QATS

Python library and GUI for efficient processing and visualization of time series.

General

About

The python library provides tools for:

• Import and export from/to various pre-defined time series file formats
• Signal processing
• Inferring statistical distributions
• Cycle counting using the Rainflow algorithm

It was originally created to handle time series files exported from SIMO and RIFLEX. Now it also handles SIMA hdf5 (.h5) files, MATLAB .mat files (versions 4, 6, 7 and 7.3), OpenFAST .out and .outb files, Bladed output (.%NN and .$NN), CSV files and more.

QATS also features a GUI which offers efficient and low threshold processing and visualization of time series. It is perfect for inspecting, comparing and reporting:

• time series
• power spectral density distributions
• peak and extreme distributions
• cycle distributions

Demo

Getting started

Installation

QATS supports the Python versions that are officially supported, i.e. those with status bugfix or security in the status of Python versions. QATS 5.4 supports Python 3.11, 3.12, 3.13 and 3.14; the PyPI page shows the versions supported by the latest release.

On Python 3.8, 3.9 or 3.10, stay on QATS 5.3. pip selects it automatically, since QATS 5.4 and later require Python 3.11 or later.

Run the below command in a Python environment to install the latest QATS release:

python -m pip install qats

To upgrade from a previous version, the command is:

python -m pip install --upgrade qats

QATS is also on conda-forge. With conda (or mamba), install it in a new environment:

conda create -n qats -c conda-forge qats

or in an existing one with conda install -c conda-forge qats, and upgrade it with conda update -c conda-forge qats. A new release appears on conda-forge shortly after it is published on PyPI. In a conda environment, install and upgrade QATS with conda only: installing it with pip there mixes packages from both sources.

You may now import qats in your own scripts:

>>> from qats import TsDB, TimeSeries

... or use the GUI to inspect time series.

The GUI uses the Qt binding PySide6, which is installed with qats and is the binding QATS is tested with. PyQt6 also works, through qtpy, but is supported on a best-effort basis only. To use it, install it and select it with the environment variable QT_API:

python -m pip install pyqt6
set QT_API=pyqt6

(On Linux and macOS: export QT_API=pyqt6.) Accepted values of QT_API include pyside6 and pyqt6; see the qtpy README for details.

The GUI may now be launched by:

qats app

To create a start menu link, which you can even pin to the taskbar to ease access to the QATS GUI, run the following command:

qats config --link-app

Take a look at the resources listed below to learn more.

New in version 4.11.0. The command line interface is also accessible by running Python with the '-m' option. The following commands are equvivalent to those above:

python -m qats app
python -m qats config --link-app

Resources

• Source
• Issues
• Release notes
• Documentation
• Download

Contribute

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

Install uv with the official installer. uv installs a suitable Python version automatically if you don't have one.

Clone the source code repository

At the desired location, run:

git clone https://github.com/dnvgl/qats.git

The package version is derived from Git tags (using setuptools-scm), so clone the full repository with tags rather than downloading a source archive.

Installing

To get the development environment running, run from the repository root:

uv sync

This will

• create an isolated environment in .venv
• install the locked dependencies from uv.lock, including those required for development, testing and building documentation (the dev and docs dependency groups)
• and install the package in development ("editable") mode

To use a specific Python version, e.g. 3.12, run uv sync --python 3.12.

Prefix commands with uv run to run them in the environment (or activate .venv first). You should now be able to import the package in the Python console,

uv run python

>>> import qats
>>> help(qats)

... and use the command line interface (CLI).

uv run qats -h

New in version 4.11.0. The CLI is also available from

uv run python -m qats -h

To add or update a dependency, use uv add (e.g. uv add "numpy>=2" or uv add --dev pytest) rather than editing pyproject.toml by hand, so that uv.lock is updated as well. Commit both files.

Running the tests

The automated tests are run using pytest.

uv run pytest test/

Linting and formatting

Code is linted and formatted with ruff, configured in pyproject.toml. CI fails if either check finds a problem, so run them before pushing:

uv run ruff check .
uv run ruff format --check .

To fix what can be fixed automatically and reformat the code:

uv run ruff check --fix .
uv run ruff format .

The commit that first formatted the code base with ruff is listed in .git-blame-ignore-revs. To have git blame skip it locally (GitHub does this automatically), run once:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Deprecating an API

5.x releases only add to the API. A change that would break user code (removing or renaming a function, class, parameter or module, or changing what it returns) goes into the next major release, and is announced with a DeprecationWarning in 5.x first. Use the helper in qats._deprecation, so that all warnings look the same and point to the line in the user's code:

from .._deprecation import warn_deprecated


def old_function(x):
    """
    Short description.

    .. deprecated :: 5.5.0
        `old_function()` will be removed in QATS 6.0.0. Use :func:`new_function` instead.
    """
    warn_deprecated("qats.module.old_function()", "5.5.0", "6.0.0", alternative="qats.module.new_function()")
    return new_function(x)

• Warn where the user calls the deprecated API (the function, or __init__ of a class), not in code that QATS itself runs on every import.
• If the deprecated API is used internally, call a private version that does not warn, so that users get one warning and not several.
• Add a test that the warning is issued (assertWarns(DeprecationWarning)).

Building the package

Build tarball and wheel distributions by

uv build

The builds appear in the dist folder. The distributions adhere to the PEP 0427 convention {distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl.

Building the documentation

The html documentation is built using Sphinx

uv run sphinx-build -b html docs/source docs/_build

To force a build to read/write all files (always read all files and don't use a saved environment), include the -a and -E options:

uv run sphinx-build -a -E -b html docs/source docs/_build

Versioning

We apply the "major.minor.micro" versioning scheme defined in PEP 440. See also Scheme choices on https://packaging.python.org/.

Versions are tagged with Git tags like v3.0.1. See the tags on this repository.

Release and deployment

We use the release cycle in GitHub to cut new releases.

Once a new release is published, GitHub Actions takes care of the packaging and deployment to PyPi. Unit tests run on every push and pull request.

The workflows for continuous integration and deployment are found in .github/workflows.

Authors

• Per Voie - tovop
• Erling Lone - eneelo

License

This project is licensed under the MIT License - see the LICENSE file for details.