# Julia
## Julia Usage Guide
Select a card below to access Julia-specific usage information.
***
***
## Installation
***
Julia users can install the latest version of [*catch22*](https://docs.juliahub.com/General/Catch22/stable/) using the following:
```julia
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*](https://www.github.com/chlubba/catch22):
```julia
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:
```julia
𝐟 = 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:
```julia
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.*
{% tabs %}
{% tab title="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:
```julia
# your time series data
x = Catch22.testData[:testSinusoid]
features24 = catch24(x)
# alternatively, if you would like to use short names...
f24 = c24(x)
```
{% endtab %}
{% endtabs %}
### 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.
{% tabs %}
{% tab title="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](/catch22/information-about-catch22/feature-descriptions/feature-overview-table.md)) 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`](/catch22/information-about-catch22/feature-descriptions/distribution-shape.md) 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`](/catch22/information-about-catch22/feature-descriptions/distribution-shape.md) 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_5`](/catch22/information-about-catch22/feature-descriptions/distribution-shape.md)can be evaluated with:
```julia
f = DN_HistogramMode_5(𝐱)
```
{% endtab %}
{% endtabs %}
### 3. Short Names
For each feature, we also include a unique 'short name' for easier reference (as outlined in the [feature overview table](/catch22/information-about-catch22/feature-descriptions/feature-overview-table.md)).
{% tabs %}
{% tab title="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:
```python
: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:
```julia
forecast_error_val = c22[:forecast_error](x)
```
{% endtab %}
{% endtabs %}
***
***
## 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](https://github.com/brendanjohnharris/Catch22.jl?tab=readme-ov-file#single-threaded-performance) for plots which compare single-threaded and multithreaded performance in Julia.
How is catch22 implemented in Julia?
The [*catch22*](https://www.github.com/chlubba/catch22) repository provides these 22 features, originally coded in Matlab as part of the [*hctsa*](https://github.com/benfulcher/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](https://github.com/JuliaBinaryWrappers/catch22_jll.jl) and compiled by the fantastic [BinaryBuilder](https://github.com/JuliaPackaging/BinaryBuilder.jl) 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](https://github.com/brendanjohnharris/Catch22.jl/issues). For guidelines on submitting an ideal bug report, see our page on [contributing to *catch22*](/catch22/information-about-catch22/contributing-to-catch22.md)*.*
***
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://time-series-features.gitbook.io/catch22/language-specific-docs/julia.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.