Python
A detailed usage guide for installing and using catch22 in Python.
Last updated
A detailed usage guide for installing and using catch22 in Python.
Last updated
Select a card below to access Python-specific usage information.
Python users can install pycatch22 via using the following command:
Additionally, pycatch22 can also be installed using the following alternative installation options. Click the expandable drop-down tabs to explore these options:
Here we outline how you can jump straight into computing catch22 features on your time series data with a basic usage example.
In pycatch22, time series can be provided as arrays in the form of tuples or lists , or as numpy arrays:
All features are bundled in the method catch22_all which can simply be called on your time series data as shown below:
The results of your calculation will be stored in a dictionary with the keys: names and values:
values: the feature outputs returned as a list of float64's.
Note that the ordering of the feature names is the same as that in which the outputs are given i.e., the first feature in names has the output corresponding to the first (zeroth) index in values.
Continuing our example from above, we can view the features and their computed values with the following:
Which gives the following example output:
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.
Ready to explore some of the additional functionality of pycatch22?
If the location and spread of the raw time series distribution may be important for your application, you can enable 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, you can pass an additional parameter to the catch22_all method, telling it to compute the catch24 feature set as follows:
If you do not wish to compute the full catch22 feature set on your time series, you can alternatively compute each feature (including mean and std. deviation) individually.
As example, let's compute the feature trev for a single univariate time series:
In pycatch22 short names can be included in the output when calling catch22_all() by setting short_names = True:
The returned dictionary, results, now has three keys: names, short_names and values. As before, names is a list of the original long feature names (as strings), short_names is a list of short names (as strings) and values is a list of feature values.
Continuing from the basic usage example, let's try printing the feature outputs along with their corresponding short names:
Here is the output from our example. A lot more readable!
When working with large time series datasets (containing many univariate time series instances), computing features can often become a significant computational bottleneck. This is where multi-threading comes into play, offering a powerful solution to accelerate feature computation through parallelisation.
Let's start by importing all of the libraries we will need:
and then create a large time series dataset consisting of 50 000 univariate time series instances, each of length 1000:
Next, we will need to define an iterable function which takes in a single time series, applies catch22, and then returns the feature values:
We need to see how many cpu cores are available for multithreading. You can check by running os.cpu_count(). The value returned (num of cpu cores available) will differ depending on your hardware and setup:
Now we can parallelise our function using the following:
You should notice that the time to compute all catch22 features on the entire dataset of 50 000 time series is much faster than sequentially looping over each!
For example, on 8 cores (Mac M1), it takes ~27 seconds to compute features on the entire dataset. Without multi-threading this would usually take ~2.5 minutes. That's almost a 5.5x speedup!
Click one of the expandable tabs below to explore commonly asked questions about pycatch22:
First, clone the repository to your local machine using:
names: the feature names, as listed in the , returned as a list of strings.
In pycatch22 each feature function can be accessed individually and takes arrays as tuples or lists (not numpyarrays) as input. To call a feature function, make sure to use its corresponding long name (as in the ), e.g., using for computing .
For each feature, we also include a unique 'short name' for easier reference (as outlined in the ).
If you would like to submit a bug report, you can access our Bug Tracker . For guidelines on submitting an ideal bug report, see our page on .
We have conducted thorough across Python versions 3.8, 3.9, 3.10, and 3.11 to verify and guarantee compatibility. These tests have been carried out on various operating systems, including Windows, macOS, and Linux, to ensure consistent performance and reliability across different platforms.
We have a detailed installation guide , including instructions for installing using pip, as well as alternative installation options including conda and manual (local) install.
See above in our advanced usage guide for how you can compute catch22 features on large datasets using .
, a comprehensive Python library for time series machine learning, leverages catch22's capabilities within a broader ecosystem of time series analysis tools for classification. For users looking to incorporate catch22's feature extraction into their sktime pipelines, they can do so by calling the which implements a random forest classifier using catch22 features calculated on time series data.
Tutorials for using catch22 within the sktime framework are also available .
