# colour.algebra Package¶

## Module Contents¶

colour.algebra.steps(distribution)

Returns the steps of given distribution.

Parameters: distribution (array_like) – Distribution to retrieve the steps. Distribution steps. 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. Closest $$y$$ variable element. 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. $$x$$ variable converted to ndarray. 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. Is distribution uniform. 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. $$x$$ variable iterability. 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. Is $$x$$ variable a number. bool

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. Is $$x$$ variable an integer. bool

Notes

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’]. Normalised $$x$$ variable. 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. Spherical coordinates vector (r, theta, phi). ndarray

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. Cartesian coordinates vector (x, y, z). ndarray

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. Cylindrical coordinates vector (z, theta, rho). ndarray

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. Cartesian coordinates vector (x, y, z). ndarray

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. Extrapolated points value(s). float or ndarray
interpolator

Property for self.__interpolator private attribute.

Returns: self.__interpolator object
left

Property for self.__left private attribute.

Returns: self.__left numeric
method

Property for self.__method private attribute.

Returns: self.__method unicode
right

Property for self.__right private attribute.

Returns: self.__right 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.

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. Interpolated value(s). float or ndarray
x

Property for self.__x private attribute.

Returns: self.__x array_like
y

Property for self.__y private attribute.

Returns: self.__y 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__()

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. Interpolated value(s). numeric or ndarray
x

Property for self.__x private attribute.

Returns: self.__x array_like
y

Property for self.__y private attribute.

Returns: self.__y 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. Is identity matrix. 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. Random triplets generator. 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...])]


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. Regression statistics. ndarray, ({{mn, mn-1, ..., b}, {sum_of_squares_residual}}) 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...]))