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


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