Update docstrings in colour.recovery package.

Author: KelSolaar

colour/recovery/__init__.py

@@ -119,8 +119,8 @@ def XYZ_to_sd(
     **kwargs: Any,
 ) -> SpectralDistribution:
     """
-    Recover the spectral distribution of given *CIE XYZ* tristimulus
-    values using given method.
+    Recover the spectral distribution of specified *CIE XYZ* tristimulus
+    values using specified method.
 
     Parameters
     ----------
@@ -186,7 +186,7 @@ def XYZ_to_sd(
     | ``XYZ``    | [0, 1]                | [0, 1]        |
     +------------+-----------------------+---------------+
 
-    -   *Smits (1999)* method will internally convert given *CIE XYZ*
+    -   *Smits (1999)* method will internally convert specified *CIE XYZ*
         tristimulus values to *sRGB* colourspace array assuming equal energy
         illuminant *E*.
 

colour/recovery/datasets/otsu2018.py

@@ -1320,6 +1320,6 @@
     ]
 )
 """
-Array describing how to select the appropriate cluster for given *CIE xy*
+Array describing how to select the appropriate cluster for specified *CIE xy*
 chromaticity coordinates.
 """

colour/recovery/jakob2019.py

@@ -142,7 +142,7 @@ def sd_Jakob2019(
     coefficients: ArrayLike, shape: SpectralShape = SPECTRAL_SHAPE_JAKOB2019
 ) -> SpectralDistribution:
     """
-    Return a spectral distribution following the spectral model given by
+    Generate a spectral distribution following the spectral model specified by
     *Jakob and Hanika (2019)*.
 
     Parameters
@@ -241,7 +241,7 @@ def error_function(
 ):
     """
     Compute :math:`\\Delta E_{76}` between the target colour and the colour
-    defined by given spectral model, along with its gradient.
+    defined by specified spectral model, along with its gradient.
 
     Parameters
     ----------
@@ -340,7 +340,7 @@ def dimensionalise_coefficients(
     coefficients: ArrayLike, shape: SpectralShape
 ) -> NDArrayFloat:
     """
-    Rescale the dimensionless coefficients to given spectral shape.
+    Rescale the dimensionless coefficients to specified spectral shape.
 
     A dimensionless form of the reflectance spectral model is used in the
     optimisation process. Instead of the usual spectral shape, specified in
@@ -437,7 +437,7 @@ def find_coefficients_Jakob2019(
     Returns
     -------
     :class:`tuple`
-        Tuple of computed coefficients that best fit the given colour and
+        Tuple of computed coefficients that best fit the specified colour and
         :math:`\\Delta E_{76}` between the target colour and the colour
         corresponding to the computed coefficients.
 
@@ -555,8 +555,8 @@ def XYZ_to_sd_Jakob2019(
     additional_data: bool = False,
 ) -> Tuple[SpectralDistribution, float] | SpectralDistribution:
     """
-    Recover the spectral distribution of given *CIE XYZ* tristimulus values
-    using *Jakob and Hanika (2019)* method.
+    Recover the spectral distribution of specified *CIE XYZ* tristimulus
+    values using *Jakob and Hanika (2019)* method.
 
     Parameters
     ----------
@@ -873,8 +873,8 @@ def generate(
         print_callable: Callable = print,
     ) -> None:
         """
-        Generate the lookup table data for given *RGB* colourspace, colour
-        matching functions, illuminant and given size.
+        Generate the lookup table data for specified *RGB* colourspace, colour
+        matching functions, illuminant and specified size.
 
         Parameters
         ----------
@@ -1023,7 +1023,7 @@ def optimize(
 
     def RGB_to_coefficients(self, RGB: ArrayLike) -> NDArrayFloat:
         """
-        Look up a given *RGB* colourspace array and return corresponding
+        Look up a specified *RGB* colourspace array and return corresponding
         coefficients. Interpolation is used for colours not on the table grid.
 
         Parameters
@@ -1083,7 +1083,7 @@ def RGB_to_sd(
         self, RGB: ArrayLike, shape: SpectralShape = SPECTRAL_SHAPE_JAKOB2019
     ) -> SpectralDistribution:
         """
-        Look up a given *RGB* colourspace array and return the corresponding
+        Look up a specified *RGB* colourspace array and return the corresponding
         spectral distribution.
 
         Parameters

colour/recovery/jiang2013.py

@@ -100,7 +100,7 @@ def PCA_Jiang2013(
     | Tuple[NDArrayFloat, NDArrayFloat, NDArrayFloat]
 ):
     """
-    Perform the *Principal Component Analysis* (PCA) on given camera *RGB*
+    Perform the *Principal Component Analysis* (PCA) on specified camera *RGB*
     sensitivities.
 
     Parameters
@@ -138,7 +138,7 @@ def PCA_Jiang2013(
     def normalised_sensitivity(
         msds: MultiSpectralDistributions, channel: str
     ) -> NDArrayFloat:
-        """Return a normalised camera *RGB* sensitivity."""
+        """Generate a normalised camera *RGB* sensitivity."""
 
         sensitivity = cast(SpectralDistribution, msds.signals[channel].copy())
 
@@ -176,7 +176,7 @@ def RGB_to_sd_camera_sensitivity_Jiang2013(
     shape: SpectralShape | None = None,
 ) -> SpectralDistribution:
     """
-    Recover a single camera *RGB* sensitivity for given camera *RGB* values
+    Recover a single camera *RGB* sensitivity for specified camera *RGB* values
     using *Jiang et al. (2013)* method.
 
     Parameters
@@ -308,8 +308,8 @@ def RGB_to_msds_camera_sensitivities_Jiang2013(
     shape: SpectralShape | None = None,
 ) -> MultiSpectralDistributions:
     """
-    Recover the camera *RGB* sensitivities for given camera *RGB* values using
-    *Jiang et al. (2013)* method.
+    Recover the camera *RGB* sensitivities for specified camera *RGB* values
+    using *Jiang et al. (2013)* method.
 
     Parameters
     ----------

colour/recovery/mallett2019.py

@@ -59,7 +59,7 @@ def spectral_primary_decomposition_Mallett2019(
 ) -> MultiSpectralDistributions:
     """
     Perform the spectral primary decomposition as described in *Mallett and
-    Yuksel (2019)* for given *RGB* colourspace.
+    Yuksel (2019)* for specified *RGB* colourspace.
 
     Parameters
     ----------
@@ -86,7 +86,7 @@ def spectral_primary_decomposition_Mallett2019(
     Returns
     -------
     :class:`colour.MultiSpectralDistributions`
-        Basis functions for given *RGB* colourspace.
+        Basis functions for specified *RGB* colourspace.
 
     References
     ----------
@@ -222,7 +222,7 @@ def RGB_to_sd_Mallett2019(
     basis_functions: MultiSpectralDistributions = MSDS_BASIS_FUNCTIONS_sRGB_MALLETT2019,
 ) -> SpectralDistribution:
     """
-    Recover the spectral distribution of given *RGB* colourspace array using
+    Recover the spectral distribution of specified *RGB* colourspace array using
     *Mallett and Yuksel (2019)* method.
 
     Parameters

colour/recovery/meng2015.py

@@ -61,7 +61,7 @@ def XYZ_to_sd_Meng2015(
     optimisation_kwargs: dict | None = None,
 ) -> SpectralDistribution:
     """
-    Recover the spectral distribution of given *CIE XYZ* tristimulus values
+    Recover the spectral distribution of specified *CIE XYZ* tristimulus values
     using *Meng et al. (2015)* method.
 
     Parameters
@@ -85,6 +85,11 @@ def XYZ_to_sd_Meng2015(
     :class:`colour.SpectralDistribution`
         Recovered spectral distribution.
 
+    Raises
+    ------
+    RuntimeError
+        If the optimisation failed.
+
     Notes
     -----
     +------------+-----------------------+---------------+

colour/recovery/otsu2018.py

@@ -251,7 +251,7 @@ def __str__(self) -> str:
 
     def select(self, xy: ArrayLike) -> int:
         """
-        Return the cluster index appropriate for the given *CIE xy*
+        Determine the cluster index appropriate for the specified *CIE xy*
         coordinates.
 
         Parameters
@@ -294,7 +294,7 @@ def select(self, xy: ArrayLike) -> int:
 
     def cluster(self, xy: ArrayLike) -> Tuple[NDArrayFloat, NDArrayFloat]:
         """
-        Return the basis functions and dataset mean for the given *CIE xy*
+        Retrieve the basis functions and dataset mean for the specified *CIE xy*
         coordinates.
 
         Parameters
@@ -367,7 +367,7 @@ def read(self, path: str | PathLike) -> None:
 
     def write(self, path: str | PathLike) -> None:
         """
-        Write the dataset to an *.npz* file at given path.
+        Write the dataset to an *.npz* file at specified path.
 
         Parameters
         ----------
@@ -444,7 +444,7 @@ def XYZ_to_sd_Otsu2018(
     clip: bool = True,
 ) -> SpectralDistribution:
     """
-    Recover the spectral distribution of given *CIE XYZ* tristimulus values
+    Recover the spectral distribution of specified *CIE XYZ* tristimulus values
     using *Otsu et al. (2018)* method.
 
     Parameters
@@ -786,7 +786,7 @@ def __str__(self) -> str:
 
     def __len__(self) -> int:
         """
-        Return the number of colours in the data.
+        Determine the number of colours in the data.
 
         Returns
         -------
@@ -798,8 +798,8 @@ def __len__(self) -> int:
 
     def origin(self, i: int, direction: int) -> float:
         """
-        Return the origin *CIE x* or *CIE y* chromaticity coordinate for given
-        index and direction.
+        Retrieve the origin *CIE x* or *CIE y* chromaticity coordinate for
+        specified index and direction.
 
         Parameters
         ----------
@@ -828,7 +828,7 @@ def origin(self, i: int, direction: int) -> float:
 
     def partition(self, axis: PartitionAxis) -> Tuple[Data_Otsu2018, Data_Otsu2018]:
         """
-        Partition the data using given partition axis.
+        Partition the data using specified partition axis.
 
         Parameters
         ----------
@@ -904,7 +904,7 @@ def PCA(self) -> None:
 
     def reconstruct(self, XYZ: ArrayLike) -> SpectralDistribution:
         """
-        Reconstruct the reflectance for the given *CIE XYZ* tristimulus
+        Reconstruct the reflectance for the specified *CIE XYZ* tristimulus
         values.
 
         Parameters
@@ -947,7 +947,7 @@ def reconstruct(self, XYZ: ArrayLike) -> SpectralDistribution:
 
     def reconstruction_error(self) -> float:
         """
-        Return the reconstruction error of the data. The error is computed by
+        Compute the reconstruction error of the data. The error is computed by
         reconstructing the reflectances for the reference *CIE XYZ* tristimulus
         values using PCA and, comparing the reconstructed reflectances against
         the reference reflectances.
@@ -1076,7 +1076,7 @@ def row(self) -> Tuple[float, float, Self, Self]:
 
     def split(self, children: Sequence[Self], axis: PartitionAxis) -> None:
         """
-        Convert the leaf node into an inner node using given children and
+        Convert the leaf node into an inner node using specified children and
         partition axis.
 
         Parameters
@@ -1110,7 +1110,7 @@ def minimise(
         Returns
         -------
         :class:`tuple`
-            Tuple of tuple of nodes created by splitting a node with a given
+            Tuple of tuple of nodes created by splitting a node with a specified
             partition, partition axis, i.e., the horizontal or vertical line,
             partitioning the 2D space in two half-planes and partition error.
         """
@@ -1172,7 +1172,7 @@ def minimise(
 
     def leaf_reconstruction_error(self) -> float:
         """
-        Return the reconstruction error of the node data. The error is
+        Compute the reconstruction error of the node data. The error is
         computed by reconstructing the reflectances for the data reference
         *CIE XYZ* tristimulus values using PCA and, comparing the reconstructed
         reflectances against the data reference reflectances.
@@ -1584,7 +1584,7 @@ def to_dataset(self) -> Dataset_Otsu2018:
         else:
 
             def add_rows(node: Node_Otsu2018, data: dict | None = None) -> dict | None:
-                """Add rows for given node and its children."""
+                """Add rows for specified node and its children."""
 
                 data = optional(data, {"rows": [], "node_to_leaf_id": {}, "leaf_id": 0})
 

colour/recovery/smits1999.py

@@ -94,7 +94,7 @@ def XYZ_to_RGB_Smits1999(XYZ: ArrayLike) -> NDArrayFloat:
 
 def RGB_to_sd_Smits1999(RGB: ArrayLike) -> SpectralDistribution:
     """
-    Recover the spectral distribution of given *RGB* colourspace array using
+    Recover the spectral distribution of specified *RGB* colourspace array using
     *Smits (1999)* method.
 
     Parameters