UPDATE: new code released with changes in our architecture. Please see the release notes for details (Nov/2020)
This repository has the open source implementation of a new architecture termed STConvS2S. To sum up, our approach (STConvS2S) uses only 3D convolutional neural network (CNN) to tackle the sequence-to-sequence task using spatiotemporal data. We compare our results with state-of-the-art architectures. Details in the article published in Neurocomputing, Elsevier (arXiv versions).
Mainly, our code uses Python 3.6 and PyTorch 1.0. See config/environment.yml for other requirements.
To install packages with the same version as we executed our experiments, run the code below:
cd config
./create-env.sh
All datasets are publicly available at http://doi.org/10.5281/zenodo.3558773. Datasets must be placed in the data folder.
Note: In the 15-step ahead datasets, just for the convenience of having the input and targe tensors in the same file, we define them in the same shape (# of samples, 15, # of latitude, # of longitude, 1). However, in the code, we force the correct length of the input sequence in the tensor as shown here.
Jupyter notebooks for the first sequence-to-sequence task (given the previous 5 grids, predict the next 5 grids) can be found in the notebooks folder (see Table 1 and 3 in the paper).
Final experiments (see Table 2 in the paper) compare STConvS2S (our architecture) with deep learning state-of-the-art architectures and ARIMA models. We evaluate the models in two horizons: 5 and 15-steps ahead. This task is performed using main.py (for deep learning models) and arima.py (for ARIMA models). Results can be found in the output folder.
-
/output/full-dataset(for deep learning models)/checkpoints: pre-trained models that allow you to recreate the training configuration (weights, loss, optimizer)./losses: training and validation losses. Can be used to recreate the error analysis plot/plots: error analysis plots from training phase/results: evaluation phase results with metric value (RMSE and MAE), training time, best epochs and so on.
-
/output/arima(for ARIMA models)
First load the conda environment with the installed packages.
source activate pytorch
Below are examples of how to run each model.
STConvS2S
< 7DCA a id="user-content-stconvs2s" class="anchor" aria-label="Permalink: STConvS2S" href="#stconvs2s">We provide two variants of the STConvS2S architecture that satisfy the causal constraint. Each can be executed as follows (complete example of how we performed the exepriments, here)
python main.py -i 3 -v 4 -m stconvs2s-r --plot > output/full-dataset/results/cfsr-stconvs2s-rmse-v4.out
The above command executes STConvS2S-R (-m stconvs2s-r) in 3 iterations (-i), indicating the model version (-v), allowing the generation of plots in the training phase (--plot).
To run experiments with this architecture, switch to the -m stconvs2s-c parameter.
python arima.py > output/arima/cfsr-arima.out
- add
--chirps: change the dataset to rainfall (CHIRPS). Default dataset: temperature (CFSR). - add
-s 15: change the horizon. Default horizon: 5. - add
-l 3 -d 32 -k 5: define the number of layers (l), filters (d) and the kernel size (-k). - add
--email: send email at the end. To use this functionality, set your email in the file config/mail_config.ini. - add
--small-dataset: have a quick training using a few sample dataset.
Check out the other possible parameters here.
@article{Castro2021,
author = "Rafaela Castro and Yania M. Souto and Eduardo Ogasawara and Fabio Porto and Eduardo Bezerra",
title = "STConvS2S: Spatiotemporal Convolutional Sequence to Sequence Network for Weather Forecasting",
journal = "Neurocomputing",
volume = "426",
pages = "285 - 298",
year = "2021",
issn = "0925-2312",
doi = "https://doi.org/10.1016/j.neucom.2020.09.060"
}
To give your opinion about this work, send an email to rafaela.nascimento@eic.cefet-rj.br.