RecurrentNeuralNetwork¶

Defined in fynance.models.rnn

class RecurrentNeuralNetwork(X, y, drop=None, x_type=None, y_type=None, bias=True, forward_activation=nn.Identity, hidden_activation=nn.Tanh, hidden_state_size=None)[source]

Bases: _OutputLayerMixin, _RecurrentBase

Single-step Elman-style gated cell.

A single linear layer (over the input concatenated with a supplied hidden state) followed by an output projection. Each call to forward consumes X of shape (T, N) and H of shape (T, H) and returns (Y, H_new) with the same leading dimension T; every row is processed independently and no state is threaded across rows. This is therefore a stateless gated feed-forward cell, not a sequence model — the caller must perform any temporal state threading explicitly.

For sequence modeling with built-in temporal state and causality, prefer TemporalConvNet or Transformer.

Parameters:

X, yarray-like or int

If it’s an array-like, respectively inputs and outputs data.
If it’s an integer, respectively dimension of inputs and outputs.

dropfloat, optional

Probability of an element to be zeroed.

biasbool, optional

If True (default), the linear layers learn an additive bias.

forward_activation, hidden_activationtorch.nn.Module, optional

Activation functions, default is respectively Identity and Tanh function. The output activation defaults to Identity so the cell produces unconstrained regression outputs (pass nn.Softmax for a probability-simplex output).

hidden_state_sizeint, optional

Size of hidden states, default is the same size than input.

Attributes:

criteriontorch.nn.modules.loss: A loss function.
optimizertorch.optim: An optimizer algorithm.
W_h, W_ytorch.nn.Linear: Respectively recurrent and forward weights.
f_y, f_htorch.nn.Module: Respectively forward and hidden activation functions.

See also

fynance.models.gru.GatedRecurrentUnit
fynance.models.lstm.LongShortTermMemory

Examples

>>> import torch
>>> from fynance.models.rnn import RecurrentNeuralNetwork
>>> _ = torch.manual_seed(0)
>>> model = RecurrentNeuralNetwork(4, 1, hidden_state_size=3)
>>> X = torch.zeros(5, 4)
>>> H = torch.zeros(5, 3)
>>> Y, H_new = model(X, H)
>>> Y.shape, H_new.shape
(torch.Size([5, 1]), torch.Size([5, 3]))

fit(X, y, epochs=1, x_type=None, y_type=None)

Fit the model on (X, y) for epochs full-batch steps.

Conforms to the SignalModel contract. The hidden state is zero-initialized once and threaded across epochs (detached between steps). An optimizer must have been registered with set_optimizer.

Parameters:

X, yarray-like: Input and output data (numpy / torch / polars), shapes (T, N) and (T, M).
epochsint: Number of full-batch training steps.
x_type, y_typetorch.dtype, optional: Target dtypes forwarded to set_data.

Returns:

_OutputLayerMixin: self, to allow chaining.

forward(X, H)[source]

Forward method.

Parameters:

X, Htorch.Tensor: Respectively input data and hidden state.

Returns:

torch.Tensor: Output data.
torch.Tensor: Hidden state.

load_model(path, load_optimizer=False)

Load the model weights and parameters from a file.

Parameters:

pathstr or os.PathLike object: Path to load the model.
load_optimizerbool, optional: If True, then load also the optimizer.

predict(X, H=None)

Predicts outputs of neural network model.

Two calling conventions are supported:

predict(X) — conforms to the SignalModel contract: X may be array-like (coerced to a tensor), the hidden state is zero-initialized, and only the prediction tensor Y is returned.
predict(X, H) — explicit-state form: X and H are tensors and the updated state is threaded back, returning the (Y, H) tuple.

In both cases X (and H) are moved to the model’s device.

Parameters:

Xarray-like or torch.Tensor: Inputs to compute prediction.
Htorch.Tensor, optional: States of the model. If None (default), a zero state is used and only the prediction is returned.

Returns:

torch.Tensor: Outputs prediction (when H is None).
tuple of torch.Tensor: (Y, H) outputs prediction and updated state (when H is provided).

save_model(path, save_optimizer=False)

Save the model with this weights and parameters.

Parameters:

pathstr or os.PathLike object: Path to save the model.
save_optimizerbool, optional: If True, then save also the optimizer.

set_data(X, y, x_type=None, y_type=None)

Set data inputs and outputs.

Coerces X and y to torch.Tensor and caches them as self.X / self.y. After the call the attributes self.T (number of observations), self.N (input columns) and self.M (output columns) are set.

Parameters:

X, yarray-like: Respectively input and output data. Accepted types: numpy.ndarray, torch.Tensor, polars.DataFrame. Shapes must be (T, N) and (T, M) respectively.
x_type, y_typetorch.dtype, optional: Target dtypes for the resulting tensors. Default is None, which casts floating-point inputs to torch.get_default_dtype() (float32 by default) and leaves integer inputs unchanged. See _set_data.

Returns:

BaseNeuralNet: self, to allow chaining.

Raises:

ValueError: If self.N / self.M were already set and X / y do not match, or if X and y have different lengths.

set_lr_scheduler(lr_scheduler, **kwargs)

Set dynamic learning rate.

Parameters:

lr_schedulertorch.optim.lr_scheduler._LRScheduler: Method from torch.optim.lr_scheduler to wrap self.optimizer, cf module torch.optim.lr_scheduler in PyTorch documentation [2].
**kwargs: Keyword arguments to pass to the learning rate scheduler.

References

[2]

https://pytorch.org/docs/stable/optim.html#how-to-adjust-learning-rate

set_optimizer(criterion, optimizer, params=None, **kwargs)

Set the optimizer object.

Set optimizer object with specified criterion as loss function and any kwargs as optional parameters.

Parameters:

criterionCallable, torch.nn.modules.loss: A loss function.
optimizertorch.optim.Optimizer: An optimizer algorithm.
paramsobject or iterable object: Layer of parameters to optimize or dicts defining parameter groups. If set to None then all parameters of model will be optimized. Default is None.
**kwargs: Keyword arguments of optimizer, cf PyTorch documentation [1].

Returns:

BaseNeuralNet: Self object model.

References

[1]

https://pytorch.org/docs/stable/optim.html

set_seed(seed_torch=None, seed_numpy=None)

Set seed for PyTorch and NumPy random number generator.

Each generator is only (re)seeded when its argument is provided: passing seed_torch alone leaves the global NumPy RNG untouched, and vice versa.

Parameters:

seed_torch, seed_numpybool or int, optional: If an int \(0 \leq seed < 2^{32}\), seed respectively the PyTorch and NumPy generator with that number. If True, draw a random seed. If None (default), leave that generator untouched.

Examples

>>> from fynance.models.mlp import MultiLayerPerceptron
>>> model = MultiLayerPerceptron(3, 1, layers=[4])
>>> model.set_seed(seed_torch=42)
>>> model.seed_torch
42
>>> model.seed_numpy is None
True

train_on(X, y, H)

Trains the neural network model.

Parameters:

X, y, Htorch.Tensor: Respectively inputs, outputs and states to train model.

Returns:

torch.nn.modules.loss: Loss outputs.
torch.Tensor: Updated states of the model.