pycatch22: CAnonical Time-series CHaracteristics in python

About

catch22 is a collection of 22 time-series features coded in C that can be run from Python, as well as R, Matlab, and Julia.

This package provides a python implementation as the module pycatch22, licensed under the GNU GPL v3 license (or later).

What do the features do?

This GitBooks website is dedicated to describing the features. For their implementation in code, see the main catch22 repository. There is also information in the associated paper 📗 Lubba et al. (2019)..

Acknowledgement :+1:

If you use this software, please read and cite this open-access article:

• 📗 Lubba et al. catch22: CAnonical Time-series CHaracteristics, Data Min Knowl Disc 33, 1821 (2019).

Installation

Using pip for pycatch22:

pip install pycatch22

If this doesn't work, make sure you are using the latest setuptools: pip install setuptools --upgrade.

If you come across errors with version resolution, you should try something like: pip install pycatch22==0.4.2 --use-deprecated=legacy-resolver.

It is also a package on anaconda thanks to @rpanai, which you can install via conda:

conda install -c conda-forge pycatch22

or mamba:

mamba install -c conda-forge pycatch22

[A manual install (bottom of this page) is a last resort.]

Usage

Each feature function can be accessed individually and takes arrays as tuple or lists (not numpy arrays). For example, for loaded data tsData in Python:

import pycatch22
tsData = [1,2,4,3] # (or more interesting data!)
pycatch22.CO_f1ecac(tsData)

All features are bundled in the method catch22_all, which also accepts numpy arrays and gives back a dictionary containing the entries catch22_all['names'] for feature names and catch22_all['values'] for feature outputs.

Usage (computing 22 features: catch22):

pycatch22.catch22_all(tsData)

Usage (computing 24 features: catch24 = catch22 + mean + standard deviation):

pycatch22.catch22_all(tsData,catch24=True)

We also include a 'short name' for each feature for easier reference (as outlined in the GitBook Feature overview table). These short names can be included in the output from catch22_all() by setting short_names=True as follows:

pycatch22.catch22_all(tsData,catch24=True,short_names=True)

Template analysis script

Thanks to @jmoo2880 for putting together a demonstration notebook for using pycatch22 to extract features from a time-series dataset.

Usage notes

• When presenting results using catch22, you must identify the version used to allow clear reproduction of your results. For example, CO_f1ecac was altered from an integer-valued output to a linearly interpolated real-valued output from v0.3.
• Important Note: catch22 features only evaluate dynamical properties of time series and do not respond to basic differences in the location (e.g., mean) or spread (e.g., variance).
  • From catch22 v0.3, If the location and spread of the raw time-series distribution may be important for your application, we suggest applying the function argument catch24 = True to your call to the catch22 function in the language of your choice. This will result in 24 features being calculated: the catch22 features in addition to mean and standard deviation.

Manual install

The upstream catch22 C sources are vendored as a git submodule, so clone with submodules before building from source:

git clone --recurse-submodules https://github.com/DynamicsAndNeuralSystems/pycatch22.git

(If you already cloned without --recurse-submodules, run git submodule update --init from the repository root.)

If you find issues with the pip install, you can also install using setuptools:

python3 setup.py build
python3 setup.py install