Forecast
chronax.forecaster.Forecast
A frozen dataclass representing the output of a time series forecast, containing the mean prediction and optionally, samples for probabilistic forecasting.
Attributes
| Attribute | Type | Description |
|---|---|---|
mean |
Float[torch.Tensor, "batch variate future_time_steps"] |
(undocumented) |
samples |
Float[torch.Tensor, "batch variate future_time_steps samples"] \| None |
(undocumented) |
quantile(self, q)
Compute the quantile of the forecast samples.
| Parameter | Type | Default | Description |
|---|---|---|---|
q |
float \| torch.Tensor |
- | (undocumented) |
Returns: Float[torch.Tensor, "batch variate future_time_steps"]
median
The median of the forecast samples.
Returns: Float[torch.Tensor, "batch variate future_time_steps"]
std
Compute the standard deviation of the forecast samples.
Returns: Float[torch.Tensor, "batch variate future_time_steps"]
TotoForecaster
chronax.forecaster.TotoForecaster
A forecaster class for the Toto model that handles autoregressive decoding for time series forecasting.
This class wraps a TotoBackbone model and provides methods to generate forecasts for time series data. The forecasting process uses an autoregressive decoding algorithm:
- The model first processes the entire input context (historical data)
- For each future time step: - The model generates a distribution over possible values - Either the mean or random samples are drawn from this distribution - The generated value(s) are appended to the input sequence - The process repeats with this extended sequence
When generating multiple samples (num_samples > 1), the model creates separate trajectories for each sample: - Each trajectory starts with the same historical context - As sampling progresses, each trajectory evolves independently - This results in num_samples different possible future paths - Samples can be processed in batches (samples_per_batch) to manage memory usage
The forecaster efficiently reuses computation from the context processing phase using a key-value cache, which stores intermediate transformer attention states to avoid redundant computation.
The forecaster handles data preprocessing, including padding to match the model's patch size, and postprocessing to format the outputs as a Forecast object containing means and optional samples.
Attributes
| Attribute | Type | Description |
|---|---|---|
model |
TotoBackbone |
(undocumented) |
__init__(self, model)
| Parameter | Type | Default | Description |
|---|---|---|---|
model |
TotoBackbone |
- | (undocumented) |
forecast(self, inputs, prediction_length, num_samples=None, samples_per_batch=10, use_kv_cache=True, future_exogenous_variables=None)
Generate a forecast for a batch of time series. This method works autoregressively, i.e. it feeds the model's predictions back into itself. The decoding process is as follows:
- The model first processes the entire input context (historical data)
- For each future time step:
- The model generates a distribution over possible values
- Either the mean or random samples are drawn from this distribution
- The generated value(s) are appended to the input sequence
- The process repeats with this extended sequence
There are two modes of operation: 1. num_samples is None: generate a single mean prediction 2. num_samples is not None: generate num_samples random samples
When num_samples is not None, the model creates num_samples separate trajectories for each sample: - Each trajectory starts with the same historical context - As sampling progresses, each trajectory evolves independently - This results in num_samples different possible future paths - Samples can be processed in batches (samples_per_batch) to manage memory usage
When using samples_per_batch, this batch size compounds with the optional batch dimension of the input. For example, if you have a batch of 10 time series, and you set samples_per_batch to 10, the effective batch size is 100. For the best performance, set samples_per_batch as high as possible, subject to memory constraints.
| Parameter | Type | Default | Description |
|---|---|---|---|
inputs |
MaskedTimeseries |
- | A MaskedTimeseries object containing the input time series. |
prediction_length |
int |
- | The number of future time steps to predict. |
num_samples |
int \| None |
None |
The number of samples to generate. If None, a single mean prediction is generated. However, the mean point forecast tends to be less accurate than the median or mean of the samples (provided enough samples are generated). It's recommended to use at least 128 samples for reliable forecasts. |
samples_per_batch |
int |
10 |
The number of samples to generate per batch. In most cases, this should be as high as possible, subject to memory constraints. When the inputs have a batch dimension, the effective batch size is samples_per_batch * batch_size. |
use_kv_cache |
bool |
True |
Whether to use a key-value cache for the model. In most cases, this should be True, as it significantly speeds up inference. |
future_exogenous_variables |
Float[torch.Tensor, "batch exogenous_variables future_time_steps"] \| None |
None |
(undocumented) |
Returns: Forecast
generate_mean(self, inputs, prediction_length, timestamp_seconds, time_interval_seconds, input_padding_mask=None, id_mask=None, use_kv_cache=False, future_exogenous_variables=None, num_exogenous_variables=0)
Generate a point prediction by taking the mean of the output distribution at each step. This method works autoregressively. If future_exogenous_variables are provided, they are injected to replace predicted values for the last num_exogenous_variables channels.
| Parameter | Type | Default | Description |
|---|---|---|---|
inputs |
Float[torch.Tensor, "batch variate time_steps"] |
- | (undocumented) |
prediction_length |
int |
- | (undocumented) |
timestamp_seconds |
Int[torch.Tensor, "batch variate time_steps"] |
- | (undocumented) |
time_interval_seconds |
Int[torch.Tensor, "batch variate"] |
- | (undocumented) |
input_padding_mask |
Bool[torch.Tensor, "batch variate time_steps"] \| None |
None |
(undocumented) |
id_mask |
Float[torch.Tensor, "batch #variate time_steps"] \| None |
None |
(undocumented) |
use_kv_cache |
bool |
False |
(undocumented) |
future_exogenous_variables |
Float[torch.Tensor, "batch exogenous_variables future_time_steps"] \| None |
None |
(undocumented) |
num_exogenous_variables |
int |
0 |
(undocumented) |
Returns: Float[torch.Tensor, "batch variate time_steps"]
generate_samples(self, inputs, prediction_length, num_samples, timestamp_seconds, time_interval_seconds, input_padding_mask=None, id_mask=None, sampling_batch_size=10, use_kv_cache=False, future_exogenous_variables=None, num_exogenous_variables=0)
Generate samples from the output distribution. This method works autoregressively. If future_exogenous_variables are provided, they are injected to replace predicted values for the last num_exogenous_variables channels.
| Parameter | Type | Default | Description |
|---|---|---|---|
inputs |
Float[torch.Tensor, "batch variate time_steps"] |
- | (undocumented) |
prediction_length |
int |
- | (undocumented) |
num_samples |
int |
- | (undocumented) |
timestamp_seconds |
Int[torch.Tensor, "batch variate time_steps"] |
- | (undocumented) |
time_interval_seconds |
Int[torch.Tensor, "batch variate"] |
- | (undocumented) |
input_padding_mask |
Bool[torch.Tensor, "batch variate time_steps"] \| None |
None |
(undocumented) |
id_mask |
Float[torch.Tensor, "batch #variate time_steps"] \| None |
None |
(undocumented) |
sampling_batch_size |
int |
10 |
(undocumented) |
use_kv_cache |
bool |
False |
(undocumented) |
future_exogenous_variables |
Float[torch.Tensor, "batch exogenous_variables future_time_steps"] \| None |
None |
(undocumented) |
num_exogenous_variables |
int |
0 |
(undocumented) |
Returns: Float[torch.Tensor, "batch variate time_steps samples"]
create_affine_transformed(base_distr, loc, scale)
Creates an AffineTransformed distribution with correctly matched shapes.
Handles three cases: 1. When loc/scale are per-timestep (from CausalStdMeanScaler) 2. When base_distr only contains the distribution for the latest patch while loc/scale contain values for the entire sequence 3. When loc/scale have a single time step (from StdMeanScaler/StdMinScaler) and need to be broadcast to match a multi-step base distribution
| Parameter | Type | Default | Description |
|---|---|---|---|
base_distr |
Distribution |
- | The base distribution to transform |
loc |
torch.Tensor |
- | Location parameter |
scale |
torch.Tensor |
- | Scale parameter |
Returns: Distribution (An AffineTransformed distribution with properly handled shapes)