> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# featurize_time_series

> Summarizes time series data into aggregate metrics. 

Extracts features from time series data for machine learning or analysis.
Supports three feature sets:

* [**catch22**](https://time-series-features.gitbook.io/catch22): 22 time series features, plus optional mean and standard deviation (24 total).
  See details about each feature [here](https://time-series-features.gitbook.io/catch22/information-about-catch22/feature-descriptions/feature-overview-table).
* [**tsfeatures**](https://github.com/Nixtla/tsfeatures): Statistical features including trend, seasonality, autocorrelation, etc.
  See details about each feature [here](https://cran.r-project.org/web/packages/tsfeatures/vignettes/tsfeatures.html).
* **growth**: Simple, average, compound, and linear growth metrics.

The step takes a dataset with time series data in "tall" format (one row per time point)
or "wide" format (time points in columns), and produces a dataset with the calculated features.

## Usage

The following example shows how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      To calculate all "growth" metrics:

      ```stan theme={null}
      featurize_time_series(ds, {
        "id": "product_id",
        "time": "time_added",
        "value": "item_total",
        "sets": ["growth"]
      }) -> (features)
      ```
    </Tab>

    <Tab title="Signature">
      General syntax for using the step in a recipe. Shows the inputs and outputs the step is expected to receive and will produce respectively. For futher details see sections below.

      ```stan theme={null}
      featurize_time_series(ds: dataset, {
          "param": value,
          ...
      }) -> (features: dataset)
      ```
    </Tab>
  </Tabs>
</Accordion>

## Inputs & Outputs

The following are the inputs expected by the step and the outputs it produces. These are generally
columns (`ds.first_name`), datasets (`ds` or `ds[["first_name", "last_name"]]`) or models (referenced
by name e.g. `"churn-clf"`).

<Accordion title="Inputs" icon="right-to-bracket">
  <ParamField path="ds" type="dataset" required>
    A dataset containing time series.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="features" type="dataset" required>
    A dataset containing time series features.
  </ParamField>
</Accordion>

## Configuration

The following parameters can be used to configure the behaviour of the step by including them in
a json object as the last "input" to the step, i.e. `step(..., {"param": "value", ...}) -> (output)`.

<Accordion title="Parameters" defaultOpen="true" icon="sliders">
  <ParamField path="id" type="string (ds.column)" required>
    Column name containing the time series identifier.
  </ParamField>

  <ParamField path="time" type="string (ds.column)" required>
    Column name containing the timestamps.
  </ParamField>

  <ParamField path="value" type="string (ds.column)" required>
    Column name containing the values to featurize.
  </ParamField>

  <ParamField path="sets" type="[string, array[string]]" default="catch22">
    Feature sets to include.
    E.g. "catch22" or "tsfeatures". If no individual features are configured using the `features` pararmeter,
    all features from the selected set will be computed. If multiple sets are selected, all features from
    each set will be computed. If `all` is selected, all features from all sets will be computed.

    Values must be one of the following:

    * `catch22`
    * `tsfeatures`
    * `growth`
    * `all`

    <Accordion title="Array items">
      <ParamField path="Item" type="string">
        Each item in array.

        Values must be one of the following:

        * `catch22`
        * `tsfeatures`
        * `growth`
        * `all`
      </ParamField>
    </Accordion>
  </ParamField>

  <ParamField path="features" type="object">
    Custom features to compute from each feature set.

    <Accordion title="Properties">
      <ParamField path="catch22" type="[array[string], string]">
        Catch22 features to compute.
        [See here](https://time-series-features.gitbook.io/catch22/information-about-catch22/feature-descriptions/feature-overview-table)
        for detailed information about each possible feature.

        <Accordion title="Array items">
          <ParamField path="Item" type="string">
            Each item should be a name of a Catch22 feature.

            Values must be one of the following:

            `mode_5` `mode_10` `acf_timescale` `acf_first_min` `ami2` `trev` `high_fluctuation` `stretch_high` `transition_matrix` `periodicity` `embedding_dist` `ami_timescale` `whiten_timescale` `outlier_timing_pos` `outlier_timing_neg` `centroid_freq` `stretch_decreasing` `entropy_pairs` `rs_range` `dfa` `low_freq_power` `forecast_error` `mean` `SD`
          </ParamField>
        </Accordion>
      </ParamField>

      <ParamField path="tsfeatures" type="[array[string], string]">
        TSFeatures features to compute.
        [See here](https://cran.r-project.org/web/packages/tsfeatures/vignettes/tsfeatures.html)
        for detailed information about each possible feature.

        <Accordion title="Array items">
          <ParamField path="Item" type="string">
            Each item should be the name of a TSFeature feature.

            Values must be one of the following:

            `acf_features` `arch_stat` `crossing_points` `entropy` `flat_spots` `heterogeneity` `holt_parameters` `lumpiness` `nonlinearity` `pacf_features` `stl_features` `stability` `hw_parameters` `unitroot_kpss` `unitroot_pp` `series_length` `hurst`
          </ParamField>
        </Accordion>
      </ParamField>

      <ParamField path="growth" type="[array[string], string]">
        Growth features to compute.
        The different growth features are calculated as follows, where $x_f$ is the final value, $x_0$
        is the initial value, and $n$ is the number of periods in a time series.

        `"simple"`

        Factional change between first and last value. Maintains direction of growth by dividing the change
        by the **absolute** value of the initial value:

        $g = \frac{x_f - x_0}{|x_0|}$

        `"average"`

        The average fraction of change between consecutive values. Also maintains direction,
        unlike e.g. pandas pct\_change function:

        $g = \frac{1}{n} \sum_{i=1}^{n} \frac{x_i - x_{i-1}}{|x_{i-1}|}$

        `"compound"`

        Analogous to [CAGR](https://www.investopedia.com/terms/c/cagr.asp) (Compound Annual Growth Rate).
        The average growth rate over the entire period, assuming the growth is compounded:

        $g = \left( \frac{x_f}{x_0} \right)^{\frac{1}{n}} - 1$

        `"linear"`

        Fits a linear regression to the time series and returns the slope of the line.

        <Accordion title="Array items">
          <ParamField path="Item" type="string">
            Each item in array.

            Values must be one of the following:

            * `simple`
            * `average`
            * `compound`
            * `linear`
          </ParamField>
        </Accordion>
      </ParamField>
    </Accordion>

    <Accordion title="Examples">
      * E.g. deriving two features from catch22 and growth sets each:

      ```json theme={null}
      {
      "catch22": ["mode_5", "acf_timescale"],
      "growth": ["simple", "linear"],
      }
      ```
    </Accordion>
  </ParamField>

  <ParamField path="freq" type="[null, string, integer]">
    Frequency to use by features in the TSFeatures set.
    The number of observations in a single cycle. Used by certain features (for now only in the tsfeatures set),
    that are based on seasonality. When a string (character) is provided, this is interpreted as the natural frequency
    of the time series and will be translated to the number of observations per cycle using the following mapping:

    * 'H': 24 (hourly)
    * 'D': 1  (daily)
    * 'M': 12 (monthly)
    * 'Q': 4 (quarterly)
    * 'W': 1 (weekly)
    * 'Y': 1 (yearly)

    E.g. if the natural frequency of the time series is monthly ('M'), will
    analyze seasonality with a period of 12 observations (months in a year). If a number is provided,
    this will be interpreted directly as the number of observations per cycle. If `null`, attempts to
    infer the frequency automatically.

    Also see [this post](https://robjhyndman.com/hyndsight/seasonal-periods/) by the author of
    the original `tsfeatures` package for more details on seasonality and the frequency parameter.
  </ParamField>

  <ParamField path="unit" type="string" default="D">
    Temporal unit to use.
    Only required for converting the time column to timestamps when it is numeric.
    Y=years, M=months, W=weeks, D=days, h=hours, m=minutes, s=seconds,
    ms=milliseconds, us=microseconds, ns=nanoseconds.

    Values must be one of the following:

    `Y` `M` `W` `D` `h` `m` `s` `ms` `us` `ns`
  </ParamField>

  <ParamField path="output" type="string" default="wide">
    Output format.
    The format of the output dataset. The following options are supported:

    * "wide": One row per time series with features as multivalues (list) columns
    * "tall": Features joined to the original data, preserving all rows.

    Values must be one of the following:

    * `wide`
    * `tall`
  </ParamField>

  <ParamField path="n_jobs" type="integer" default="-1">
    Number of parallel jobs.
    If -1, all processors are used. If 1, no parallel computing code is used at all,
    which is useful for debugging. Using multiple processes with a large dataset may
    cause memory issues.

    Values must be in the following range:

    ```javascript theme={null}
    -1 ≤ n_jobs < inf
    ```
  </ParamField>
</Accordion>