hctsa is a software package for running highly comparative time-series analysis using Matlab (full support for versions R2018b or later).

The software provides a code framework that enables the extraction of thousands of time-series features from a time series (or a time-series dataset). It also provides a range of tools for visualizing and analyzing the resulting time-series feature matrix, including:

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

Feel free to email me for help with real-world applications of hctsa 🤓

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.

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

For users unfamiliar with git, the current version of the repository can be downloaded by simply clicking the green Clone or download button, and then clicking Download .zip.

It is recommended to use the repository with git. For this, please make a fork of it, clone it to your local machine, and then set an upstream remote to keep it synchronized with the main repository e.g., using the following code:

git remote add upstream git://github.com/benfulcher/hctsa.git

(make sure that you have generated an ssh key and associated it with your Github account).

You can then update to the latest stable version of the repository by pulling the master branch to your local repository:

git pull upstream master

For analyzing specific datasets, we recommend working outside of the repository so that incremental updates can be pulled from the upstream repository. Details on how to merge the latest version of the repository with the local changes in your fork can be found here.

CompEngine is an accompanying web resource for this project. It is a self-organizing database of time-series data that allows users to upload, explore, and compare thousands of diverse types of time-series data. This vast and growing collection of time-series data can also be downloaded. You can read more about it in our 📙preprint.

Is over 7000 just a few too many features for your application? Do you not have access to a Matlab license? catch22 has all of your faux-rhetorical questions covered. This reduced set of 22 features, determined through a combination of classification performance and mutual redundancy as explained in this paper, is available here as an efficiently coded C implementation with wrappers for python and R.

There are a range of open datasets with pre-computed hctsa features, as well as some examples of hctsa workflows.

• C. elegans movement speed data and associated analysis code.
• Drosophila movement speed and associated analysis code.
• 1000 empirical time series

(If you have data to share and host, let me know and I'll add it to this list)

Matlab code for computing features for an initialized HCTSA.mat file, by distributing the computation across a large number of cluster jobs (using pbs or slurm schedulers) is here.

Here we provide a list of publications that have used hctsa.

Where journal articles (📗) are not open access, we also provide a link to the preprint (📙). Links to Github code repositories (:octocat:) are provided where appropriate.

See the following publications for details of how the highly-comparative approach to time-series analysis has developed since our initial publication in 2013:

• We reduced hctsa down to a reduced set of 22 efficiently coded features.
  • 📗 CAnonical Time-series CHaracteristics. Data Mining and Knowledge Discovery 33, 1821 (2019).
  • Code.
• We developed a software package for highly-comparative time-series analysis, hctsa (includes applications to high throughput phenotyping of C. Elegans and Drosophila movement time series).
  • 📗 hctsa: A Computational Framework for Automated Time-Series Phenotyping Using Massive Feature Extraction. Cell Systems 5, 527 (2017).
  • Code (fly) & Code (worm).
• Introduction to using features for time-series analysis
  • 📗 Feature-based time-series analysis. Feature Engineering for Machine Learning and Data Analytics, CRC Press (2018).
  • 📙 Preprint.
• The behavior of thousands of time-series methods on thousands of different time series can be used to organize an interdisciplinary time-series analysis literature
  • 📗 Highly comparative time-series analysis: the empirical structure of time series and their methods. J. Roy. Soc. Interface (2013).

We have used hctsa to:

• Distinguish targeted perturbations to mouse fMRI dynamics
  • 📗 Cortical Excitation:Inhibition Imbalance Causes Abnormal Brain Network Dynamics as Observed in Neurodevelopmental Disorders. Cerebral Cortex (2020).
  • Code.
• Connect structural brain connectivity to fMRI dynamics
  • 📗 Structural connectome topology relates to regional BOLD signal dynamics in the mouse brain. Chaos (2017).
  • 📙 Preprint.
• Distinguish time-series patterns for data-mining applications
  • 📗 Highly comparative feature-based time-series classification. IEEE Trans. Knowl. Data Eng. (2014).
• Classify babies with low blood pH from fetal heart rate time series
  • 📗 Highly comparative fetal heart rate analysis. 34th Ann. Int. Conf. IEEE EMBC (2012).

hctsa has been used to:

• Assess stress-induced changes in astrocyte calcium dynamics.
  • 📗 Paper in Nature Communications (2020).
• Assess the stress controllability of neurons from their activity time series.
  • 📗 Paper in Nature Neuroscience (2020).
• Predicting post cardiac arrest outcomes.
  • 📙 Preprint on arXiv (2020).
• Recognition of hand gestures.
  • 📗 Paper in PLoS ONE (2020).
• Classification of heartbeats measured using single-lead ECG.
  • 📗Paper in IEEE 42nd International Convention on Information and Communication Technology, Electronics and Microelectronics (MIPRO) (2019).
• Non-intrusively monitor load for appliance detection and electrical power saving in buildings.
  • 📗 Paper in Energy and Buildings (2019).
• Detect mild cognitive impairment using single-channel EEG to measure speech-evoked brain responses.
  • 📗 Paper in IEEE Transactions on Neural Systems and Rehabilitation Engineering (2019).
• Assess muscles for clinical rehabilitation.
  • 📗 Paper in 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (2017).
• Evaluate asphalt irregularity from smartphone sensors.
  • 📗 Paper in International Symposium on Intelligent Data Analysis (2018).
• Select features for fetal heart rate analysis using genetic algorithms.
  • 📗 Paper in Physiological Measurement (2014).

(Let me know if I've missed any!)

There are two licenses applied to the core parts of the repository:

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.

A range of external code packages are provided in the Toolboxes directory of the repository, and each have their own associated license (as outlined below).

The following Matlab toolboxes are used by hctsa and are required for full functionality of the software. In the case that some toolboxes are unavailable, the hctsa software can still be used, but only a reduced set of time-series features will be computed.

1. Statistics Toolbox
2. Signal Processing Toolbox
3. Curve Fitting Toolbox
4. System Identification Toolbox
5. Wavelet Toolbox
6. Econometrics Toolbox

The following time-series analysis packages are provided with the software (in the Toolboxes directory), and are used by our main feature extraction algorithms to compute meaningful structural features from time series:

• TISEAN package for nonlinear time-series analysis, version 3.0.1 (GPL license).
• TSTOOL package for nonlinear time-series analysis, version 1.2 (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).
• Cross Recurrence Plot Toolbox (GPL license)
• Zoubin Ghahramani's Hidden Markov Model (HMM) code (MIT license).
• Danny Kaplan's Code for embedding statistics (GPL license).
• Two-dimensional histogram code from Matlab Central (BSD license).
• Various histogram and entropy code by Rudy Moddemeijer (unlicensed).

Other good resources for time-series analysis, e.g., in other programming languages (python and R) are listed here.

This excellent repository allows users to run hctsa software from within python: pyopy.

Some beginner-level python code for analyzing the results of hctsa calculations is here.

A Matlab repository for generating time-series data from diverse model systems is here.

Native python time-series code to extract hundreds of time-series features, with in-built feature filtering, is tsfresh; cf. their paper.

These R packages are by Rob Hyndman. The first, tscompdata, makes available existing collections of time-series data for analysis. The second, tsfeatures, includes implementations of a range of time-series features.

TSFEL, 'Time Series Feature Extraction Library', is a python package with implementations of 60 simple time-series features (with unit tests).

Khiva is an open-source library of efficient algorithms to analyse time series in GPU and CPU.

A python-based nonlinear time-series analysis and complex systems code package, pyunicorn.

TSFuse can extract features from multivariate time series.

Many thanks go to Romesh Abeysuriya for helping with the mySQL database set-up and install scripts, and Santi Villalba for lots of helpful feedback and advice on the software.