colour.continuous.Signal¶

class colour.continuous.Signal(data=None, domain=None, **kwargs)[source]¶

Bases: colour.continuous.abstract.AbstractContinuousFunction

Defines the base class for continuous signal.

The class implements the Signal.function() method so that evaluating the function for any independent domain \(x \in\mathbb{R}\) variable returns a corresponding range \(y \in\mathbb{R}\) variable. It adopts an interpolating function encapsulated inside an extrapolating function. The resulting function independent domain, stored as discrete values in the colour.continuous.Signal.domain attribute corresponds with the function dependent and already known range stored in the colour.continuous.Signal.range attribute.

Important

Specific documentation about getting, setting, indexing and slicing the continuous signal values is available in the Spectral Representation and Continuous Signal section.

Parameters

data (Series or Signal or array_like or dict_like, optional) – Data to be stored in the continuous signal.
domain (array_like, optional) – Values to initialise the colour.continuous.Signal.domain attribute with. If both data and domain arguments are defined, the latter with be used to initialise the colour.continuous.Signal.domain attribute.
name (unicode, optional) – Continuous signal name.
dtype (type, optional) – {np.float16, np.float32, np.float64, np.float128}, Floating point data type.
interpolator (object, optional) – Interpolator class type to use as interpolating function.
interpolator_kwargs (dict_like, optional) – Arguments to use when instantiating the interpolating function.
extrapolator (object, optional) – Extrapolator class type to use as extrapolating function.
extrapolator_kwargs (dict_like, optional) – Arguments to use when instantiating the extrapolating function.

Attributes

dtype
domain
range
interpolator
interpolator_kwargs
extrapolator
extrapolator_kwargs
function

Methods

__init__()
__str__()
__repr__()
__hash__()
__getitem__()
__setitem__()
__contains__()
__eq__()
__ne__()
arithmetical_operation()
signal_unpack_data()
fill_nan()
to_series()

Examples

Instantiation with implicit domain:

>>> range_ = np.linspace(10, 100, 10)
>>> print(Signal(range_))
[[   0.   10.]
 [   1.   20.]
 [   2.   30.]
 [   3.   40.]
 [   4.   50.]
 [   5.   60.]
 [   6.   70.]
 [   7.   80.]
 [   8.   90.]
 [   9.  100.]]

Instantiation with explicit domain:

>>> domain = np.arange(100, 1100, 100)
>>> print(Signal(range_, domain))
[[  100.    10.]
 [  200.    20.]
 [  300.    30.]
 [  400.    40.]
 [  500.    50.]
 [  600.    60.]
 [  700.    70.]
 [  800.    80.]
 [  900.    90.]
 [ 1000.   100.]]

Instantiation with a dict:

>>> print(Signal(dict(zip(domain, range_))))
[[  100.    10.]
 [  200.    20.]
 [  300.    30.]
 [  400.    40.]
 [  500.    50.]
 [  600.    60.]
 [  700.    70.]
 [  800.    80.]
 [  900.    90.]
 [ 1000.   100.]]

Instantiation with a Pandas Series:

>>> if is_pandas_installed():
...     from pandas import Series
...     print(Signal(  
...         Series(dict(zip(domain, range_)))))
[[  100.    10.]
 [  200.    20.]
 [  300.    30.]
 [  400.    40.]
 [  500.    50.]
 [  600.    60.]
 [  700.    70.]
 [  800.    80.]
 [  900.    90.]
 [ 1000.   100.]]

Retrieving domain y variable for arbitrary range x variable:

>>> x = 150
>>> range_ = np.sin(np.linspace(0, 1, 10))
>>> Signal(range_, domain)[x]  
0.0359701...
>>> x = np.linspace(100, 1000, 3)
>>> Signal(range_, domain)[x]  
array([  ...,   4.7669395...e-01,   8.4147098...e-01])

Using an alternative interpolating function:

>>> x = 150
>>> from colour.algebra import CubicSplineInterpolator
>>> Signal(
...     range_,
...     domain,
...     interpolator=CubicSplineInterpolator)[x]  
0.0555274...
>>> x = np.linspace(100, 1000, 3)
>>> Signal(
...     range_,
...     domain,
...     interpolator=CubicSplineInterpolator)[x]  
array([ 0.        ,  0.4794253...,  0.8414709...])

__init__(data=None, domain=None, **kwargs)[source]¶

property dtype¶

Getter and setter property for the continuous signal dtype.

Parameters: value (type) – Value to set the continuous signal dtype with.
Returns: Continuous signal dtype.
Return type: type

property domain¶

Getter and setter property for the continuous signal independent domain \(x\) variable.

Parameters: value (array_like) – Value to set the continuous signal independent domain \(x\) variable with.
Returns: Continuous signal independent domain \(x\) variable.
Return type: ndarray

property range¶

Getter and setter property for the continuous signal corresponding range \(y\) variable.

Parameters: value (array_like) – Value to set the continuous signal corresponding range \(y\) variable with.
Returns: Continuous signal corresponding range \(y\) variable.
Return type: ndarray

property interpolator¶

Getter and setter property for the continuous signal interpolator type.

Parameters: value (type) – Value to set the continuous signal interpolator type with.
Returns: Continuous signal interpolator type.
Return type: type

property interpolator_kwargs¶

Getter and setter property for the continuous signal interpolator instantiation time arguments.

Parameters: value (dict) – Value to set the continuous signal interpolator instantiation time arguments to.
Returns: Continuous signal interpolator instantiation time arguments.
Return type: dict

property extrapolator¶

Getter and setter property for the continuous signal extrapolator type.

Parameters: value (type) – Value to set the continuous signal extrapolator type with.
Returns: Continuous signal extrapolator type.
Return type: type

property extrapolator_kwargs¶

Getter and setter property for the continuous signal extrapolator instantiation time arguments.

Parameters: value (dict) – Value to set the continuous signal extrapolator instantiation time arguments to.
Returns: Continuous signal extrapolator instantiation time arguments.
Return type: dict

property function¶

Getter property for the continuous signal callable.

Returns: Continuous signal callable.
Return type: callable

__str__()[source]¶

Returns a formatted string representation of the continuous signal.

Returns: Formatted string representation.
Return type: unicode

Examples

>>> range_ = np.linspace(10, 100, 10)
>>> print(Signal(range_))
[[   0.   10.]
 [   1.   20.]
 [   2.   30.]
 [   3.   40.]
 [   4.   50.]
 [   5.   60.]
 [   6.   70.]
 [   7.   80.]
 [   8.   90.]
 [   9.  100.]]

__repr__()[source]¶

Returns an evaluable string representation of the continuous signal.

Returns: Evaluable string representation.
Return type: unicode

Examples

>>> range_ = np.linspace(10, 100, 10)
>>> Signal(range_)  
Signal([[   0.,   10.],
        [   1.,   20.],
        [   2.,   30.],
        [   3.,   40.],
        [   4.,   50.],
        [   5.,   60.],
        [   6.,   70.],
        [   7.,   80.],
        [   8.,   90.],
        [   9.,  100.]],
       interpolator=KernelInterpolator,
       interpolator_kwargs={},
       extrapolator=Extrapolator,
       extrapolator_kwargs={...})

__hash__()[source]¶

Returns the abstract continuous function hash.

Returns: Object hash.
Return type: int

__getitem__(x)[source]¶

Returns the corresponding range \(y\) variable for independent domain \(x\) variable.

Parameters: x (numeric, array_like or slice) – Independent domain \(x\) variable.
Returns: math:y range value.
Return type: numeric or ndarray

Examples

>>> range_ = np.linspace(10, 100, 10)
>>> signal = Signal(range_)
>>> print(signal)
[[   0.   10.]
 [   1.   20.]
 [   2.   30.]
 [   3.   40.]
 [   4.   50.]
 [   5.   60.]
 [   6.   70.]
 [   7.   80.]
 [   8.   90.]
 [   9.  100.]]
>>> signal[0]
10.0
>>> signal[np.array([0, 1, 2])]
array([ 10.,  20.,  30.])
>>> signal[0:3]
array([ 10.,  20.,  30.])
>>> signal[np.linspace(0, 5, 5)]  
array([ 10.        ,  22.8348902...,  34.8004492...,  47.5535392...,  60.        ])

__setitem__(x, y)[source]¶

Sets the corresponding range \(y\) variable for independent domain \(x\) variable.

Parameters

x (numeric, array_like or slice) – Independent domain \(x\) variable.
y (numeric or ndarray) – Corresponding range \(y\) variable.

Examples

>>> range_ = np.linspace(10, 100, 10)
>>> signal = Signal(range_)
>>> print(signal)
[[   0.   10.]
 [   1.   20.]
 [   2.   30.]
 [   3.   40.]
 [   4.   50.]
 [   5.   60.]
 [   6.   70.]
 [   7.   80.]
 [   8.   90.]
 [   9.  100.]]
>>> signal[0] = 20
>>> signal[0]
20.0
>>> signal[np.array([0, 1, 2])] = 30
>>> signal[np.array([0, 1, 2])]
array([ 30.,  30.,  30.])
>>> signal[0:3] = 40
>>> signal[0:3]
array([ 40.,  40.,  40.])
>>> signal[np.linspace(0, 5, 5)] = 50
>>> print(signal)
[[   0.     50.  ]
 [   1.     40.  ]
 [   1.25   50.  ]
 [   2.     40.  ]
 [   2.5    50.  ]
 [   3.     40.  ]
 [   3.75   50.  ]
 [   4.     50.  ]
 [   5.     50.  ]
 [   6.     70.  ]
 [   7.     80.  ]
 [   8.     90.  ]
 [   9.    100.  ]]
>>> signal[np.array([0, 1, 2])] = np.array([10, 20, 30])
>>> print(signal)
[[   0.     10.  ]
 [   1.     20.  ]
 [   1.25   50.  ]
 [   2.     30.  ]
 [   2.5    50.  ]
 [   3.     40.  ]
 [   3.75   50.  ]
 [   4.     50.  ]
 [   5.     50.  ]
 [   6.     70.  ]
 [   7.     80.  ]
 [   8.     90.  ]
 [   9.    100.  ]]

__contains__(x)[source]¶

Returns whether the continuous signal contains given independent domain \(x\) variable.

Parameters: x (numeric, array_like or slice) – Independent domain \(x\) variable.
Returns: Is \(x\) domain value contained.
Return type: bool

Examples

>>> range_ = np.linspace(10, 100, 10)
>>> signal = Signal(range_)
>>> 0 in signal
True
>>> 0.5 in signal
True
>>> 1000 in signal
False

__eq__(other)[source]¶

Returns whether the continuous signal is equal to given other object.

Parameters: other (object) – Object to test whether it is equal to the continuous signal.
Returns: Is given object equal to the continuous signal.
Return type: bool

Examples

>>> range_ = np.linspace(10, 100, 10)
>>> signal_1 = Signal(range_)
>>> signal_2 = Signal(range_)
>>> signal_1 == signal_2
True
>>> signal_2[0] = 20
>>> signal_1 == signal_2
False
>>> signal_2[0] = 10
>>> signal_1 == signal_2
True
>>> from colour.algebra import CubicSplineInterpolator
>>> signal_2.interpolator = CubicSplineInterpolator
>>> signal_1 == signal_2
False

__ne__(other)[source]¶

Returns whether the continuous signal is not equal to given other object.

Parameters: other (object) – Object to test whether it is not equal to the continuous signal.
Returns: Is given object not equal to the continuous signal.
Return type: bool

Examples

>>> range_ = np.linspace(10, 100, 10)
>>> signal_1 = Signal(range_)
>>> signal_2 = Signal(range_)
>>> signal_1 != signal_2
False
>>> signal_2[0] = 20
>>> signal_1 != signal_2
True
>>> signal_2[0] = 10
>>> signal_1 != signal_2
False
>>> from colour.algebra import CubicSplineInterpolator
>>> signal_2.interpolator = CubicSplineInterpolator
>>> signal_1 != signal_2
True

arithmetical_operation(a, operation, in_place=False)[source]¶

Performs given arithmetical operation with \(a\) operand, the operation can be either performed on a copy or in-place.

Parameters

a (numeric or ndarray or Signal) – Operand.
operation (object) – Operation to perform.
in_place (bool, optional) – Operation happens in place.

Returns

Continuous signal.

Return type

Signal

Examples

Adding a single numeric variable:

>>> range_ = np.linspace(10, 100, 10)
>>> signal_1 = Signal(range_)
>>> print(signal_1)
[[   0.   10.]
 [   1.   20.]
 [   2.   30.]
 [   3.   40.]
 [   4.   50.]
 [   5.   60.]
 [   6.   70.]
 [   7.   80.]
 [   8.   90.]
 [   9.  100.]]
>>> print(signal_1.arithmetical_operation(10, '+', True))
[[   0.   20.]
 [   1.   30.]
 [   2.   40.]
 [   3.   50.]
 [   4.   60.]
 [   5.   70.]
 [   6.   80.]
 [   7.   90.]
 [   8.  100.]
 [   9.  110.]]

Adding an array_like variable:

>>> a = np.linspace(10, 100, 10)
>>> print(signal_1.arithmetical_operation(a, '+', True))
[[   0.   30.]
 [   1.   50.]
 [   2.   70.]
 [   3.   90.]
 [   4.  110.]
 [   5.  130.]
 [   6.  150.]
 [   7.  170.]
 [   8.  190.]
 [   9.  210.]]

Adding a colour.continuous.Signal class:

>>> signal_2 = Signal(range_)
>>> print(signal_1.arithmetical_operation(signal_2, '+', True))
[[   0.   40.]
 [   1.   70.]
 [   2.  100.]
 [   3.  130.]
 [   4.  160.]
 [   5.  190.]
 [   6.  220.]
 [   7.  250.]
 [   8.  280.]
 [   9.  310.]]

static signal_unpack_data(data=None, domain=None, dtype=None)[source]¶

Unpack given data for continuous signal instantiation.

Parameters

data (Series or Signal or array_like or dict_like, optional) – Data to unpack for continuous signal instantiation.
domain (array_like, optional) – Values to initialise the colour.continuous.Signal.domain attribute with. If both data and domain arguments are defined, the latter will be used to initialise the colour.continuous.Signal.domain attribute.
dtype (type, optional) – {np.float16, np.float32, np.float64, np.float128}, Floating point data type.

Returns

Independent domain \(x\) variable and corresponding range \(y\) variable unpacked for continuous signal instantiation.

Return type

tuple

Examples

Unpacking using implicit domain:

>>> range_ = np.linspace(10, 100, 10)
>>> domain, range_ = Signal.signal_unpack_data(range_)
>>> print(domain)
[ 0.  1.  2.  3.  4.  5.  6.  7.  8.  9.]
>>> print(range_)
[  10.   20.   30.   40.   50.   60.   70.   80.   90.  100.]

Unpacking using explicit domain:

>>> domain = np.arange(100, 1100, 100)
>>> domain, range = Signal.signal_unpack_data(range_, domain)
>>> print(domain)
[  100.   200.   300.   400.   500.   600.   700.   800.   900.  1000.]
>>> print(range_)
[  10.   20.   30.   40.   50.   60.   70.   80.   90.  100.]

Unpacking using a dict:

>>> domain, range_ = Signal.signal_unpack_data(
...     dict(zip(domain, range_)))
>>> print(domain)
[  100.   200.   300.   400.   500.   600.   700.   800.   900.  1000.]
>>> print(range_)
[  10.   20.   30.   40.   50.   60.   70.   80.   90.  100.]

Unpacking using a Pandas Series:

>>> if is_pandas_installed():
...     from pandas import Series
...     domain, range = Signal.signal_unpack_data(
...         Series(dict(zip(domain, range_))))
... 
>>> print(domain)  
[  100.   200.   300.   400.   500.   600.   700.   800.   900.  1000.]
>>> print(range_)  
[  10.   20.   30.   40.   50.   60.   70.   80.   90.  100.]

Unpacking using a colour.continuous.Signal class:

>>> domain, range_ = Signal.signal_unpack_data(
...     Signal(range_, domain))
>>> print(domain)
[  100.   200.   300.   400.   500.   600.   700.   800.   900.  1000.]
>>> print(range_)
[  10.   20.   30.   40.   50.   60.   70.   80.   90.  100.]

fill_nan(method='Interpolation', default=0)[source]¶

Fill NaNs in independent domain \(x\) variable and corresponding range \(y\) variable using given method.

Parameters

method (unicode, optional) – {‘Interpolation’, ‘Constant’}, Interpolation method linearly interpolates through the NaNs, Constant method replaces NaNs with default.
default (numeric, optional) – Value to use with the Constant method.

Returns

NaNs filled continuous signal.

Return type

Signal

Examples

>>> range_ = np.linspace(10, 100, 10)
>>> signal = Signal(range_)
>>> signal[3:7] = np.nan
>>> print(signal)
[[   0.   10.]
 [   1.   20.]
 [   2.   30.]
 [   3.   nan]
 [   4.   nan]
 [   5.   nan]
 [   6.   nan]
 [   7.   80.]
 [   8.   90.]
 [   9.  100.]]
>>> print(signal.fill_nan())
[[   0.   10.]
 [   1.   20.]
 [   2.   30.]
 [   3.   40.]
 [   4.   50.]
 [   5.   60.]
 [   6.   70.]
 [   7.   80.]
 [   8.   90.]
 [   9.  100.]]
>>> signal[3:7] = np.nan
>>> print(signal.fill_nan(method='Constant'))
[[   0.   10.]
 [   1.   20.]
 [   2.   30.]
 [   3.    0.]
 [   4.    0.]
 [   5.    0.]
 [   6.    0.]
 [   7.   80.]
 [   8.   90.]
 [   9.  100.]]

to_series()[source]¶

Converts the continuous signal to a Pandas Series class instance.

Returns: Continuous signal as a Pandas Series class instance.
Return type: Series

Examples

>>> if is_pandas_installed():
...     range_ = np.linspace(10, 100, 10)
...     signal = Signal(range_)
...     print(signal.to_series())  
0.0     10.0
1.0     20.0
2.0     30.0
3.0     40.0
4.0     50.0
5.0     60.0
6.0     70.0
7.0     80.0
8.0     90.0
9.0    100.0
Name: Signal (...), dtype: float64