canari.component.lstm_component

canari.component.lstm_component#

class canari.component.lstm_component.LstmNetwork(std_error: float | None = 0.0, num_layer: int | None = 1, num_hidden_unit: int | None = 50, look_back_len: int | None = 1, num_features: int | None = 1, num_output: int | None = 1, device: str | None = 'cpu', num_thread: int | None = 1, manual_seed: int | None = None, gain_weight: int | None = 1, gain_bias: int | None = 1, load_lstm_net: str | None = None, mu_states: list[float] | None = None, var_states: list[float] | None = None)[source]#

Bases: BaseComponent

LstmNetwork class, inheriting from Canari’s BaseComponent. This component configures a Bayesian LSTM neural network from pyTAGI library, and it can be used in the same way as a traditional LSTM from PyTorch, e.g. to model recurrent patterns such as seasonal and periodic patterns.

Parameters:

  • std_error (Optional[float]) – Standard deviation of the process noise. Defaults to 0.0.

  • num_layer (Optional[int]) – Number of LSTM layers. Defaults to 1.

  • num_hidden_unit (Optional[int] or list[int]) – Number of hidden units per LSTM layer. If an integer is provided, it is used for all layers. Defaults to 50.

  • look_back_len (Optional[int]) – Number of past LSTM’s outputs used as input features. Defaults to 1.

  • num_features (Optional[int]) – Number of input features. Defaults to 1.

  • num_output (Optional[int]) – Number of output features predicted by the network. Defaults to 1.

  • device (Optional[str]) – Device used for computation, either “cpu” or “cuda”. Defaults to “cpu”.

  • num_thread (Optional[int]) – Number of CPU threads for computation. Defaults to 1.

  • manual_seed (Optional[int]) – Initial seed for reproducing random number generation, i.e. intializing LSTM’s weights and biases. Defaults to None (random initialization).

  • gain_weight (Optional[int]) – Scaling factor for weight initialization. Defaults to 1.

  • gain_bias (Optional[int]) – Scaling factor for bias initialization. Defaults to 1.

  • load_lstm_net (Optional[str]) – Path to a saved LSTM network file containing pretrained LSTM’s weights and biases. Defaults to None.

  • mu_states (Optional[list[float]]) – Initial mean of the hidden state. Defaults: initialized to zeros.

  • var_states (Optional[list[float]]) – Initial variance of the hidden state. Defaults: initialized to zeros.

References

Vuong, V.D., Nguyen, L.H. and Goulet, J.-A. (2025). Coupling LSTM neural networks and state-space models through analytically tractable inference. International Journal of Forecasting. Volume 41, Issue 1, Pages 128-140.

Examples

>>> from canari.component import LstmNetwork
>>> lstm = LstmNetwork(
...     std_error=0.1,
...     num_layer=2,
...     num_hidden_unit=[32, 16],
...     look_back_len=5,
...     num_features=3,
...     device="cpu",
...     manual_seed=1,
... )
>>> lstm.states_name
['lstm']
>>> lstm.mu_states
array([[0.]])
>>> lstm.var_states
array([[0.]])
>>> lstm.transition_matrix
array([[0.]])
>>> lstm.observation_matrix
array([[1.]])
>>> lstm.process_noise_matrix
array([[0.01]])
initialize_component_name()[source]#

Initialize the component’s name. str.

initialize_lstm_network() → Sequential[source]#

Builds and returns the LSTM network as a pytagi.Sequential instance.

The network consists of:

  • One or multiple LSTM layers, each with specified hidden units.

  • A final Linear layer mapping the LSTM’s output to the desired output size.

The first LSTM layer input size is determined by num_features + look_back_len - 1.

Returns:

a pytagi.Sequential instance representing the LSTM network.

Return type:

Sequential

initialize_mu_states()[source]#

Initialize the mean of the hidden states. Output an 2D array.

initialize_num_states()[source]#

Initialize the number of hidden states. int.

initialize_observation_matrix()[source]#

Initialize the observation matrix. Output an 2D array.

initialize_process_noise_matrix()[source]#

Initialize the process noise covariance matrix. Output an 2D array.

initialize_states_name()[source]#

Initialize the names of all hidden states. list[str].

initialize_transition_matrix()[source]#

Initialize the transition matrix. Output an 2D array.

initialize_var_states()[source]#

Initialize the covariance matrix of the hidden states. Output an 2D array.

Contents