/flow-forecast

Deep learning PyTorch library for time series forecasting, classification, and anomaly detection (originally for flood forecasting).

Primary LanguagePythonGNU General Public License v3.0GPL-3.0

Deep learning for time series forecasting

Example image Flow Forecast (FF) is an open-source deep learning for time series forecasting framework. It provides all the latest state of the art models (transformers, attention models, GRUs, ODEs) and cutting edge concepts with easy to understand interpretability metrics, cloud provider integration, and model serving capabilities. Flow Forecast was the first time series framework to feature support for transformer based models and remains the only true end-to-end deep learning for time series framework. Currently, Task-TS from CoronaWhy primarily maintains this repository. Pull requests are welcome. Historically, this repository provided open source benchmark and codes for flash flood and river flow forecasting.

For additional tutorials and examples please see our tutorials repository.

branch status $$
master CircleCI
Build PY Upload Python Package
Documentation Documentation Status
CodeCov codecov
CodeFactor CodeFactor

Getting Started

Using the library

  1. Run pip install flood-forecast
  2. Detailed info on training models can be found on the Wiki.
  3. Check out our Confluence Documentation

Models currently supported

  1. Vanilla LSTM (LSTM): A basic LSTM that is suitable for multivariate time series forecasting and transfer learning.
  2. Full transformer (SimpleTransformer in model_dict): The full original transformer with all 8 encoder and decoder blocks. Requires passing the target in at inference.
  3. Simple Multi-Head Attention (MultiHeadSimple): A simple multi-head attention block and linear embedding layers. Suitable for transfer learning.
  4. Transformer with a linear decoder (CustomTransformerDecoder in model_dict): A transformer with n-encoder blocks (this is tunable) and a linear decoder. Suitable for forecasting, classification or anomaly detection.
  5. DA-RNN: (DARNN) A well rounded model with which utilizes a LSTM + attention.
  6. Enhancing the Locality and Breaking the Memory Bottleneck of Transformer on Time Series Forecasting (called DecoderTransformer in model_dict):
  7. Transformer XL: Porting Transformer XL for time series.
  8. Informer: Beyond Efficient Transformer for Long Sequence Time-Series Forecasting (Informer)
  9. DeepAR
  10. DSANet: Model from the DSANet paper with additional optional parameters.
  11. Simple Linear Model (SimpleLinearModel): Essentially a linear regression model with a few more layers. Great for rapid prototyping of features and interpretability.
  12. Vanilla GRU with optional probablistic output layer. Good for multivariate time series forecasting and classification.
  13. DLinear and NLinear from the AAAI paper Are Transformers Effective for Time Series Forecasting
  14. Crossformer from ICLR 2023
  15. Anomaly Transformer
  16. TSMixer
  17. Inverted Transformer + Various Attention Mechanisms

Forthcoming Models

We have a number of models we are planning on releasing soon. Please check our project board for more info

Integrations

Google Cloud Platform

Weights and Biases

Contributing

For instructions on contributing please see our contributions page and our project board.

Historical River Flow Data

Task 1 Stream Flow Forecasting

This task focuses on forecasting a stream's future flow/height (in either cfs or feet respectively) given factors such as current flow, temperature, and precipitation. In the future we plan on adding more variables that help with the stream flow prediction such as snow pack data and the surrounding soil moisture index.

Task 2 Flood severity forecasting

Task two focuses on predicting the severity of the flood based on the flood forecast, population information, and topography. Flood severity is defined based on several factors including the number of injuires, property damage, and crop damage.

If you use either the data or code from this repository please use the citation below. Additionally please cite the original authors of the models.

@misc{godfried2020flowdb,
      title={FlowDB a large scale precipitation, river, and flash flood dataset}, 
      author={Isaac Godfried and Kriti Mahajan and Maggie Wang and Kevin Li and Pranjalya Tiwari},
      year={2020},
      eprint={2012.11154},
      archivePrefix={arXiv},
      primaryClass={cs.AI}
}