hctsa

hctsa is a Matlab software package for running highly comparative time-series analysis. It extracts thousands of time-series features from a collection of univariate time series and includes a range of tools for visualizing and analyzing the resulting time-series feature matrix, including:

1. Normalizing and clustering time-series data;
2. Producing low-dimensional representations of time-series data;
3. Identifying and interpreting discriminating features between different classes of time series; and
4. Fitting and evaluating multivariate classification models.

Feel free to email me for advice on applications of hctsa :nerd_face:

:snake: Python: future development of the hctsa feature library is planned to happen in pyhctsa, a native Python implementation that reproduces the hctsa v3.0.0 feature set.

Installation and quick start :arrow_down:

For users familiar with git (recommended), please make a fork of the repo and then clone it to your local machine. To update, after setting an upstream remote (git remote add upstream git://github.com/benfulcher/hctsa.git) you can use git pull upstream main. To obtain the latest toolboxes (like the optimized catch22 feature set) in one step, clone with git clone --recurse-submodules; otherwise startup.m will fetch the catch22 submodule for you automatically the first time it runs.

Users unfamiliar with git can instead download the repository by clicking the green "Code" button then "Download ZIP".

Once downloaded, you can install hctsa by running the install.m script (see docs for details), and then compute and explore a time-series feature matrix for a sample time-series dataset in a few lines of code:

TS_Init('INP_test_ts.mat','hctsa'); % format time series into HCTSA.mat
TS_Compute;                         % compute all features (uses Parallel Computing Toolbox if available)
TS_Normalize;                       % normalize the resulting feature matrix, into HCTSA_N.mat
TS_Cluster;                         % cluster time series and features by similarity
TS_PlotDataMatrix;                  % plot the clustered feature matrix

See the docs for how to bring in your own time-series data and for the many other analysis and visualization tools available.

Documentation 📖

Comprehensive documentation for hctsa, from getting started through to more advanced analyses is on GitBook.

There is also a lot of additional information in these docs, including:

• :point_right: Information about alternative feature sets (including the much faster catch22), and information about other time-series packages available in R, python, and Julia.
• :wavy_dash: The accompanying time-series data archive for this project, CompEngine.
• :floppy_disk: Downloadable hctsa feature matrices from time-series datasets with example workflows.
• :computer: Resources for distributing an hctsa computation on a computing cluster.
• :closed_book: A list of publications that have used hctsa to address different research questions.
• :information_desk_person: Frequently asked questions about hctsa and related feature-based time-series analyses.

Acknowledgement :+1:

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

• 📗 B.D. Fulcher and N.S. Jones. hctsa: A computational framework for automated time-series phenotyping using massive feature extraction. Cell Systems: 5, 527 (2017).
• 📗 B.D. Fulcher, M.A. Little, N.S. Jones. Highly comparative time-series analysis: the empirical structure of time series and their methods. J. Roy. Soc. Interface: 10, 83 (2013).

Feedback, as email, GitHub issues or pull requests, is much appreciated.

For commercial use of hctsa, including licensing and consulting, contact Engine Analytics.

Licenses

Two licenses apply to the two core functionalities of hctsa:

1. The framework for running hctsa analyses and visualizations is licensed as the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. A license for commercial use is available from Engine Analytics.

2. Code for computing features from time-series data is licensed as GNU General Public License version 3.

Many features in hctsa rely on external packages (provided for convenience in the Toolboxes directory, which each have their own associated license, outlined below) and Matlab Add-On Toolboxes. Note that, in the case that some of them are unavailable, hctsa can still be used, but only a reduced set of time-series features will be computed.

Matlab version: R2022a or later.

Matlab Add-On Toolboxes: Statistics and Machine Learning, Signal Processing, Curve Fitting, Wavelet, and Econometrics.

External Packages (provided):

• TISEAN package for nonlinear time-series analysis, version 3.0.1 (GPL license).
• Joseph T. Lizier's Java Information Dynamics Toolkit (JIDT) for studying information-theoretic measures of computation in complex systems, version 1.3 (GPL license).
• Time-series analysis code developed by Michael Small (unlicensed).
• Max Little's Time-series analysis code (GPL license).
• Sample Entropy code from Physionet (GPL license).
• ARFIT Toolbox for AR model estimation (unlicensed).
• gpml Toolbox for Gaussian Process regression model estimation, version 3.5 (FreeBSD license).
• Danilo P. Mandic's delay vector variance code (GPL license).
• Zoubin Ghahramani's Hidden Markov Model (HMM) code (MIT license).
• Danny Kaplan's Code for embedding statistics (GPL license).
• Ulrich Bauer's ripser persistent homology tool, version 1.2.1 (MIT license).
• Tolga Esat Özkurt's nonlinearity measure code (Özkurt et al., 2020) (unlicensed).
• The feature set, included as a git submodule (GPL license).