common¶
Common processing tasks.

class
copper.common.
Windower
(length)¶ Windows incoming data to a specific length.
Takes new input data and combines with past data to maintain a sliding window with optional overlap. The window length is specified directly, so the overlap depends on the length of the input.
The input length may change on each iteration, but the
Windower
must be cleared before the number of channels can change.Parameters: length (int) – Total number of samples to output on each iteration. This must be at least as large as the number of samples input to the windower on each iteration. See also
copper.common.Ensure2D
 Ensure input to the windower is 2D.
Examples
Basic use of a windower:
>>> import copper >>> import numpy as np >>> win = copper.Windower(4) >>> win.process(np.array([[1, 2], [3, 4]])) array([[ 0., 0., 1., 2.], [ 0., 0., 3., 4.]]) >>> win.process(np.array([[7, 8], [5, 6]])) array([[ 1., 2., 7., 8.], [ 3., 4., 5., 6.]]) >>> win.clear() >>> win.process(np.array([[1, 2], [3, 4]])) array([[ 0., 0., 1., 2.], [ 0., 0., 3., 4.]])
If your data is 1dimensional (shape
(n_samples,)
), use anEnsure2D
block in front of theWindower
:>>> win = copper.Windower(4) >>> p = copper.Pipeline([copper.Ensure2D(), win]) >>> p.process(np.array([1, 2])) array([[ 0., 0., 1., 2.]])

clear
()¶ Clear the buffer containing previous input data.

process
(data)¶ Add new data to the end of the window.
Parameters: data (array, shape (n_channels, n_samples)) – Input data. n_samples
must be less than or equal to the windowerlength
.Returns: out – Output window with the input data at the end. Return type: array, shape (n_channels, length)

class
copper.common.
Centerer
(name=None, hooks=None)¶ Centers data by subtracting out its mean.

process
(data)¶ Center each row of the input.
Parameters: data (array, shape (n_channels, n_samples)) – Input data. Returns: out – Input data that’s been centered. Return type: array, shape (n_channels, n_samples)


class
copper.common.
Filter
(b, a=1, overlap=0)¶ Filters incoming data with a time domain filter.
This filter implementation takes filter coefficients that are designed by the user – it merely applies the filter to the input, remembering the final inputs/outputs from the previous update and using them as initial conditions for the current update.
Parameters:  b (ndarray) – Numerator polynomial coefficients of the filter.
 a (ndarray, optional) – Denominator polynomial coefficients of the filter. Default is 1, meaning the filter is FIR.
 overlap (int, optional) – Number of samples overlapping in consecutive inputs. Needed for correct filter initial conditions in each filtering operation. Default is 0, meaning the final inputs/outputs of the previous update are used.
See also
copper.common.Ensure2D
 Ensure input to the filter is 2D.
Examples
Design a filter using scipy and use the coefficients:
>>> import copper >>> import numpy as np >>> from scipy.signal import butter >>> b, a = butter(4, 100/1000/2) >>> f = copper.Filter(b, a) >>> f.process(np.random.randn(1, 5)) array([...
Use a filter in combination with a
Windower
, making sure to account for overlapping data in consecutive filtering operations. Here, we’ll use a window of length 5 and pass in 3 samples at a time, so there will be an overlap of 2 samples. The overlapping samples in each output will agree:>>> w = copper.Windower(5) >>> f = copper.Filter(b, a, overlap=2) >>> p = copper.Pipeline([w, f]) >>> out1 = p.process(np.random.randn(1, 3)) >>> out2 = p.process(np.random.randn(1, 3)) >>> out1[:, 2:] == out2[:, :2] array([[ True, True]], dtype=bool)

clear
()¶ Clears the filter initial conditions.
Clearing the initial conditions is important when starting a new recording if
overlap
is nonzero.

process
(data)¶ Applies the filter to the input.
Parameters: data (ndarray, shape (n_channels, n_samples)) – Input signals.

class
copper.common.
FeatureExtractor
(features, hooks=None)¶ Computes multiple features from the input, concatenating the results.
Each feature should be able to take in the same data and output a 1D array, so overall output of the FeatureExtractor can be a single 1D array.
This block isn’t strictly necessary, since you could just apply multiple feature blocks in parallel and the result of each will be passed to the next block. However, the block following feature computation typically expects the input to be a single array (or row) per data sample.
Parameters: features (list) – List of (name, feature) tuples (i.e. implementing a compute
method).
named_features
¶ dict – Dictionary of features accessed by name.

feature_indices
¶ dict – Dictionary of (start, stop) tuples indicating the bounds of each feature, accessed by name. Will be empty until after data is first passed through.

clear
()¶ Clears the output array.
This should be called if the input is going to change form in some way (i.e. the shape of the input array changes).

process
(data)¶ Run data through the list of features and concatenates the results.
The first pass (after a
clear
call) will be a little slow since the extractor needs to allocate the output array.Parameters: data (array, shape (n_channels, n_samples)) – Input data. Must be appropriate for all features. Returns: out Return type: array, shape (n_features,)


class
copper.common.
Estimator
(estimator)¶ A pipeline block wrapper around scikitlearn’s idea of an estimator.
An estimator is an object that can be trained with some data (
fit
) and, once trained, can output predictions from novel inputs. A common usecase for this block is to utilize a scikitlearn pipeline in the context of a axopy pipeline.Parameters: estimator (object) – An object implementing the scikitlearn Estimator interface (i.e. implementing fit
andpredict
methods).
process
(data)¶ Calls the estimator’s
predict
method and returns the result.


class
copper.common.
Transformer
(transformer, hooks=None)¶ A pipeline block wrapper around scikitlearn’s idea of a transformer.
A transformer is trained with some data (
fit
) and, once trained, can output projections of the input data to some other space. A common example is projecting data in highdimensional space to a lowerdimensional space using principal components analysis.Parameters: transformer (object) – An object implementing the scikitlearn Transformer interface (i.e. implementing fit
andtransform
methods).
process
(data)¶ Calls the transformer’s
transform
method and returns the result.


class
copper.common.
Ensure2D
(orientation='row')¶ Transforms an array to ensure it has 2 dimensions.
Input with shape
(n,)
can be made to have shape(n, 1)
or(1, n)
.Parameters: orientation ({'row', 'col'}, optional) – Orientation of the output. If ‘row’, the output will have shape (1, n)
, meaning the output is a row vector. This is the default behavior, useful when the data is something like samples of a 1channel signal. If ‘col’, the output will have shape(n, 1)
, meaning the output is a column vector.Examples
Output row data:
>>> import numpy as np >>> import copper >>> block = copper.Ensure2D() >>> block.process(np.array([1, 2, 3])) array([[1, 2, 3]])
Output column data:
>>> block = copper.Ensure2D(orientation='col') >>> block.process(np.array([1, 2, 3])) array([[1], [2], [3]])

process
(data)¶ Make sure data is 2dimensional.
If the input already has two dimensions, it is unaffected.
Parameters: data (array, shape (n,)) – Input data. Returns: out – Output data, with shape specified by orientation
.Return type: array, shape (1, n) or (n, 1)
