Metadata-Version: 2.4
Name: tsfast
Version: 0.3.0
Summary: Deep learning library for time series analysis and system identification
Project-URL: Repository, https://github.com/daniel-om-weber/tsfast
Project-URL: Documentation, https://daniel-om-weber.github.io/tsfast
Author-email: Daniel Oliver Martin Weber <daniel.om.weber@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: deep-learning,fransys,pytorch,system-identification,time-series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: h5py
Requires-Dist: identibench
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: torch>=2.1
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: ipykernel; extra == 'dev'
Requires-Dist: jupytext; extra == 'dev'
Requires-Dist: nbmake; extra == 'dev'
Requires-Dist: onnx>=1.14; extra == 'dev'
Requires-Dist: onnxruntime<1.24,>=1.16; (python_version == '3.10') and extra == 'dev'
Requires-Dist: onnxruntime>=1.16; (python_version >= '3.11') and extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ray[tune]; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-jupyter>=0.25; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Provides-Extra: onnx
Requires-Dist: onnx>=1.14; extra == 'onnx'
Requires-Dist: onnxruntime<1.24,>=1.16; (python_version == '3.10') and extra == 'onnx'
Requires-Dist: onnxruntime>=1.16; (python_version >= '3.11') and extra == 'onnx'
Provides-Extra: tune
Requires-Dist: ray[tune]; extra == 'tune'
Description-Content-Type: text/markdown



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

## 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)
[![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,
> 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 PyTorch, it
provides efficient implementations of various deep learning models and
utilities.

## Key Features

- **Specialized Data Handling for Time Series**:
  - HDF5-backed data pipeline with signal blocks for flexible sequence
    data processing.
  - Includes a range of transforms tailored for sequences, such as
    noise injection and normalization adapted for time series tensors.
  - Features advanced data loading with TBPTT (Truncated
    Backpropagation Through Time) support.
- **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`, `ResidualBlock_RNN`),
  Convolutional Neural Networks (TCNs, `CausalConv1d`),
  and combined architectures (`CRNN`, `SeperateCRNN`)
  specifically designed for sequence modeling. Includes building blocks
  like `SeqLinear` and layer normalization.
- **Integrated Training**: Features `RNNLearner`, `TCNLearner`,
  `CRNNLearner`, etc., with a lightweight pure-PyTorch training loop,
  custom time-series losses (e.g., `fun_rmse`, `nrmse`), and composable
  transforms for augmentation and regularization.
- **System Identification & Prediction**:
  - Supports simulation (prediction based on inputs) and N-step ahead
    forecasting.
  - Includes specialized models for system identification
    tasks like FRANSYS (`FranSys`, `FranSysLearner`) and AR models
    (`AR_Model`, `ARProg`).
  - Provides an `InferenceWrapper` for easier model deployment and
    prediction.
- **Hyperparameter Optimization**: Integrates with Ray Tune via
  `HPOptimizer` for efficient hyperparameter searching.

## Installation

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

``` bash
pip install tsfast
```

For development installation:

``` bash
git clone https://github.com/daniel-om-weber/tsfast
cd tsfast
pip install -e '.[dev]'
# or using uv:
uv sync --extra 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 *

# Load benchmark dataset
dls = create_dls_silverbox()

# Train an RNN and visualize results
lrn = RNNLearner(dls)
lrn.fit_flat_cos(1)
lrn.show_results(max_n=1)
```

## 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}
}
```
