# Structure of the hctsa framework

## Overview

The *hctsa* framework consists of three basic objects containing relevant metadata:

1. *Master Operations* specify pieces of code (Matlab functions) and their inputs to be computed. Taking in a single time series, master operations can generate a large number of outputs as a Matlab structure, each of which can be identified with a single *operation* (or 'feature').
2. *Operations* (or 'features') are a single number summarizing some measure of structure in a time series. In *hctsa*, each operation links to an output from a piece of evaluated code (a *master operation*).
3. *Time series* are univariate and uniformly sampled time-ordered measurements.

These three different objects are summarized below:

|              |        **Master Operation**       |  **Operation** | **Time Series**         |
| :----------: | :-------------------------------: | :------------: | ----------------------- |
| **Summary**: |     Code and inputs to execute    | Single feature | Univariate data         |
| **Example**: | `CO_AutoCorr(x,1:5,'TimeDomain')` |     `AC_1`     | \[1.2, 33.7, -0.1, ...] |

In the example above, a *master operation* specifies the code to run, `CO_AutoCorr(x,1:5,'TimeDomain')`, which outputs the autocorrelation of the input time series (`x`) at lags 1, 2, ..., 5. Each operation (or 'feature') is a single number that draws on this set of outputs, for example, the autocorrelation at lag 1, which is named `AC_1`, for example.

In the *hctsa* framework, master operations, operations, and time series are stored as **tables** that contain all of their associated keywords and metadata (and actual time-series data in the case of time series).

For a given *hctsa* analysis, the user must specify a set of code to evaluate (*master operations*), their associated individual outputs to measure (*operations*), and a set of time series to evaluate the features on (*time series*).

We provide a default library of over 7700 *operations* (derived from approximately 1000 unique *master operations*). This can be customized, and additional pieces of code can also be added to the repository.

### The results of a *hctsa* analysis

Having specified a set of master operations, operations, and time series, the results of computing these functions in the time series data are stored in three matrices:

* **TS\_DataMat** is an *n* x *m* data matrix containing the results of applying *m* operations to the *n* time series.
* **TS\_Quality** is an *n* x *m* matrix containing quality labels for each operation output (coding different outputs such as errors or NaNs). Quality labels are described in the section below.
* **TS\_CalcTime** is an *n* x *m* matrix containing calculation times for each operation output. Note that the calculation time stored is for the corresponding master operation.

### HCTSA .mat files

Each `HCTSA*.mat` file includes the tables described above: for **TimeSeries** (corresponding to the rows of the **TS\_** matrices), **Operations** (corresponding to columns of the **TS\_** matrices), and **MasterOperations**, corresponding to the code evaluated to compute the operations. In addition, the results are stored as above: **TS\_DataMat**, **TS\_Quality**, and **TS\_CalcTime**.

## Quality labels

*Quality labels* are used to indicate when operations take non-real values, or when fatal errors were encountered. Quality labels are stored in the **Quality** column of the **Results** table in the *mySQL* database, and in local Matlab files as the **TS\_Quality** matrix.

When the quality label is nonzero, this indicates that a *special-valued output* occurred. In this case, the output value of the operation is set to zero, as a convention, and the quality label codes the special output value:

| **Quality label** |                                      **Description**                                      |
| :---------------: | :---------------------------------------------------------------------------------------: |
|         0         |                  No problems with calculation. Output was a real number.                  |
|         1         |                               A fatal error was encountered.                              |
|         2         |                              Output of the code was **NaN**.                              |
|         3         |                              Output of the code was **Inf**.                              |
|         4         |                              Output of the code was **-Inf**                              |
|         5         |                         Output had a non-zero imaginary component                         |
|         6         |                               Output was empty (e.g., `[]`)                               |
|         7         | Field specified for this operation did not exist in the master operation output structure |


---

# 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/hctsa-manual/installing-and-using-hctsa/setup/hctsa_structure.md?ask=<question>
```

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.