colour.algebra Package

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

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...]))