Quick Start¶

Prepare our Dataset¶

In torchcast we set up our data and model with the following:

• The groups which define separate time-serieses. Here we have multiple sites. Groups are not necessarily simultanoues to each other (e.g. we could have time-series of product purchases with products having varying release-dates) and correlations across these groups are not modeled.

• The measures which define separate metrics we are measuring simultanously. Here we have the two kinds of particulate-matter (2.5 and 10).

The TimeSeriesDataset is similar to PyTorch’s native TensorDataset, with some useful metadata on the batch of time-serieses (the station names, the dates for each).

For a quick example, we’ll focus on predicting particulate-matter (PM2.5 and PM10). We’ll log-transform since this is strictly positive.

[3]:

df_aq['PM2p5_log10'] = np.log10(df_aq['PM2p5'])
df_aq['PM10_log10'] = np.log10(df_aq['PM10'])

# create a dataset:
dataset_all = TimeSeriesDataset.from_dataframe(
    dataframe=df_aq,
    dt_unit='W',
    measure_colnames=['PM2p5_log10', 'PM10_log10'],
    group_colname='station',
    time_colname='week'
)

# Split out training period:
SPLIT_DT = np.datetime64('2016-02-22')
dataset_train, _ = dataset_all.train_val_split(dt=SPLIT_DT)
dataset_train

[3]:

TimeSeriesDataset(sizes=[torch.Size([12, 156, 2])], measures=(('PM2p5_log10', 'PM10_log10'),))

Specify our Model¶

In torchcast our forecasting model is defined by measures and processes. The processes give rise to the measure-able behavior. Here we’ll specify a random-walk/trend component and a yearly seasonal component for each pollutant.

[4]:

processes = []
for m in dataset_train.measures[0]:
    processes.extend([
        LocalTrend(id=f'{m}_trend', measure=m),
        Season(id=f'{m}_day_in_year', period=365.25 / 7, dt_unit='W', K=3, measure=m, fixed=True)
    ])
kf_first = KalmanFilter(measures=dataset_train.measures[0], processes=processes)

Train our Model¶

The KalmanFilter class provides a convenient fit() method that’s useful for avoiding standard boilerplate for full-batch training:

[5]:

kf_first.fit(
    dataset_train.tensors[0],
    start_offsets=dataset_train.start_datetimes
)

Initializing PM2p5_log10_trend.position to 1.8530830144882202
Initializing PM10_log10_trend.position to 1.9869805574417114

[5]:

KalmanFilter(processes=[LocalTrend(id='PM2p5_log10_trend'), Season(id='PM2p5_log10_day_in_year'), LocalTrend(id='PM10_log10_trend'), Season(id='PM10_log10_day_in_year')], measures=['PM2p5_log10', 'PM10_log10'])

Calling forward() on our KalmanFilter produces a Predictions object. If you’re writing your own training loop, you’d simply use the log_prob() method as the loss function:

[6]:

pred = kf_first(
        dataset_train.tensors[0],
        start_offsets=dataset_train.start_datetimes,
        out_timesteps=dataset_all.tensors[0].shape[1]
)

loss = -pred.log_prob(dataset_train.tensors[0]).mean()
print(loss)

tensor(-0.7233, grad_fn=<NegBackward0>)

Inspect & Visualize our Output¶

Predictions can easily be converted to Pandas DataFrames for ease of inspecting predictions, comparing them to actuals, and visualizing:

[7]:

df_pred = pred.to_dataframe(dataset_all)
df_pred[['actual','mean','upper','lower']] = 10 ** df_pred[['actual','mean','upper','lower']]
df_pred

[7]:

[8]:

df_pred['percent_error'] = np.abs(df_pred['mean'] - df_pred['actual']) / df_pred['actual']
print("Percent Error: {:.1%}".format(df_pred.query("time>@SPLIT_DT")['percent_error'].mean()))

Percent Error: 35.4%

The Predictions class comes with a plot classmethod for getting simple plots of forecasted vs. actual:

[9]:

pred.plot(df_pred.query("group=='Changping'"), split_dt=SPLIT_DT, time_colname='time', group_colname='group')

Finally you can produce dataframes that decompose the predictions into the underlying processes that produced them:

[10]:

pred.plot(
    pred.to_dataframe(dataset_all, type='components').query("group=='Changping'"), split_dt=SPLIT_DT,
    time_colname='time', group_colname='group'
)

[ ]: