colour.algebra Package¶

Sub-Packages¶

Sub-Modules¶

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.as_array(x, shape=None, data_type=<type 'numpy.float64'>)¶

Converts given \(x\) variable to ndarray.

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

Examples

>>> as_array(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]	sastanin. (n.d.). How to make scipy.interpolate give an extrapolated result beyond the input range? Retrieved August 08, 2014, from http://stackoverflow.com/a/2745496/931625

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.

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 TC 1-38. (2005). 9.2.4 Method of interpolation for uniformly spaced independent variable. In CIE 167:2005 Recommended Practice for Tabulating Spectral Data for Use in Colour Computations (pp. 1–27). ISBN:978-3-901-90641-1

[2]	Westland, S., Ripamonti, C., & Cheung, V. (2012). Interpolation Methods. In Computational Colour Science Using MATLAB (2nd ed., pp. 29–37). ISBN:978-0-470-66569-5

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

random_triplet_generator(size, limits=array([[0, 1],

[0, 1],

[0, 1]]), random_state=<mtrand.RandomState object at 0x2b436c405930>)

Returns a generator yielding random triplets.

Parameters:	size (integer) – Generator size. limits (array_like, (3, 2)) – Random values limits on each triplet axis. random_state (RandomState) – Mersenne Twister pseudo-random number generator.
Returns:	Random triplets generator.
Return type:	generator

Notes

The doctest is assuming that np.random.RandomState() definition will return the same sequence no matter which OS or Python version is used. There is however no formal promise about the prng sequence reproducibility of either Python or *Numpy implementations: Laurent. (2012). Reproducibility of python pseudo-random numbers across systems and versions? Retrieved January 20, 2015, from http://stackoverflow.com/questions/8786084/reproducibility-of-python-pseudo-random-numbers-across-systems-and-versions

Examples

>>> from pprint import pprint
>>> prng = np.random.RandomState(4)
>>> pprint(list(random_triplet_generator(10, random_state=prng)))    
[array([ 0.9670298...,  0.5472322...,  0.9726843...]),
 array([ 0.7148159...,  0.6977288...,  0.2160895...]),
 array([ 0.9762744...,  0.0062302...,  0.2529823...]),
 array([ 0.4347915...,  0.7793829...,  0.1976850...]),
 array([ 0.8629932...,  0.9834006...,  0.1638422...]),
 array([ 0.5973339...,  0.0089861...,  0.3865712...]),
 array([ 0.0441600...,  0.9566529...,  0.4361466...]),
 array([ 0.9489773...,  0.7863059...,  0.8662893...]),
 array([ 0.1731654...,  0.0749485...,  0.6007427...]),
 array([ 0.1679721...,  0.7333801...,  0.4084438...])]

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]	Wikipedia. (n.d.). Simple linear regression. Retrieved May 24, 2014, from http://en.wikipedia.org/wiki/Simple_linear_regression

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