C-compiled

A detailed usage guide for using compiled catch22 executables.

C-compiled Usage Guide

Select a card below to access C-compiled-specific usage information.

Installation

Getting started

Advanced usage

Frequently Asked Questions

---

---

Installation

---

Note: In order to compile the C source files, you will need to ensure you have GCC installed on your system. MacOS users can follow these instructions to install GCC using homebrew. In most Linux distributions, GCC comes pre-installed, however if it is unavailable, it can be easily installed using sudo apt-get install gcc. Windows users can follow these instructions to install the MSYS2 platform which includes support for GCC.

1. To get started with using catch22, clone the repository to a location of your choice using the following command in Bash/CMD:

git clone https://github.com/DynamicsAndNeuralSystems/catch22.git

1. Navigate to the folder called c in the cloned repository (catch22/C) and compile the C source files into a single executable named run_features. Choose your operating system from one of the tabs below to access OS-specific instructions:

Windows

1. After having installed on your system, launch the UCRT64 environment by running UCRT64.exe (not MSYS2.exe). You will see a terminal that looks like this:

emulated terminal

1. Install the mingw-w64 GCC to start compiling catch22. You can do this by running the following command:

pacman -S mingw-w64-ucrt-x86_64-gcc

1. Now you can call gcc as you would from the MacOS or Linux platforms to compile the catch22 source files. First navigate to the folder containing the C source files from within the emulated environment:

$ cd /c/{your_fpath_in_cdrive}/catch22/c

Next, compile the source code using the following gcc command:

gcc -o run_features main.c CO_AutoCorr.c DN_HistogramMode_10.c DN_HistogramMode_5.c DN_OutlierInclude.c FC_LocalSimple.c IN_AutoMutualInfoStats.c MD_hrv.c PD_PeriodicityWang.c SB_BinaryStats.c SB_CoarseGrain.c SB_MotifThree.c SB_TransitionMatrix.c SC_FluctAnal.c SP_Summaries.c DN_Mean.c DN_Spread_Std.c butterworth.c fft.c helper_functions.c histcounts.c splinefit.c stats.c -lm

If the source code compiled successfully, you should now see an executable called run_features.exe in your folder. If you wish, you can copy this executable to a new folder to run catch22 with your time series data. See our usage guide for more information.

MacOS/Linux

Compiled the source code using GCC by running the following command in bash:

gcc -o run_features *.c

---

Getting Started: Basic Usage

Here we outline how you can jump straight into computing catch22 features on your time series data with a basic usage example.

Expected Input

The compiled run_features program only takes one time series at a time. Time series data are expected to be in the .txt or .csv file format. Each file contains one univariate time series and each line in the file corresponds to a single time series observation i.e., 12 lines for a time series of length 12:

time_series_example.txt

-0.89094
-0.86099
-0.82438
-0.78214
-0.73573
-0.68691
-0.63754
-0.58937
-0.54342
-0.50044
-0.46082
-0.42469

Running the executable

To use catch22, launch a terminal and run:

$ ./run_features <infile.txt> [outfile]

Note, this will be an executable (e.g., run_features.exe) for Windows users. Here, specifying <outfile> is optional. If you do not wish to supply a file for saving the outputs, catch22 will print to stdout by default.

As an example, here we run catch22 on a simple sinusoidal time series with 5000 observations (i.e., length T = 5000), provided as a .txt or .csv file:

$ ./run_features testSinusoid.txt testSinusoidOutput.txt
# enter either 0 for catch22 or 1 for catch24

Here we tell catch22 to store the results of the calculation in a.txt file called "testSinusoidOutput.txt". Note that we can also save the results as a comma separated values (.csv) file.

Expected output

Each line of the output (either saved or printed to the terminal) corresponds to one feature; the three comma-separated entries per line correspond to feature value, feature name and execution time in milliseconds in the following format:

feature value, feature name, execution time (ms)

For example:

0.29910714285714, CO_Embed2_Basic_tau.incircle_1, 0.341000
0.57589285714286, CO_Embed2_Basic_tau.incircle_2, 0.296000
...

And that's it! You now have all the knowledge you need to apply catch22 to your time series data. To access some of the additional functionality of catch22, keep reading for advanced usage tips and examples.

---

---

Advanced Usage

Ready to explore some of the additional functionality of catch22?

1. Catch24

If the location and spread of the raw time series distribution may be important for your application, you can enable catch24.

Catch24

Catch24 is an extension of the original catch22 feature set to include mean and standard deviation, yielding a total of 24 time series features. To access catch24, when using the run_features executable, the user will be prompted to enter either 0 (catch22) or 1 (catch24).

2. Multiple Time Series

A typical analysis may involve more than one time series (e.g., classification). To run catch22 on multiple univariate time series, do the following:

Multiple Time Series

1. For multiple time series, put them - one file for each - into a folder timeSeries. Ensure that the script runAllTs.sh is in the same location as thetimeSeries folder.

📂 timeSeries/
├─ 📜ts_data1.txt <- contains one univariate time series
├─ 📜ts_data2.txt
├─ 📜ts_data3.txt
📜 runAllTs.sh

1. Change the permissions of runAllTS.sh to executable by calling chmod 755 runAllTS.sh:

$ chmod 755 runAllTS.sh

1. Call the executable using the following command to compute catch22 features on each of the time series:

$ ./runAllTS.sh

The output (one output file per input file) will be written to a folder featureOutput:

📂 timeSeries/
├─ 📜ts_data1.txt
├─ 📜ts_data2.txt
├─ 📜ts_data3.txt
📂 featureOutput/ <- new folder containing results
├─ 📜ts_data1output.txt <- contains 22 lines, each corresp. to a feature output
├─ 📜ts_data2output.txt
├─ 📜ts_data3output.txt
📜 runAllTs.sh

---

---

FAQ

---

Click one of the expandable tabs below to explore commonly asked questions about pycatch22:

How can I submit a bug report for pycatch22?

If you would like to submit a bug report, you can access our Bug Tracker here. For guidelines on submitting an ideal bug report, see our page on contributing to catch22.

---