catch22: CAnonical Time-series CHaracteristics

catch22 is a set of 22 time-series features, implemented in C and available in Python, R, Julia and MATLAB. The features are a high-performing, minimally redundant subset of the more than 7000 features in hctsa, selected for their classification performance across 93 real-world time-series classification problems (Lubba et al., 2019). They capture properties of a time series's dynamics, such as its autocorrelation, distribution of values, extreme events, scaling and predictability, and are fast to compute.

📖 Full documentation: time-series-features.gitbook.io/catch22, covering installation, what each feature measures, and publications that use catch22.

Installation

Language	Package	Latest	Install
Python	pycatch22		pip install pycatch22 or conda install -c conda-forge pycatch22
R	Rcatch22		install.packages("Rcatch22")
Julia	Catch22.jl		] add Catch22
MATLAB	wrap_Matlab/ in this repository		compile with mexAll (instructions)
C	C/ in this repository		gcc -O2 C/*.c -o run_features -lm

Quick start

In Python:

import pycatch22

x = [0.1, 0.4, 0.3, 0.9, 0.5, 0.2, 0.7, 0.6, 0.8, 0.3]  # your time series
results = pycatch22.catch22_all(x, catch24=True)  # a dict of 'names' and 'values'

From the command line, with one value per line in series.txt:

./run_features --catch24 series.txt features.txt
./run_features --list  # the features, their earlier names, and their hctsa calls

Each line of the output is a feature value, its name, and its computation time in milliseconds.

See the documentation for usage in each language.

The features

The 22 features (plus the 2 extra catch24 features)

Short name	Feature name	What it measures
mode_5	DN_HistogramMode_5	Mode of the z-scored distribution (5-bin histogram)
mode_10	DN_HistogramMode_10	Mode of the z-scored distribution (10-bin histogram)
outlier_timing_pos	DN_OutlierInclude_p_001_mdrmd	Timing of extreme positive values
outlier_timing_neg	DN_OutlierInclude_n_001_mdrmd	Timing of extreme negative values
acf_timescale	CO_FirstCrossing_acf_1e_pointOfCrossing	First 1/e crossing of the autocorrelation function
acf_first_min	CO_FirstMin_ac	First minimum of the autocorrelation function
low_freq_power	SP_Summaries_fft_area_5_1	Power in the lowest fifth of frequencies
median_freq	SP_Summaries_fft_wq_50	Median frequency of the power spectrum
forecast_error	FC_LocalSimple_mean3_stde	Error of a rolling 3-sample mean forecast
whiten_timescale	FC_LocalSimple_mean1_taurat	Change in autocorrelation timescale after differencing
high_fluctuation	MD_pNN_pnn40	Proportion of large successive differences
stretch_high	SB_BinaryStats_mean_longstretch1	Longest stretch of above-mean values
stretch_decreasing	SB_BinaryStats_diff_longstretch0	Longest stretch of non-increasing steps
entropy_pairs	SB_MotifThree_quantile_hh	Entropy of successive pairs in a 3-letter symbolization
ami2	CO_HistogramAMI_even_5bin_ami2	Automutual information at lag 2 (5-bin histogram)
trev	CO_trev_1_num	Time-reversibility statistic
ami_timescale	IN_AutoMutualInfoStats_40_gaussian_fmmi	First minimum of the automutual information function
transition_variance	SB_TransitionMatrix_quantile_3_ac_sumdiagcov	Variance in the transition matrix of a 3-letter symbolization
periodicity	PD_PeriodicityWang_th0_01	Periodicity measure of Wang et al. (2007)
embedding_dist	CO_Embed2_Dist_tau_d_expfit_meandiff	Exponential fit to distances in a 2-d embedding
rs_range	SC_FluctAnal_2_rsrangefit_50_1_logi_prop_r1	Rescaled-range fluctuation analysis
dfa	SC_FluctAnal_2_dfa_50_1_2_logi_prop_r1	Detrended fluctuation analysis
mean	DN_mean	Mean (catch24 only)
std	DN_Spread_std	Standard deviation (catch24 only)

The list is also in featureList.txt, with each feature's name before v1.0 and the hctsa call that reproduces it. The documentation describes each feature in detail.

Usage notes

• Location and spread. Each time series is z-scored before the 22 features are computed, so they measure its dynamics and are insensitive to its mean and variance. If the mean and spread matter for your application, compute catch24 (e.g., catch24=True in Python, catch24 = TRUE in R), which adds the mean and standard deviation.
• Features that cannot be estimated (e.g., for a constant series, or dfa on a series shorter than 79 samples) are set by default to a fixed value at the appropriate end of their range, so you always get 22 real numbers. This masking can be switched off to get NaN instead (e.g., --no-mask on the command line). A series containing NaN or Inf gives NaN for every feature.
• Exact match with hctsa. Each feature reproduces a feature of hctsa v3.0.0, the final MATLAB release, given by a function call listed in featureList.txt. The C is tested against these calls to a relative tolerance of 10⁻⁹ (see tests/).
• Sampling. A time series is an ordered sequence of values without time stamps, assumed to be evenly sampled.

Versions

Feature values can change between versions, so report the version of catch22 you used so that your results can be reproduced.

• v1.0: every feature now exactly reproduces its hctsa v3.0.0 definition, so values change for most features. Several features are renamed to their hctsa names, and centroid_freq is replaced by the median frequency, median_freq. Features that cannot be estimated are masked rather than returning NaN (see above). Classification accuracy is unchanged across 140 UCR/UEA datasets. The documentation describes how each feature changed.
• v0.6.0: four features were corrected to match their MATLAB (hctsa) definitions. PD_PeriodicityWang_th0_01 and IN_AutoMutualInfoStats_40_gaussian_fmmi return the lag itself (previously the lag minus one). SB_BinaryStats_mean_longstretch1 and SB_BinaryStats_diff_longstretch0 return the exact run length (previously one more for runs not at the start of the series), and zero differences count as non-increases in SB_BinaryStats_diff_longstretch0.
• v0.3: CO_f1ecac changed from an integer to a linearly interpolated real value.

See the releases for details.

Citing catch22

If you use catch22, please cite the open-access paper:

C. H. Lubba, S. S. Sethi, P. Knaute, S. R. Schultz, B. D. Fulcher, N. S. Jones. catch22: CAnonical Time-series CHaracteristics. Data Mining and Knowledge Discovery 33, 1821–1852 (2019).

BibTeX

@article{lubba2019catch22,
  title   = {catch22: {CA}nonical {T}ime-series {CH}aracteristics},
  author  = {Lubba, Carl H. and Sethi, Sarab S. and Knaute, Philip and Schultz, Simon R. and Fulcher, Ben D. and Jones, Nick S.},
  journal = {Data Mining and Knowledge Discovery},
  volume  = {33},
  number  = {6},
  pages   = {1821--1852},
  year    = {2019},
  doi     = {10.1007/s10618-019-00647-x}
}

License

catch22 is licensed under the GNU GPL v3 (or later).