colour.algebra Package — Colour 0.3.0 documentation

# colour.algebra Package

## Sub-Packages

- colour.algebra.coordinates Package
  - Sub-Modules
    - colour.algebra.coordinates.transformations Module
      - Coordinates System Transformations
  - Module Contents

## Sub-Modules

- colour.algebra.common Module
  - Algebra Common Utilities
- colour.algebra.extrapolation Module
  - Extrapolation
- colour.algebra.interpolation Module
  - Interpolation
- colour.algebra.matrix Module
  - Matrix Helpers
- colour.algebra.regression Module
  - Regression Analysis

## Module Contents

`colour.algebra.` `steps`(distribution)

  Returns the steps of given distribution.

  Parameters: | distribution (array_like) – Distribution to retrieve the steps.
  Returns: | Distribution steps.
  Return type: | tuple

  Examples

  Uniformly spaced variable:

      >>> y = np.array([1, 2, 3, 4, 5])
      >>> steps(y)
      (1,)

  Non-uniformly spaced variable:

      >>> y = np.array([1, 2, 3, 4, 8])
      >>> steps(y)
      (1, 4)

`colour.algebra.` `closest`(y, x)

  Returns closest \(y\) variable element to reference \(x\) variable.

  Parameters: | y (array_like) – Variable to search for the closest element. x (numeric) – Reference variable.
  Returns: | Closest \(y\) variable element.
  Return type: | numeric

  Examples

      >>> y = np.array([24.31357115, 63.62396289, 55.71528816, 62.70988028, 46.84480573, 25.40026416])
      >>> closest(y, 63)
      62.70988028

`colour.algebra.` `to_ndarray`(x, data_type=<type 'numpy.float64'>)

  Converts given \(x\) variable to ndarray.

  Parameters: | x (object) – Variable to convert. data_type (dtype) – ndarray data type.
  Returns: | \(x\) variable converted to ndarray.
  Return type: | ndarray

  Examples

      >>> to_ndarray(1)
      array([ 1.])

`colour.algebra.` `is_uniform`(distribution)

  Returns if given distribution is uniform.

  Parameters: | distribution (array_like) – Distribution to check for uniformity.
  Returns: | Is distribution uniform.
  Return type: | bool

  Examples

  Uniformly spaced variable:

      >>> y = np.array([1, 2, 3, 4, 5])
      >>> is_uniform(y)
      True

  Non-uniformly spaced variable:

      >>> y = np.array([1, 2, 3.1415, 4, 5])
      >>> is_uniform(y)
      False

`colour.algebra.` `is_iterable`(x)

  Returns if given \(x\) variable is iterable.

  Parameters: | x (object) – Variable to check the iterability.
  Returns: | \(x\) variable iterability.
  Return type: | bool

  Examples

      >>> is_iterable([1, 2, 3])
      True
      >>> is_iterable(1)
      False

`colour.algebra.` `is_numeric`(x)

  Returns if given \(x\) variable is a number.

  Parameters: | x (object) – Variable to check.
  Returns: | Is \(x\) variable a number.
  Return type: | bool

  See also

  `is_integer()`

  Examples

      >>> is_numeric(1)
      True
      >>> is_numeric((1,))
      False

`colour.algebra.` `is_integer`(x)

  Returns if given \(x\) variable is an integer under given threshold.

  Parameters: | x (object) – Variable to check.
  Returns: | Is \(x\) variable an integer.
  Return type: | bool

  Notes

  - The determination threshold is defined by the `colour.algebra.common.INTEGER_THRESHOLD` attribute.

  See also

  `is_numeric()`

  Examples

      >>> is_integer(1)
      True
      >>> is_integer(1.01)
      False

`colour.algebra.` `normalise`(x, factor=1, clip=True)

  Normalises given array_like \(x\) variable values and optionally clip them between.

  Parameters: | x (array_like) – \(x\) variable to normalise. factor (numeric, optional) – Normalization factor clip (bool, optional) – Clip values between in domain [0, ‘factor’].
  Returns: | Normalised \(x\) variable.
  Return type: | ndarray

  Examples

      >>> x = np.array([0.48224885, 0.31651974, 0.22070513])
      >>> normalise(x)
      array([ 1.        ,  0.6563411...,  0.4576581...])

`colour.algebra.` `cartesian_to_spherical`(vector)

  Transforms given Cartesian coordinates vector to Spherical coordinates.

  Parameters: | vector (array_like) – Cartesian coordinates vector (x, y, z) to transform.
  Returns: | Spherical coordinates vector (r, theta, phi).
  Return type: | ndarray

  See also

  `spherical_to_cartesian()`, `cartesian_to_cylindrical()`, `cylindrical_to_cartesian()`

  Examples

      >>> vector = np.array([3, 1, 6])
      >>> cartesian_to_spherical(vector)
      array([ 6.7823299...,  1.0857465...,  0.3217505...])

`colour.algebra.` `spherical_to_cartesian`(vector)

  Transforms given Spherical coordinates vector to Cartesian coordinates.

  Parameters: | vector (array_like) – Spherical coordinates vector (r, theta, phi) to transform.
  Returns: | Cartesian coordinates vector (x, y, z).
  Return type: | ndarray

  See also

  `cartesian_to_spherical()`, `cartesian_to_cylindrical()`, `cylindrical_to_cartesian()`

  Examples

      >>> vector = np.array([6.78232998, 1.08574654, 0.32175055])
      >>> spherical_to_cartesian(vector)
      array([ 3.        ,  0.9999999...,  6.        ])

`colour.algebra.` `cartesian_to_cylindrical`(vector)

  Transforms given Cartesian coordinates vector to Cylindrical coordinates.

  Parameters: | vector (array_like) – Cartesian coordinates vector (x, y, z) to transform.
  Returns: | Cylindrical coordinates vector (z, theta, rho).
  Return type: | ndarray

  See also

  `cartesian_to_spherical()`, `spherical_to_cartesian()`, `cylindrical_to_cartesian()`

  Examples

      >>> vector = np.array([3, 1, 6])
      >>> cartesian_to_cylindrical(vector)
      array([ 6.        ,  0.3217505...,  3.1622776...])

`colour.algebra.` `cylindrical_to_cartesian`(vector)

  Transforms given Cylindrical coordinates vector to Cartesian coordinates.

  Parameters: | vector (array_like) – Cylindrical coordinates vector (z, theta, rho) to transform.
  Returns: | Cartesian coordinates vector (x, y, z).
  Return type: | ndarray

  See also

  `cartesian_to_spherical()`, `spherical_to_cartesian()`, `cartesian_to_cylindrical()`

  Examples

      >>> vector = np.array([6, 0.32175055, 3.16227766])
      >>> cylindrical_to_cartesian(vector)
      array([ 3.        ,  0.9999999...,  6.        ])

class `colour.algebra.` `Extrapolator1d`(interpolator=None, method=u'Linear', left=None, right=None)

  Bases: `object`

  Extrapolates the 1-D function of given interpolator.

  The Extrapolator1d acts as a wrapper around a given Colour or scipy interpolator class instance with compatible signature. Two extrapolation methods are available:

  - Linear: Linearly extrapolates given points using the slope defined by the interpolator boundaries (xi[0], xi[1]) if x < xi[0] and (xi[-1], xi[-2]) if x > xi[-1].
  - Constant: Extrapolates given points by assigning the interpolator boundaries values xi[0] if x < xi[0] and xi[-1] if x > xi[-1].

  Specifying the left and right arguments takes precedence on the chosen extrapolation method and will assign the respective left and right values to the given points.

  Parameters: | interpolator (object) – Interpolator object. method (unicode, optional) – (‘Linear’, ‘Constant’), Extrapolation method. left (numeric, optional) – Value to return for x < xi[0]. right (numeric, optional) – Value to return for x > xi[-1].

  `__class__`()

  Notes

  The interpolator must define x and y attributes.

  References

  [1] | http://stackoverflow.com/a/2745496/931625 (Last accessed 8 August 2014)

  Examples

  Extrapolating a single numeric variable:

      >>> from colour.algebra import LinearInterpolator1d
      >>> x = np.array([3, 4, 5])
      >>> y = np.array([1, 2, 3])
      >>> interpolator = LinearInterpolator1d(x, y)
      >>> extrapolator = Extrapolator1d(interpolator)
      >>> extrapolator(1)
      -1.0

  Extrapolating an array_like variable:

      >>> extrapolator(np.array([6, 7 , 8]))
      array([ 4.,  5.,  6.])

  Using the Constant extrapolation method:

      >>> x = np.array([3, 4, 5])
      >>> y = np.array([1, 2, 3])
      >>> interpolator = LinearInterpolator1d(x, y)
      >>> extrapolator = Extrapolator1d(interpolator, method='Constant')
      >>> extrapolator(np.array([0.1, 0.2, 8, 9]))
      array([ 1.,  1.,  3.,  3.])

  Using defined left boundary and Constant extrapolation method:

      >>> x = np.array([3, 4, 5])
      >>> y = np.array([1, 2, 3])
      >>> interpolator = LinearInterpolator1d(x, y)
      >>> extrapolator = Extrapolator1d(interpolator, method='Constant', left=0)
      >>> extrapolator(np.array([0.1, 0.2, 8, 9]))
      array([ 0.,  0.,  3.,  3.])

  `__call__`(x)

    Evaluates the Extrapolator1d at given point(s).

    Parameters: | x (numeric or array_like) – Point(s) to evaluate the Extrapolator1d at.
    Returns: | Extrapolated points value(s).
    Return type: | float or ndarray

  `interpolator`

    Property for self.__interpolator private attribute.

    Returns: | self.__interpolator
    Return type: | object

  `left`

    Property for self.__left private attribute.

    Returns: | self.__left
    Return type: | numeric

  `method`

    Property for self.__method private attribute.

    Returns: | self.__method
    Return type: | unicode

  `right`

    Property for self.__right private attribute.

    Returns: | self.__right
    Return type: | numeric

class `colour.algebra.` `LinearInterpolator1d`(x=None, y=None)

  Bases: `object`

  Linearly interpolates a 1-D function.

  Parameters: | x (ndarray) – Independent \(x\) variable values corresponding with \(y\) variable. y (ndarray) – Dependent and already known \(y\) variable values to interpolate.

  `__call__`()

  Notes

  This class is a wrapper around numpy.interp definition.

  See also

  `SpragueInterpolator`

  Examples

  Interpolating a single numeric variable:

      >>> y = np.array([5.9200, 9.3700, 10.8135, 4.5100, 69.5900, 27.8007, 86.0500])
      >>> x = np.arange(len(y))
      >>> f = LinearInterpolator1d(x, y)
      >>> # Doctests ellipsis for Python 2.x compatibility.
      >>> f(0.5)
      7.64...

  Interpolating an array_like variable:

      >>> f([0.25, 0.75])
      array([ 6.7825,  8.5075])

  `__call__`(x)

    Evaluates the interpolating polynomial at given point(s).

    Parameters: | x (numeric or array_like) – Point(s) to evaluate the interpolant at.
    Returns: | Interpolated value(s).
    Return type: | float or ndarray

  `x`

    Property for self.__x private attribute.

    Returns: | self.__x
    Return type: | array_like

  `y`

    Property for self.__y private attribute.

    Returns: | self.__y
    Return type: | array_like

class `colour.algebra.` `SplineInterpolator`(*args, **kwargs)

  Bases: `scipy.interpolate.interpolate.interp1d`

  Interpolates a 1-D function using cubic spline interpolation.

  Notes

  This class is a wrapper around scipy.interpolate.interp1d class.

class `colour.algebra.` `SpragueInterpolator`(x=None, y=None)

  Bases: `object`

  Constructs a fifth-order polynomial that passes through \(y\) dependent variable.

  The Sprague (1880) method is recommended by the CIE for interpolating functions having a uniformly spaced independent variable.

  Parameters: | x (array_like) – Independent \(x\) variable values corresponding with \(y\) variable. y (array_like) – Dependent and already known \(y\) variable values to interpolate.

  `__call__`()

  See also

  `LinearInterpolator1d`

  Notes

  The minimum number \(k\) of data points required along the interpolation axis is \(k=6\).

  References

  [1] | CIE 167:2005 Recommended Practice for Tabulating Spectral Data for Use in Colour Computations: 9.2.4 Method of interpolation for uniformly spaced independent variable

  [2] | Stephen Westland, Caterina Ripamonti, Vien Cheung, Computational Colour Science Using MATLAB, 2nd Edition, The Wiley-IS&T Series in Imaging Science and Technology, published July 2012, ISBN-13: 978-0-470-66569-5, page 33.

  Examples

  Interpolating a single numeric variable:

      >>> y = np.array([5.9200, 9.3700, 10.8135, 4.5100, 69.5900, 27.8007, 86.0500])
      >>> x = np.arange(len(y))
      >>> f = SpragueInterpolator(x, y)
      >>> f(0.5)
      7.2185025...

  Interpolating an array_like variable:

      >>> f([0.25, 0.75])
      array([ 6.7295161...,  7.8140625...])

  `SPRAGUE_C_COEFFICIENTS` = array([[ 884, -1960, 3033, -2648, 1080, -180], [ 508, -540, 488, -367, 144, -24], [ -24, 144, -367, 488, -540, 508], [ -180, 1080, -2648, 3033, -1960, 884]])
  `__call__`(x)

    Evaluates the interpolating polynomial at given point(s).

    Parameters: | x (numeric or array_like) – Point(s) to evaluate the interpolant at.
    Returns: | Interpolated value(s).
    Return type: | numeric or ndarray

  `x`

    Property for self.__x private attribute.

    Returns: | self.__x
    Return type: | array_like

  `y`

    Property for self.__y private attribute.

    Returns: | self.__y
    Return type: | array_like

`colour.algebra.` `is_identity`(x, n=3)

  Returns if given array_like variable \(x\) is an identity matrix.

  Parameters: | x (array_like, (N)) – Variable \(x\) to test. n (int, optional) – Matrix dimension.
  Returns: | Is identity matrix.
  Return type: | bool

  Examples

      >>> is_identity(np.array([1, 0, 0, 0, 1, 0, 0, 0, 1]).reshape(3, 3))
      True
      >>> is_identity(np.array([1, 2, 0, 0, 1, 0, 0, 0, 1]).reshape(3, 3))
      False

`colour.algebra.` `linear_regression`(y, x=None, additional_statistics=False)

  Performs the statistics computation about the ideal trend line from given data using the least-squares method.

  The equation of the line is \(y=b+mx\) or \(y=b+m1x1+m1x2+...+mnxn\) where the dependent variable \(y\) value is a function of the independent variable \(x\) values.

  Parameters: | y (array_like) – Dependent and already known \(y\) variable values used to curve fit an ideal trend line. x (array_like, optional) – Independent \(x\) variable(s) values corresponding with \(y\) variable. additional_statistics (ndarray) – Output additional regression statistics, by default only the \(b\) variable and \(m\) coefficients are returned.
  Returns: | Regression statistics.
  Return type: | ndarray, ({{mn, mn-1, ..., b}, {sum_of_squares_residual}})
  Raises: | `ValueError` – If \(y\) and \(x\) variables have incompatible dimensions.

  References

  [2] | http://en.wikipedia.org/wiki/Simple_linear_regression (Last accessed 24 May 2014)

  Examples

  Linear regression with the dependent and already known \(y\) variable:

      >>> y = np.array([1, 2, 1, 3, 2, 3, 3, 4, 4, 3])
      >>> linear_regression(y)
      array([ 0.2909090...,  1.        ])

  Linear regression with the dependent \(y\) variable and independent \(x\) variable:

      >>> x1 = np.array([40, 45, 38, 50, 48, 55, 53, 55, 58, 40])
      >>> linear_regression(y, x1)
      array([ 0.1225194..., -3.3054357...])

  Multiple linear regression with the dependent \(y\) variable and multiple independent \(x_i\) variables:

      >>> x2 = np.array([25, 20, 30, 30, 28, 30, 34, 36, 32, 34])
      >>> linear_regression(y, tuple(zip(x1, x2)))
      array([ 0.0998002...,  0.0876257..., -4.8303807...])

  Multiple linear regression with additional statistics:

      >>> linear_regression(y, tuple(zip(x1, x2)), True)
      (array([ 0.0998002...,  0.0876257..., -4.8303807...]), array([ 2.1376249...]))