pyts: a scikit-learn shaped toolbox for time series classification

A classification library built on scikit-learn conventions

pyts describes itself with a short sentence: a Python package for time series classification. The interesting part is not that sentence but how the package is assembled. The README says the development of the package is in line with the one of the scikit-learn community, and points at the scikit-learn Development Guide as the reference, noting one difference: pyts uses Numba instead of Cython for optimization.

That single design choice has consequences worth noting before you install anything. Numba compiles Python functions at runtime through LLVM, so heavy inner loops in the dynamic time warping and shapelet code get real speed without a C toolchain. You pay for it with a heavyweight import and JIT compilation on first call. The classifiers are exposed as estimator classes, `KNeighborsClassifier`, `TimeSeriesForest`, `LearningShapelets` among them, which means the surrounding scikit-learn machinery applies to them: pipelines, cross validation, grid search, and joblib parallelism.

The project carries a JMLR paper, published in 2020 as volume 21, number 46, and a Zenodo DOI, so this is an academic package rather than a production service. The repository is licensed BSD-3-Clause, has 1880 stars and 181 forks, and was last pushed on 2026-10-05.

Installing against Python 3.11 and a rising dependency floor

The dependency floor is high and clearly stated. pyproject.toml pins `requires-python = ">=3.11,<3.16"`, and the README lists the same range with NumPy 1.24.0, SciPy 1.15.0, Scikit-Learn 1.6.0, Joblib 1.3.0 and Numba 0.60.0 as minimums. Matplotlib is only needed to run the examples. Install from PyPI or conda-forge:

pip install pyts

conda install -c conda-forge pyts

The README also offers a source install, which is the path to take if you want to read the code alongside the documentation:

git clone https://github.com/johannfaouzi/pyts.git
cd pyts
pip install .

The scipy floor of 1.15.0 is the constraint most likely to surprise you. That version is recent enough that an existing scientific Python environment may need an upgrade cascade before pyts will resolve, so budget for that rather than discovering it at install time. The classifier list in pyproject.toml also advertises Python 3.11 through 3.15, so forward compatibility is claimed for versions that did not exist when the package was first published.

Running the test suite from outside the source directory is a one-liner:

pytest pyts

What each module contributes to a classification pipeline

The module list is the best argument for the package, because it maps onto the stages of a real time series classification workflow. The `approximation` module covers the lossy summaries: Piecewise Aggregate Approximation, Symbolic Aggregate approXimation, the Discrete Fourier Transform, Multiple Coefficient Binning and Symbolic Fourier Approximation. The `image` module covers representations that turn a series into a matrix, namely Recurrence Plot, Gramian Angular Field and Markov Transition Field, which then feed an image classifier.

`bag_of_words` provides `WordExtractor` and `BagOfWords`, `metrics` provides dynamic time warping with several variants plus the BOSS metric, and `decomposition` currently holds exactly one algorithm, Singular Spectrum Analysis. `multivariate` supplies utilities for series with more than one channel, and `datasets` both generates toy sets and fetches from the UEA and UCR Time Series Classification Repository, which is the standard benchmark archive for this field.

The classifiers themselves are fewer than the transformations. `KNeighborsClassifier`, `SAXVSM`, `BOSSVS`, `LearningShapelets`, `TimeSeriesForest` and `TSBF` sit in `classification`, and the release history explains why that list is short: TimeSeriesForest and TSBF arrived only in 0.12.0, in October 2021. Most of the published accuracy comparisons in this field come from papers that are not scikit-learn estimators at all, so a package that prioritises API consistency will always implement fewer classifiers than the literature contains. Judge it as a clean subset rather than a complete survey.

A dependency the README does not mention

The README dependency list names six packages. pyproject.toml lists seven. The extra entry is `platformdirs>=4.0.0`, which appears in the `dependencies` array alongside numpy, scipy, scikit-learn, joblib and numba, but has no corresponding line in the README's Dependencies section.

Both facts are true at once and neither is wrong. platformdirs is not something you need to reason about when using the classifiers; it is infrastructure, almost certainly for locating a cache directory. The README is a summary aimed at someone deciding whether the package is for them, and this line was left out of it. But the README's list is headed "pyts requires", which is a stronger claim than a summary, so a reader pinning a frozen environment from the README alone will under-pin and may hit a resolution the maintainers did not test.

There is a second mismatch worth knowing about, and this one is a stale caveat rather than an omission. The module section opens with a note saying the content described corresponds to the main branch and not the latest released version, so you may have to install the latest version to use some of these features. At present that caveat does not describe reality: the main branch `pyproject.toml` declares `version = "0.14.0"`, and v0.14.0 was published on 2026-10-04, one day before the last push. The main branch and the released version currently agree, so the disclaimer is doing no work. It is a standing instruction to check your installed version rather than the website, and it is worth taking literally in the future rather than assuming it is always wrong.

Three years between releases, and an empty note for 0.14.0

The release history has three entries. v0.12.0 shipped on 2021-10-31, v0.13.0 on 2023-06-18, and v0.14.0 on 2026-10-04. The gap between the last two is three years and about four months, while the repository itself shows pushes as recent as 2026-10-05, so the project is being worked on and shipped slowly rather than abandoned.

What happened in those three years is not recorded on the release page. The v0.14.0 body is an empty string, and the name is the generic "Release of version 0.14.0". The two earlier releases both carry detailed notes, so this is a change in practice rather than a project that never bothered. The README itself points elsewhere for history, sending you to the changelog on ReadTheDocs, which is the place to look for what actually changed.

The 0.13.0 notes are the ones to read before upgrading an existing script, because they contain two breaking changes that a version number alone will not flag. One replaces the `base_estimator_` attribute with `estimator_`, which touches any code that reached into fitted attributes. The other pins the number of K-means initiations used for the initial shapelets in `LearningShapelets` to 10, explicitly to prevent a change in scikit-learn's default from altering pyts behaviour, and adds `chunksize` and `n_jobs` to Singular Spectrum Analysis so large decompositions can trade memory for time and run in parallel.

Reading the repository layout to see what is maintained

The root of the repository is small and tells you what kind of project this is: `.github/`, `.pre-commit-config.yaml`, `.codecov.yml`, `.readthedocs.yml`, `CONTRIBUTING.md`, `LICENSE.txt`, `MANIFEST.in`, `README.md`, `pyproject.toml`, `environment.yml`, `scripts/`, `doc/`, `examples/` and the `pyts/` package. A pre-commit config and a coverage config together say the project takes its own test suite seriously, which matters more for a numerical package than it would for a web library.

The `examples/` directory is organised by module rather than by tutorial, with subdirectories for approximation, bag_of_words, classification, clustering, datasets, decomposition, image, metrics, multivariate, preprocessing and transformation, plus a `plot_ts.py` at the top. Gallery-style examples organised per module is the layout scikit-learn itself uses, which reinforces that the project is deliberately tracking that ecosystem. Reading the classifier examples is often a faster way to understand expected input shapes than the API reference.

Development Status is recorded as `4 - Beta` in the package metadata, and the intended audience is listed as Science/Research and Developers. That is a fair summary of what you get: a well-organised, properly versioned research library with honest versioning and a real test suite, whose sharpest edges are documentation lags rather than code quality.

Editorial conclusion

pyts is most useful when you want time series classification to look like every other model in a scikit-learn based pipeline: estimator classes, fit and predict, joblib parallelism, and a consistent API. It earns its place by collecting algorithms that are scattered across separate papers into one importable namespace, and by exposing the intermediate transforms, since most of the accuracy gains come from the representation rather than the classifier. What the project does not give you is a migration story. The three year gap between versions, the empty release note for 0.14.0, and the missing dependency in the README all mean you should read the changelog on ReadTheDocs and the `estimator_` rename in the 0.13.0 notes before upgrading an existing script.

Frequently asked questions

Official sources

1. johannfaouzi/pyts on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases