> For the complete documentation index, see [llms.txt](https://time-series-features.gitbook.io/catch22/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://time-series-features.gitbook.io/catch22/language-specific-docs/matlab.md). # MATLAB A detailed usage guide for installing and using catch22 in MATLAB. ## MATLAB Usage Guide Select a card below to access MATLAB-specific usage information.
Installationinstall_light.png#installation
Getting startedgetting_started_light.png#getting-started-basic-usage
Advanced usageadv_usage_light.png#advanced-usage
Frequently Asked QuestionsFAQ_light.png#faq
API ReferenceAPI_light.pngMATLAB API
*** *** ## Installation *** 1. To get started with installing *catch22* in MATLAB, clone the repository to a location of your choice using the following command in `Bash/CMD`: ```bash git clone https://github.com/DynamicsAndNeuralSystems/catch22.git ``` 2. In MATLAB, navigate to the `wrap_Matlab` directory in the cloned repo and call `mexAll` from the MATLAB command window. This compiles the *catch22* C code into a single MEX function, `catch22_mex`, which needs a C compiler set up for MATLAB (see `mex -setup C`). Ensure you include the folder in your MATLAB path to use the package: ```matlab cd('catch22/wrap_Matlab') addpath(pwd) % add folder in MATLAB path mexAll ``` 3. Optionally, check the installation by running `testing`, which compares `catch22_all` with the stored outputs of the C code for the time series in `catch22/testData/basic`: ```matlab testing ``` *** ## 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 *catch22* MATLAB takes one univariate time series at a time, passed as a **vector** (row or column). Consider the following example for a single time series of length 10 (i.e., 10 points): ```matlab >> data = rand(10,1) % example of the expected format for your time series data data = 0.5672 0.9982 0.1319 ... 0.0813 0.6592 ``` ### Computing *catch22* features All features are bundled into a function called `catch22_all`. By default, the extended *catch24* feature set will be computed unless the second argument, `doCatch24`, is set to `false`: * `true` (default) -> return the *catch24* feature set (*catch22* + mean + std. dev.). * `false` -> return the standard *catch22* feature set. ```matlab % compute catch24 features [vals, names] = catch22_all(data); % for the catch22 feature set [vals, names] = catch22_all(data, false); ``` ### Expected output A **column vector** of feature values and a **cell** of feature names (`24x1` if *catch24*, `22x1` if *catch22*) will be returned by MATLAB. The order in which the feature outputs are returned corresponds to the order in which feature names are returned, e.g., the feature output in `vals(1)` corresponds to the feature name `names{1}`: ```matlab % Print feature name and value for i = 1:numel(names) fprintf('%s: %f\n', names{i}, vals(i)); end ``` The features are returned in the order of the [feature overview table](/catch22/information-about-catch22/feature-descriptions/feature-overview-table.md), with the names of *catch22* v1.0. {% hint style="info" %} **catch22 v1.0** changed the values of most features (to match *hctsa* v3.0.0 exactly) and renamed several of them, so outputs are not comparable with those of v0.x. See the [feature descriptions](/catch22/information-about-catch22/feature-descriptions.md) for what changed. {% endhint %} 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.* {% 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. In MATLAB, *catch24* is computed by default; you can also request it explicitly by passing `true` as the second argument of `catch22_all`: ```matlab tsData = rand(100,1); % create some time series [vals, names] = catch22_all(tsData, true); ``` {% endtab %} {% endtabs %} ### 2. Computing Individual Features {% tabs %} {% tab title="Computing Individual Features" %} From v1.0, the MATLAB wrapper no longer has a separate function for each feature: compute them all with `catch22_all` and select the one you need by its name (as in the [feature overview table](/catch22/information-about-catch22/feature-descriptions/feature-overview-table.md)). For example, to get only `DN_HistogramMode_5`: ```matlab tsData = rand(1000,1); % create length 1000 time series [vals, names] = catch22_all(tsData, false); f = vals(strcmp(names, 'DN_HistogramMode_5')); fprintf('DN_HistogramMode_5 value: %f\n', f) ``` {% 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" %} In MATLAB, short names can be included in the output when calling `catch22_all` by specifying an additional output: ```matlab tsData = rand(1000, 1); % your time series data [featureVals, longNames, shortNames] = catch22_all(tsData, false); % print the short name and corresponding feature value for i = 1:numel(featureVals) fprintf('%s: %f\n', shortNames{i}, featureVals(i)); end ``` Now, in addition to the cell of long names and feature values, we also obtain an additional cell (`22x1` for *catch22,* `24x1` for *catch24*) of short feature names. To get the names without computing any features, use `GetAllFeatureNames`, which also returns each feature's name before v1.0 and the *hctsa* code that reproduces it: ```matlab [longNames, shortNames, legacyNames, hctsaCalls] = GetAllFeatureNames(false); ``` {% endtab %} {% endtabs %} ### 4. Masking Some features cannot be estimated for some time series, e.g., any feature of a constant time series, or `dfa` for a time series shorter than 79 samples. {% tabs %} {% tab title="Masking" %} By default, such features are [masked](/catch22/information-about-catch22/feature-descriptions/feature-overview-table.md#masking): set to a fixed value at the appropriate end of the feature's range, so that real numbers are always returned. The fourth output of `catch22_all` says which values were masked, and setting the third argument, `maskNaNs`, to `false` gives `NaN` instead: ```matlab tsData = rand(50,1); % too short for dfa [vals, names, shortNames, isMasked] = catch22_all(tsData, false); % dfa is masked (to 1) shortNames(isMasked) vals = catch22_all(tsData, false, false); % dfa is NaN ``` A time series containing `NaN` or `Inf` gives `NaN` for every feature (it is never masked). {% endtab %} {% endtabs %} *** ## FAQ Click one of the expandable tabs below to explore commonly asked questions about *catch22* in MATLAB:
How can I submit a bug report for catch22? If you would like to submit a bug report, you can access our Bug Tracker [here](https://github.com/DynamicsAndNeuralSystems/catch22/issues). For guidelines on submitting an ideal bug report, see our page on [contributing to *catch22*](/catch22/information-about-catch22/contributing-to-catch22.md)*.*
How do I reproduce a catch22 feature in hctsa? From v1.0, each *catch22* feature exactly reproduces a call to *hctsa* v3.0.0 code, applied to the *z*-scored time series, `x_z` (or, for the mean and standard deviation, to the raw time series, `x`). These calls are returned as the fourth output of `GetAllFeatureNames`, and listed in the [feature overview table](https://time-series-features.gitbook.io/catch22/language-specific-docs/pages/Xul45GNpdBAJ3I0nN7Kt#feature-names-before-v1.0-and-hctsa-code).
*** *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://time-series-features.gitbook.io/catch22/language-specific-docs/matlab.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.