

<img src="https://raw.githubusercontent.com/daniel-om-weber/tsfast/refs/heads/master/assets/logo.svg" width="200" align="left" alt="tsfast logo">

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## TSFast

[![PyPI
version](https://badge.fury.io/py/tsfast.svg)](https://badge.fury.io/py/tsfast)
[![License: Apache
2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Docs
Status](https://img.shields.io/badge/docs-up_to_date-brightgreen.svg)](https://daniel-om-weber.github.io/tsfast/)
[![Python
Versions](https://img.shields.io/pypi/pyversions/tsfast.png)](https://pypi.org/project/tsfast/)

## Description

> `tsfast` is an open-source deep learning library for time series
> analysis and system identification tasks. Built on PyTorch & fastai,
> it offers efficient deep learning models and utilities.

`tsfast` is an open-source deep learning package that focuses on system
identification and time series analysis tasks. Built on the foundations
of PyTorch and fastai, it provides efficient implementations of various
deep learning models and utilities.

## Key Features

- **Specialized Data Handling for Time Series**:
  - Employs `SequenceBlock` (built on `fastai.TransformBlock`) for
    robust sequence data processing pipelines.
  - Includes a range of transforms tailored for sequences, such as
    `SeqSlice`, `SeqNoiseInjection`, and `Normalize` adapted for time
    series tensors.
  - Features advanced data loading with `TbpttDl` (for Truncated
    Backpropagation Through Time), and factories for `WeightedDL` and
    `BatchLimitDL`.
- **Predefined Datasets & Helpers**: Offers easy-to-use benchmark
  datasets (e.g., `create_dls_silverbox` from `identibench`) for rapid
  prototyping and experimentation.
- **Tailored Time Series Models**: Provides implementations of Recurrent
  Neural Networks (RNNs, including
  [`DenseNet_RNN`](https://daniel-om-weber.github.io/tsfast/03_models/rnn.html#densenet_rnn),
  [`ResidualBlock_RNN`](https://daniel-om-weber.github.io/tsfast/03_models/rnn.html#residualblock_rnn)),
  Convolutional Neural Networks (TCNs,
  [`CausalConv1d`](https://daniel-om-weber.github.io/tsfast/03_models/cnn.html#causalconv1d)),
  and combined architectures
  ([`CRNN`](https://daniel-om-weber.github.io/tsfast/03_models/cnn.html#crnn),
  [`SeperateCRNN`](https://daniel-om-weber.github.io/tsfast/03_models/cnn.html#seperatecrnn))
  specifically designed for sequence modeling. Includes building blocks
  like
  [`SeqLinear`](https://daniel-om-weber.github.io/tsfast/03_models/layers.html#seqlinear)
  and stateful batch normalization.
- **Integrated `fastai` Learner**: Features
  [`RNNLearner`](https://daniel-om-weber.github.io/tsfast/02_learner/learner.html#rnnlearner),
  [`TCNLearner`](https://daniel-om-weber.github.io/tsfast/02_learner/learner.html#tcnlearner),
  [`CRNNLearner`](https://daniel-om-weber.github.io/tsfast/02_learner/learner.html#crnnlearner),
  etc., extending `fastai`’s `Learner` for streamlined model training,
  equipped with custom time-series losses (e.g.,
  [`fun_rmse`](https://daniel-om-weber.github.io/tsfast/02_learner/losses.html#fun_rmse),
  [`nrmse`](https://daniel-om-weber.github.io/tsfast/02_learner/losses.html#nrmse))
  and callbacks (e.g.,
  [`TbpttResetCB`](https://daniel-om-weber.github.io/tsfast/00_data/loader.html#tbpttresetcb),
  [`ARInitCB`](https://daniel-om-weber.github.io/tsfast/02_learner/callbacks.html#arinitcb),
  [`SkipFirstNCallback`](https://daniel-om-weber.github.io/tsfast/02_learner/callbacks.html#skipfirstncallback)).
- **System Identification & Prediction**:
  - Supports simulation (prediction based on inputs) and N-step ahead
    forecasting.
  - Includes specialized models and callbacks for system identification
    tasks like FRANSYS (`FranSys`, `FranSysCallback`) and AR models
    (`AR_Model`, `ARProg`).
  - Provides an `InferenceWrapper` for easier model deployment and
    prediction.
- **Hyperparameter Optimization**: Integrates with Ray Tune via
  [`HPOptimizer`](https://daniel-om-weber.github.io/tsfast/tune.html#hpoptimizer)
  for efficient hyperparameter searching.

## Installation

You can install the **latest stable** version from pip using:

``` python
pip install tsfast
```

For development installation:

``` python
git clone https://github.com/daniel-om-weber/tsfast
cd tsfast
pip install -e '.[dev]'
```

## Quick Start

Here is a quick example using a benchmark dataloader. It demonstrates
loading and visualizing data, training a RNN, and visualizing the
results.

``` python
from tsfast.basics import *
dls = create_dls_silverbox()
dls.show_batch(max_n=1)
```

![](index_files/figure-commonmark/cell-2-output-1.png)

``` python
lrn = RNNLearner(dls)
lrn.fit_flat_cos(1)
```

<style>
    /* Turns off some styling */
    progress {
        /* gets rid of default border in Firefox and Opera. */
        border: none;
        /* Needs to be in here for Safari polyfill so background images work as expected. */
        background-size: auto;
    }
    progress:not([value]), progress:not([value])::-webkit-progress-bar {
        background: repeating-linear-gradient(45deg, #7e7e7e, #7e7e7e 10px, #5c5c5c 10px, #5c5c5c 20px);
    }
    .progress-bar-interrupted, .progress-bar-interrupted::-webkit-progress-bar {
        background: #F44336;
    }
</style>

| epoch | train_loss | valid_loss | fun_rmse | time  |
|-------|------------|------------|----------|-------|
| 0     | 0.006716   | 0.006925   | 0.015471 | 01:55 |

``` python
lrn.show_results(max_n=1)
```

<style>
    /* Turns off some styling */
    progress {
        /* gets rid of default border in Firefox and Opera. */
        border: none;
        /* Needs to be in here for Safari polyfill so background images work as expected. */
        background-size: auto;
    }
    progress:not([value]), progress:not([value])::-webkit-progress-bar {
        background: repeating-linear-gradient(45deg, #7e7e7e, #7e7e7e 10px, #5c5c5c 10px, #5c5c5c 20px);
    }
    .progress-bar-interrupted, .progress-bar-interrupted::-webkit-progress-bar {
        background: #F44336;
    }
</style>

![](index_files/figure-commonmark/cell-4-output-3.png)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
For major changes, please open an issue first to discuss what you would
like to change.

## Citation

If you use tsfast in your research, please cite:

``` text
@Misc{tsfast,
author = {Daniel O.M. Weber},
title = {tsfast - A deep learning library for time series analysis and system identification},
howpublished = {Github},
year = {2024},
url = {https://github.com/daniel-om-weber/tsfast}
}
```
