autopycoin.models.NBEATS#

class autopycoin.models.NBEATS(*args, **kwargs)[source]#

Tensorflow model defining the N-BEATS architecture.

N-BEATS is a univariate model, see autopycoin.models.UnivariateModel for more information. Its strong advantage resides in its structure which allows us to extract the trend and the seasonality of temporal series. They are available from the attributes seasonality and trend. This is an unofficial implementation of the paper https://arxiv.org/abs/1905.10437.

Parameters
stackstuple[autopycoin.models.Stack]

Stacks can be created from autopycoin.models.TrendBlock, autopycoin.models.SeasonalityBlock or autopycoin.models.GenericBlock. See stack documentation for more details.

Notes

NBEATS supports the estimation of aleotoric and epistemic errors with:

  • Aleotoric interval : autopycoin.loss.QuantileLossError

  • Epistemic interval : MCDropout

You can use autopycoin.loss.QuantileLossError as loss error to estimate the aleotoric error. Also, run multiple times a prediction with drop_date > 0 to estimate the epistemic error.

Input shape N-D tensor with shape: (batch_size, time step, variables) or (batch_size, time step). The most common situation would be a 2D input with shape (batch_size, time step).

Output shape Two N-D tensor with shape: (batch_size, time step, variables, quantiles) or (batch_size, time step, quantiles) or (batch_size, time step). For instance, for a 2D input with shape (batch_size, units), the output would have shape (batch_size, units). With a QuantileLossError with 2 quantiles or higher the output would have shape (batch_size, units, quantiles). With a multivariate inputs the output would have shape (batch_size, units, variates, quantiles).

Examples

>>> from autopycoin.layers import TrendBlock, SeasonalityBlock
>>> from autopycoin.models import Stack, NBEATS
>>> from autopycoin.losses import QuantileLossError
>>> from autopycoin.data import random_ts
>>> from autopycoin.dataset import WindowGenerator
>>> import tensorflow as tf
>>> import pandas as pd
...
>>> data = random_ts(n_steps=1000,
...                  trend_degree=2,
...                  periods=[10],
...                  fourier_orders=[10],
...                  trend_mean=0,
...                  trend_std=1,
...                  seasonality_mean=0,
...                  seasonality_std=1,
...                  batch_size=1,
...                  n_variables=1,
...                  noise=True,
...                  seed=42)
>>> data = pd.DataFrame(data[0].numpy(), columns=['test'])
...
>>> w = WindowGenerator(
...        input_width=20,
...        label_width=10,
...        shift=10,
...        test_size=50,
...        valid_size=10,
...        flat=True,
...        batch_size=32,
...        preprocessing=lambda x,y: (x, (x, y))
...     )
...
>>> w = w.from_array(data=data,
...        input_columns=['test'],
...        label_columns=['test'])
>>>
>>> trend_block = TrendBlock(label_width=w.label_width,
...                          p_degree=2,
...                          n_neurons=16,
...                          drop_rate=0.1,
...                          name="trend_block")
>>>
>>> seasonality_block = SeasonalityBlock(label_width=w.label_width,
...                                      forecast_periods=[10],
...                                      backcast_periods=[20],
...                                      forecast_fourier_order=[10],
...                                      backcast_fourier_order=[20],
...                                      n_neurons=15,
...                                      drop_rate=0.1,
...                                      name="seasonality_block")
>>>
>>> trend_blocks = [trend_block for _ in range(3)]
>>> seasonality_blocks = [seasonality_block for _ in range(3)]
>>> trend_stacks = Stack(trend_blocks, name="trend_stack")
>>> seasonality_stacks = Stack(seasonality_blocks, name="seasonality_stack")
>>>
>>> model = NBEATS([trend_stacks, seasonality_stacks], name="interpretable_NBEATS")
>>> model.compile(loss=QuantileLossError(quantiles=[0.5]))
>>> history = model.fit(w.train, verbose=0)
Attributes
stackstuple[Tensor]

Return the input width.

seasonalityTensor

Based on the paper, the seasonality is available if the previous stacks are composed by trend blocks.

trendTensor

The trend component of the output.

stack_outputsTensor
is_interpretablebool

Return True if the model is interpretable.

nbeats_typestr

Return the Nbeats type.

label_widthint

Return the label width.

input_widthint

Return the input width.

compile(optimizer='rmsprop', loss=None, metrics=None, loss_weights=[0.0, 1.0], weighted_metrics=None, run_eagerly=None, steps_per_execution=None, **kwargs) → None[source]#

Compile method from tensorflow.

When compiling with losses defining a quantiles attribute it propagates this attribute to the submodels and sublayers.

property input_width: int#

Return the input width.

property is_interpretable: bool#

Return True if the model is interpretable.

property label_width: int#

Return the label width.

property nbeats_type: str#

Return the Nbeats type.

seasonality(data: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]#

Based on the paper, the seasonality is available if the previous stacks are composed by trend blocks. Else, it doesn’t correspond to seasonality.

Parameters
dataTensor

input data.

Returns
seasonalityTensor

Same shape as call inputs (see notes).

Raises
AttributeError

If all previous stacks are not composed by trend blocks then an error is raised.

AssertionError

if no SeasonalityStack are defined.

property stacks: int#

Return the input width.

trend(data: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]#

The trend component of the output.

Returns
trendTensor

Same shape as call inputs (see notes).

Raises
AttributeError

Raises an error if previous stacks are not TrendBlock.

Examples using autopycoin.models.NBEATS#

Plotting NBEATS output

Plotting NBEATS output#