Julia

A detailed usage guide for installing and using catch22 in Julia (Catch22.jl).

Julia Usage Guide

Select a card below to access Julia-specific usage information.

Installation

Getting started

Advanced usage

Frequently Asked Questions

API Reference

---

---

Installation

---

Julia users can install the latest version of catch22 using the following:

using Pkg
Pkg.add("Catch22")

---

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 input time series can be provided as a Vector{Float64} or Array{Float64, 2}. If an array is provided, the time series must occupy its columns. For example, this package contains a few test time series from catch22:

using Catch22
𝐱 = Catch22.testdata[:testSinusoid] # a Vector{Float64}
X = randn(1000, 10) # an Array{Float64, 2} with 10 time series samples

Computing catch22 features

Once your time series data is in the correct form, all catch22 features can then be evaluated with:

𝐟 = catch22(𝐱) # for a time series vector (1 instance)
F = catch22(X) # for a time series matrix (many instances)

Expected output

If an array is provided (multiple univaraite time series), containing one time series in each of N columns:

• A 22 x N FeatureArrray of feature values will be returned (a subtype of AbstractDimArray).

If a vector is provided (a single time series) :

• A vector of feature values will be returned as a FeatureVector, a one dimensional FeatureArray.

Example FeatureVector output

Let's have a look at the typical output for a FeatureVector:

FeatureVector output
22-element FeatureArray{Float64,1}  with dimensions:
  Dim{:feature} Categorical{Symbol} Symbol[DN_HistogramMode_5, DN_HistogramMode_10, …, SB_TransitionMatrix_3ac_sumdiagcov, PD_PeriodicityWang_th0_01] Unordered
 :DN_HistogramMode_5                             1.27293
 :DN_HistogramMode_10                           -1.12759
 :CO_Embed2_Dist_tau_d_expfit_meandiff           1.6463
 :CO_f1ecac                                      119.741
 :CO_FirstMin_ac                                 2.0
 :CO_HistogramAMI_even_2_5                       1.0795
 :CO_trev_1_num                                 -0.000175093
 :DN_OutlierInclude_p_001_mdrmd                 -0.137772
 :DN_OutlierInclude_n_001_mdrmd                  0.136873
 :FC_LocalSimple_mean1_tauresrat                 0.00625
 :FC_LocalSimple_mean3_stderr                    0.140511
 :IN_AutoMutualInfoStats_40_gaussian_fmmi        1.0
 :MD_hrv_classic_pnn40                           0.822
 :SB_BinaryStats_diff_longstretch0               6.0
 :SB_BinaryStats_mean_longstretch1               301.0
 :SB_MotifThree_quantile_hh                      1.38226
 :SC_FluctAnal_2_rsrangefit_50_1_logi_prop_r1    0.77551
 :SC_FluctAnal_2_dfa_50_1_2_logi_prop_r1         0.693878
 :SP_Summaries_welch_rect_area_5_1               0.988172
 :SP_Summaries_welch_rect_centroid               0.00997088
 :SB_TransitionMatrix_3ac_sumdiagcov             0.010059
 :PD_PeriodicityWang_th0_01                      628.0

Note that all features are returned as Float64's, even though some may be constrained to integers.

You can access the output for each SPI individually using the corresponding symbol i.e., :DN_HistogramMode_5 for the DN_HistogramMode_5 feature.

---

---

Advanced Usage

Ready to explore some of the additional functionality of Catch22.jl?

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 you can use the catch24 FeatureSet:

​# your time series data 
x = Catch22.testData[:testSinusoid]
​
features24 = catch24(x)
​
# alternatively, if you would like to use short names...
f24 = c24(x)

2. Computing Individual Features

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.

Computing Individual Features

Each feature can be evaluated for a time series array or vector with the catch22 FeatureSet. You can do this by indexing the catch22 FeatureSet using the feature names (as in the feature overview table) as a symbol. In Julia, you can obtain a list of features (as symbols) by using getnames(catch22).

As an example, let's compute only the feature DN_HistogramMode_5 using its symbol. Here we will compute the feature for both a single univariate time series (as a vector) and an array with 10 univariate time series:

using Catch22
​
# your time series
x = catch22.testdata[:testSinusoid] # a Vector{Float64}
X = randn(1000, 10) # an Array{Float64, 2} with 10 time series
​
# evaluate feature using the corresponding symbol :feature_name
f = catch22[:DN_HistogramMode_5](x) # returns a scalar Float64
F = catch22[:DN_HistogramMode_5](X) # returns a 1x10 Matrix{Float64}

For our time series vector, we obtain a scalar Float64 corresponding to the value of DN_HistogramMode_5 for our single time series. Similarly, for an array of multiple time series, we obtain a matrix of Float64 values, corresponding to the value of the feature for each time series in the original array.

Alternatively, functions that calculate each feature individually are exported. For example, DN_HistogramMode_5can be evaluated with:

f = DN_HistogramMode_5(𝐱)

3. Short Names

For each feature, we also include a unique 'short name' for easier reference (as outlined in the feature overview table).

Short Names

1. Returning short names as outputs

In Julia, short names can be returned in place of the corresponding long feature names by calling c22 (instead of catch22) on your time series data. Since c22 is also a FeatureSet type, it accepts the same inputs as catch22:

using Catch22
𝐱 = Catch22.testdata[:testSinusoid]
f = c22(x) # 22 element feature array

Here is an example of (part of) the FeatureArray returned:

:mode_5                 1.27293
:mode_10               -1.12759
:embedding_dist         1.6463
:acf_timescale          119.741

You can also access the individual results using their associated short name symbol e.g., :mode5. To obtain the full list of short names, you can use getnames(c22).

2.Computing individual features by their short name

Using the c22 FeatureSet, you can index individual time series features by their short name (as symbols). For example, to compute the feature FC_LocalSimple_mean3_stderr with short name forecast_error, you can do the following:

forecast_error_val = c22[:forecast_error](x)

---

---

FAQ

---

Click one of the expandable tabs below to explore commonly asked questions about Catch22 in Julia:

Does catch22.jl make use of Julia's native multithreading?

Yes, by default, catch22.jl uses Julia's powerful native multithreading to parallelise over

To get an idea of how the performance of catch22 scales as a function of time series length (number of samples), both in terms of computation time (for the full feature set) and memory usage, see here for plots which compare single-threaded and multithreaded performance in Julia.

How is catch22 implemented in Julia?

The catch22 repository provides these 22 features, originally coded in Matlab as part of the hctsa toolbox, as C functions (in addition to Matlab and Python wrappers). The catch22.jl package simply uses Julia's ccall to wrap these C functions from a shared library that is accessed through catch22_jll and compiled by the fantastic BinaryBuilder package.

How can I submit a bug report for Catch22.jl?

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.

---