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: Optional[InputToNode] = None, node_to_node: Optional[NodeToNode] = None, regressor: Optional[Union[IncrementalRegression, LinearModel]] = 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: BaseEstimator, MultiOutputMixin, RegressorMixin

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, LinearModel, 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: Optional[Union[int, integer]] = None, transformer_weights: Optional[ndarray] = 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: Optional[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: Union[LinearModel, IncrementalRegression]¶

Return the regressor.

Returns: regressor
Return type: LinearModel

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¶

Request metadata passed to the fit method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see 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.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

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¶

Request metadata passed to the partial_fit method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see 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.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

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¶

Request metadata passed to the score method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see 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.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

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: Optional[InputToNode] = None, node_to_node: Optional[NodeToNode] = None, regressor: Optional[Union[IncrementalRegression, LinearModel]] = 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: ESNRegressor, ClassifierMixin

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, LinearModel, None], default=None) – Regressor object such as derived from LinearModel. 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: Optional[Union[int, integer]] = None, transformer_weights: Optional[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: Optional[ndarray] = None, postpone_inverse: bool = False, classes: Optional[ndarray] = 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¶

Request metadata passed to the fit method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see 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.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

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¶

Request metadata passed to the partial_fit method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see 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.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

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¶

Request metadata passed to the score method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see 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.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

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