nemos.basis._basis.Basis#

class nemos.basis._basis.Basis[source]#

Bases: Base, ABC, BasisTransformerMixin

Abstract base class for defining basis functions for feature transformation.

Basis functions are mathematical constructs that can represent data in alternative, often more compact or interpretable forms. This class provides a template for such transformations, with specific implementations defining the actual behavior.

Raises:

ValueError: – If kwargs include parameters not recognized or do not have default values in create_convolutional_predictor.
ValueError: – If axis different from 0 is provided as a keyword argument (samples must always be in the first axis).

Attributes

n_basis_funcs

Number of basis functions.

__init__()[source]#

Return type:: None

Methods

`__init__`()
`compute_features`(*xi)	Apply the basis transformation to the input data.
`evaluate`(*xi)	Abstract method to evaluate the basis functions at given points.
`evaluate_on_grid`(*n_samples)	Evaluate the basis set on a grid of equi-spaced sample points.
`get_params`([deep])	From scikit-learn, get parameters by inspecting init.
`set_input_shape`(xi)	Set the expected input shape for the basis object.
`set_params`(**params)	Set the parameters of this estimator.
`setup_basis`(*xi)	Pre-compute all basis state variables.
`to_transformer`()	Turn the Basis into a TransformerBasis for use with scikit-learn.

__add__(other)[source]#

Add two Basis objects together.

Parameters:: other (BasisMixin) – The other Basis object to add.
Returns:: The resulting Basis object.
Return type:: AdditiveBasis

classmethod __init_subclass__(**kwargs)#

Set the set_{method}_request methods.

This uses PEP-487 [1] to set the set_{method}_request methods. It looks for the information available in the set default values which are set using __metadata_request__* class attributes, or inferred from method signatures.

The __metadata_request__* class attributes are used when a method does not explicitly accept a metadata through its arguments or if the developer would like to specify a request value for those metadata which are different from the default None.

References

__len__()[source]#: Return the number of additive basis.

__mul__(other)[source]#

Multiply two Basis objects together.

Parameters:: other (BasisMixin | int) – The other Basis object to multiply.
Return type:: Basis
Returns:: The resulting Basis object.

__pow__(exponent)[source]#

Exponentiation of a Basis object.

Define the power of a basis by repeatedly applying the method __multiply__. The exponent must be a positive integer.

Parameters:

exponent (int) – Positive integer exponent

Return type:

BasisMixin

Returns:

The product of the basis with itself “exponent” times. Equivalent to self * self * ... * self.

Raises:

TypeError – If the provided exponent is not an integer.
ValueError – If the integer is zero or negative.

__rmul__(other)[source]#

Right multiplication operator for basis.

Parameters:: other (BasisMixin | int)

compute_features(*xi)[source]#

Apply the basis transformation to the input data.

This method is designed to be a high-level interface for transforming input data using the basis functions defined by the subclass. Depending on the basis’ mode (‘Eval’ or ‘Conv’), it either evaluates the basis functions at the sample points or performs a convolution operation between the input data and the basis functions.

Parameters:: *xi (ArrayLike | Tsd | TsdFrame | TsdTensor) – Input data arrays to be transformed. The shape and content requirements depend on the subclass and mode of operation (‘Eval’ or ‘Conv’).
Return type:: FeatureMatrix
Returns:: Transformed features. In ‘Eval’ mode, it corresponds to the basis functions evaluated at the input samples. In ‘Conv’ mode, it consists of convolved input samples with the basis functions. The output shape varies based on the subclass and mode.

Notes

Subclasses should implement how to handle the transformation specific to their basis function types and operation modes.

abstractmethod evaluate(*xi)[source]#

Abstract method to evaluate the basis functions at given points.

This method must be implemented by subclasses to define the specific behavior of the basis transformation. The implementation depends on the type of basis (e.g., spline, raised cosine), and it should evaluate the basis functions at the specified points in the domain.

Parameters:: *xi (ArrayLike | Tsd | TsdFrame | TsdTensor) – Variable number of arguments, each representing an array of points at which to evaluate the basis functions. The dimensions and requirements of these inputs vary depending on the specific basis implementation.
Return type:: FeatureMatrix
Returns:: An array containing the evaluated values of the basis functions at the input points. The shape and structure of this array are specific to the subclass implementation.

evaluate_on_grid(*n_samples)[source]#

Evaluate the basis set on a grid of equi-spaced sample points.

Parameters:

n_samples (int) – The number of samples.

Return type:

Tuple[Tuple[NDArray], NDArray]

Returns:

X – Array of shape (n_samples,) containing the equi-spaced sample points where we’ve evaluated the basis.
basis_funcs – Evaluated exponentially decaying basis functions, numerically orthogonalized, shape (n_samples, n_basis_funcs)

get_metadata_routing()#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:: routing – A MetadataRequest encapsulating routing information.
Return type:: MetadataRequest

get_params(deep=True)#

From scikit-learn, get parameters by inspecting init.

Parameters:: deep – If True, will return the parameters for this estimator and contained subobjects that are estimators.
Return type:: dict
Returns:: A dictionary containing the parameters. Key is the parameter name, value is the parameter value.

property n_basis_funcs#: Number of basis functions.

abstractmethod set_input_shape(xi)[source]#

Set the expected input shape for the basis object.

This method configures the shape of the input data that the basis object expects. xi can be specified as an integer, a tuple of integers, or derived from an array. The method also calculates the total number of input features and output features based on the number of basis functions.

Parameters:: xi (int | tuple[int, ...] | TypeAliasForwardRef('NDArray'))

set_params(**params)#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:: **params (Any) – Estimator parameters.
Returns:: self – Estimator instance.
Return type:: estimator instance

abstractmethod setup_basis(*xi)[source]#

Pre-compute all basis state variables.

This method is intended to be equivalent to the sklearn transformer fit method. As the latter, it computes all the state attributes, and store it with the convention that the attribute name must end with “_”, for example self.kernel_, self._input_shape_.

The method differs from transformer’s fit for the structure of the input that it accepts. In particular, _fit_basis accepts a number of different time series, one per 1D basis component, while fit requires all inputs to be concatenated in a single array.

Return type:: FeatureMatrix
Parameters:: xi (ArrayLike)

to_transformer()#

Turn the Basis into a TransformerBasis for use with scikit-learn.

Return type:: TransformerBasis

Examples

Jointly cross-validating basis and GLM parameters with scikit-learn.

>>> import nemos as nmo
>>> from sklearn.pipeline import Pipeline
>>> from sklearn.model_selection import GridSearchCV
>>> # load some data
>>> X, y = np.random.normal(size=(30, 1)), np.random.poisson(size=30)
>>> basis = nmo.basis.RaisedCosineLinearEval(10).set_input_shape(1).to_transformer()
>>> glm = nmo.glm.GLM(regularizer="Ridge", regularizer_strength=1.)
>>> pipeline = Pipeline([("basis", basis), ("glm", glm)])
>>> param_grid = dict(
...     glm__regularizer_strength=(0.1, 0.01, 0.001, 1e-6),
...     basis__n_basis_funcs=(3, 5, 10, 20, 100),
... )
>>> gridsearch = GridSearchCV(
...     pipeline,
...     param_grid=param_grid,
...     cv=5,
... )
>>> gridsearch = gridsearch.fit(X, y)