pyrcn.echo_state_network¶

The pyrcn.echo_state_network.

It contains a simple object-oriented implementation of Echo State Networks 1 2.

Separate implementations of Classifiers and Regressors as specified by scikit-learn

References

1: H. Jaeger, ‘The “echo state” approach to analysing and training recurrent neural networks – with an Erratum note’, p. 48.
2: M. Lukoševičius, ‘A Practical Guide to Applying Echo State Networks’, Jan. 2012, doi: 10.1007/978-3-642-35289-8_36.

Echo State Network¶

class pyrcn.echo_state_network.ESNRegressor(*, input_to_node: pyrcn.base.blocks._input_to_node.InputToNode | None = None, node_to_node: pyrcn.base.blocks._node_to_node.NodeToNode | None = None, regressor: pyrcn.linear_model._incremental_regression.IncrementalRegression | sklearn.base.RegressorMixin | None = None, requires_sequence: Union[Literal['auto'], bool] = 'auto', decision_strategy: Literal['winner_takes_all', 'median', 'last_value'] = 'winner_takes_all', verbose: bool = True, **kwargs: Any)¶

Bases: RegressorMixin, MultiOutputMixin, BaseEstimator

Echo State Network regressor.

This model optimizes the mean squared error loss function using linear regression.

Parameters

input_to_node (Optional[InputToNode], default=None) – Any `InputToNode` object that transforms the inputs. If `None`, a `pyrcn.base.blocks.InputToNode` object is instantiated.
node_to_node (Optional[NodeToNode], default=None) – Any `NodeToNode` object that transforms the outputs of `input_to_node`. If `None`, a `pyrcn.base.blocks.NodeToNode` object is instantiated.
regressor (Union[IncrementalRegression, RegressorMixin, None],) –
default=None – Regressor object such as derived from BaseEstimator. This regressor will automatically be cloned each time prior to fitting. If `None`, a `pyrcn.linear_model.IncrementalRegression` object is instantiated.
requires_sequence (Union[Literal["auto"], bool], default="auto") – If True, the input data is expected to be a sequence. If “auto”, tries to automatically estimate when calling `fit` for the first time
decision_strategy (Literal["winner_takes_all", "median", "last_value"],) –
default='winner_takes_all' – Decision strategy for sequence-to-label task. Ignored if the target output is a sequence
verbose (bool = False) – Verbosity output
kwargs (Any) – keyword arguments passed to the subestimators if this is desired, default=None

property decision_strategy: Literal['winner_takes_all', 'median', 'last_value']¶

Return the decision_strategy parameter.

Returns: decision_strategy
Return type: Literal[“winner_takes_all”, “median”, “last_value”]

fit(X: ndarray, y: ndarray, n_jobs: int | numpy.integer | None = None, transformer_weights: numpy.ndarray | None = None) → ESNRegressor¶

Fit the regressor.

Parameters

X (ndarray of shape (n_samples, n_features) or of shape (n_sequences,)) –
y (ndarray of shape (n_samples,) or (n_samples, n_targets)) –
(n_sequences) (or of shape) – The targets to predict.
n_jobs (Optional[int, np.integer], default=None) – The number of jobs to run in parallel. `-1` means using all processors. See Glossary for more details.
transformer_weights (Optional[np.ndarray] = None) – ignored

Returns

self

Return type

Returns a trained ESNRegressor model.

get_params(deep: bool = True) → dict¶: Get all parameters of the ESNRegressor.

hidden_layer_state(X: ndarray) → ndarray¶

Return the hidden_layer_state, e.g. the reservoir state over time.

Parameters: X (ndarray of shape (n_samples, n_features)) –
Returns: hidden_layer_state – The hidden_layer_state, e.g. the reservoir state over time.
Return type: ndarray of (n_samples,)

property input_to_node: InputToNode¶

Return the input_to_node Transformer.

Returns: input_to_node
Return type: InputToNode

property node_to_node: NodeToNode¶

Return the node_to_node Transformer.

Returns: node_to_node
Return type: NodeToNode

partial_fit(X: ndarray, y: ndarray, transformer_weights: None | numpy.ndarray = None, postpone_inverse: bool = False) → ESNRegressor¶

Fit the regressor partially.

Parameters

X (ndarray of shape (n_samples, n_features)) –
y (ndarray of shape (n_samples,) or (n_samples, n_targets)) – The targets to predict.
transformer_weights (ignored) –
postpone_inverse (bool, default=False) – If the output weights have not been fitted yet, regressor might be hinted at postponing inverse calculation. Refer to `IncrementalRegression` for details.

Returns

self

Return type

Returns a trained `ESNRegressor` model.

predict(X: ndarray) → ndarray¶

Predict the targets using the trained `ESNRegressor`.

Parameters: X (ndarray of shape (n_samples, n_features)) –
Returns: y – The predicted targets
Return type: ndarray of (n_samples,) or (n_samples, n_targets)

property regressor: sklearn.base.RegressorMixin | pyrcn.linear_model._incremental_regression.IncrementalRegression¶

Return the regressor.

Returns: regressor
Return type: RegressorMixin

property requires_sequence: Union[Literal['auto'], bool]¶

Return the requires_sequence parameter.

Returns: requires_sequence
Return type: Union[Literal[“auto”], bool]

property sequence_to_value: bool¶

Return the sequence_to_value parameter.

Returns: sequence_to_value
Return type: bool

set_fit_request(*, n_jobs: Union[bool, None, str] = '$UNCHANGED$', transformer_weights: Union[bool, None, str] = '$UNCHANGED$') → ESNRegressor¶

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to fit.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in version 1.3.

Parameters

n_jobs (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for n_jobs parameter in fit.
transformer_weights (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for transformer_weights parameter in fit.

Returns

self – The updated object.

Return type

object

set_params(**parameters: dict) → ESNRegressor¶: Set all possible parameters of the ESNRegressor.

set_partial_fit_request(*, postpone_inverse: Union[bool, None, str] = '$UNCHANGED$', transformer_weights: Union[bool, None, str] = '$UNCHANGED$') → ESNRegressor¶

Configure whether metadata should be requested to be passed to the partial_fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to partial_fit if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to partial_fit.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in version 1.3.

Parameters

postpone_inverse (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for postpone_inverse parameter in partial_fit.
transformer_weights (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for transformer_weights parameter in partial_fit.

Returns

self – The updated object.

Return type

object

set_score_request(*, sample_weight: Union[bool, None, str] = '$UNCHANGED$') → ESNRegressor¶

Configure whether metadata should be requested to be passed to the score method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to score.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in version 1.3.

Parameters: sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in score.
Returns: self – The updated object.
Return type: object

class pyrcn.echo_state_network.ESNClassifier(*, input_to_node: pyrcn.base.blocks._input_to_node.InputToNode | None = None, node_to_node: pyrcn.base.blocks._node_to_node.NodeToNode | None = None, regressor: pyrcn.linear_model._incremental_regression.IncrementalRegression | sklearn.base.RegressorMixin | None = None, requires_sequence: Union[Literal['auto'], bool] = 'auto', decision_strategy: Literal['winner_takes_all', 'median', 'last_value'] = 'winner_takes_all', verbose: bool = False, **kwargs: Any)¶

Bases: ClassifierMixin, ESNRegressor

Echo State Network classifier.

This model optimizes the mean squared error loss function using linear regression.

Parameters

input_to_node (Optional[InputToNode], default=None) – Any `InputToNode` object that transforms the inputs. If `None`, a `pyrcn.base.blocks.InputToNode` object is instantiated.
node_to_node (Optional[NodeToNode], default=None) – Any `NodeToNode` object that transforms the outputs of `input_to_node`. If `None`, a `pyrcn.base.blocks.NodeToNode()` object is instantiated.
regressor (Union[IncrementalRegression, RegressorMixin, None],) –
default=None – Regressor object such as derived from RegressorMixin. This regressor will automatically be cloned each time prior to fitting. If `None`, a `pyrcn.linear_model.IncrementalRegression()` object is instantiated.
requires_sequence (Union[Literal["auto"], bool], default="auto") – If True, the input data is expected to be a sequence. If “auto”, tries to automatically estimate when calling `fit` for the first time
decision_strategy (Literal["winner_takes_all", "median", "last_value"],) –
default='winner_takes_all' – Decision strategy for sequence-to-label task. Ignored if the target output is a sequence
verbose (bool = False) – Verbosity output
kwargs (Any, default = None) – keyword arguments passed to the subestimators if this is desired.

fit(X: ndarray, y: ndarray, n_jobs: int | numpy.integer | None = None, transformer_weights: None | numpy.ndarray = None) → ESNClassifier¶

Fit the classifier.

Parameters

X (ndarray of shape (n_samples, n_features) or of shape (n_sequences,)) –
y (ndarray of shape (n_samples,) or (n_samples, n_classes)) –
(n_sequences) (or of shape) – The targets to predict.
n_jobs (int, default=None) – The number of jobs to run in parallel. `-1` means using all processors. See Glossary for more details.
transformer_weights (ignored) –

Returns

self

Return type

Returns a trained ESNClassifier model.

partial_fit(X: ndarray, y: ndarray, transformer_weights: numpy.ndarray | None = None, postpone_inverse: bool = False, classes: numpy.ndarray | None = None) → ESNClassifier¶

Fit the regressor partially.

Parameters

X (ndarray of shape (n_samples, n_features)) –
y (ndarray of shape (n_samples,) or (n_samples, n_targets)) – The targets to predict.
classes (Optional[np.ndarray], default=None) – Classes across all calls to partial_fit. Can be obtained via np.unique(y_all), where y_all is the target vector of the entire dataset. This argument is required for the first call to partial_fit and can be omitted in the subsequent calls. Note that y doesn’t need to contain all labels in classes.
transformer_weights (Optional[ndarray], default=None) – ignored
postpone_inverse (bool, default=False) – If the output weights have not been fitted yet, regressor might be hinted at postponing inverse calculation. Refer to IncrementalRegression for details.

Returns

self

Return type

returns a trained ESNClassifier model

predict(X: ndarray) → ndarray¶

Predict the classes using the trained `ESNClassifier`.

Parameters: X (ndarray of shape (n_samples, n_features)) – The input data.
Returns: y_pred – The predicted classes.
Return type: ndarray of shape (n_samples,) or (n_samples, n_classes)

predict_log_proba(X: ndarray) → ndarray¶

Predict the log probability estimated using a trained `ESNClassifier`.

Parameters: X (ndarray of shape (n_samples, n_features)) – The input data.
Returns: y_pred – The predicted logarithmic probability estimated.
Return type: ndarray of shape (n_samples,) or (n_samples, n_classes)

predict_proba(X: ndarray) → ndarray¶

Predict the probability estimated using a trained `ESNClassifier`.

Parameters: X (ndarray of shape (n_samples, n_features)) – The input data.
Returns: y_pred – The predicted probability estimates.
Return type: ndarray of shape (n_samples,) or (n_samples, n_classes)

set_fit_request(*, n_jobs: Union[bool, None, str] = '$UNCHANGED$', transformer_weights: Union[bool, None, str] = '$UNCHANGED$') → ESNClassifier¶

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to fit.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in version 1.3.

Parameters

n_jobs (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for n_jobs parameter in fit.
transformer_weights (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for transformer_weights parameter in fit.

Returns

self – The updated object.

Return type

object

set_partial_fit_request(*, classes: Union[bool, None, str] = '$UNCHANGED$', postpone_inverse: Union[bool, None, str] = '$UNCHANGED$', transformer_weights: Union[bool, None, str] = '$UNCHANGED$') → ESNClassifier¶

Configure whether metadata should be requested to be passed to the partial_fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to partial_fit if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to partial_fit.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in version 1.3.

Parameters

classes (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for classes parameter in partial_fit.
postpone_inverse (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for postpone_inverse parameter in partial_fit.
transformer_weights (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for transformer_weights parameter in partial_fit.

Returns

self – The updated object.

Return type

object

set_score_request(*, sample_weight: Union[bool, None, str] = '$UNCHANGED$') → ESNClassifier¶

Configure whether metadata should be requested to be passed to the score method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to score.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in version 1.3.

Parameters: sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in score.
Returns: self – The updated object.
Return type: object