tsflex Documentation

Use the following comparison matrix to determine if tsflex is the right tool for your time-series feature extraction needs. tsflex distinguishes itself from competitors like seglearn, tsfresh, TSFEL, and Kats through several key capabilities:

Key Advantages of tsflex

• Unevenly sampled data: Unlike seglearn, tsfresh, and TSFEL, tsflex supports unevenly sampled time series.
• Sequence index flexibility: Supports any sortable sequence index (whereas Kats requires a Datetime index, and others require sorted indices).
• Advanced Windowing: Supports multiple stride-window combinations and defines strided-windows using sequence index ranges rather than just sample-based definitions.
• Data Integrity: Maintains sequence columns, retains output names, preserves input datatypes, and supports categorical data.
• Efficiency & Scale: Supports multiprocessing, chunking multiple time-series, and provides operation execution time logging.
• Complex Mappings: Supports many-to-many function mappings, which is not supported by seglearn, tsfresh, TSFEL, or Kats.

Feature Summary Table

Processing functions in tsflex are highly flexible. They must follow this prototype:

function(*series: pd.Series, **kwargs) -> Union[np.ndarray, pd.Series, pd.DataFrame, List[pd.Series]]

Supported patterns include:

• Many-to-one: Takes multiple series and returns a single array, named pd.Series, or pd.DataFrame with one column.
• One-to-many: Takes one series and returns a List[pd.Series] or a pd.DataFrame with multiple columns.
• Many-to-many: Takes multiple series and returns a List[pd.Series] or a pd.DataFrame with multiple columns.

To ensure the pipeline handles the output correctly, it is recommended to provide named series or dataframes in the return value.

# Many-to-one example
def abs_diff(s1: pd.Series, s2: pd.Series) -> pd.Series:
    return pd.Series(np.abs(s1-s2), name=f"abs_diff_{s1.name}-{s2.name}")

# One-to-many example
def abs_square(s1: pd.Series) -> List[pd.Series]:
    s1_abs = pd.Series(np.abs(s1), name=f"abs_{s1.name}")
    s1_square = pd.Series(np.square(s1), name=f"square_{s1.name}")
    return [s1_abs, s1_square]

tsflex leverages Pandas and expects input to be one or more pd.Series or pd.DataFrame objects. A single time-series (referred to as ts) can be represented in two primary ways:

Wide Data (Flat Data)

This is the most common format and is the primary focus of tsflex.

• Each column represents a different data modality.
• The index represents the shared time.
• Note: Because modalities might not share the exact same timestamps, NaN entries may occur. In such cases, it is often better to treat the data as a list of series (List[pd.Series]) where NaNs are omitted.

Long Data

Consists of three columns:

• A non-index time column (which may contain duplicates).
• A kind column (defining the name of the time-series).
• A value column (the actual data value).

Recommendation: tsflex is built to support wide-dataframes and series-lists. If you are starting with long data, it is recommended to convert it directly to a series-list rather than a wide-dataframe to avoid introducing unwanted NaNs.

import pandas as pd; from typing import Union, List
# The expected input type for tsflex operations
data: Union[pd.Series, pd.DataFrame, List[Union[pd.Series, pd.DataFrame]]]

The feature extraction module relies on three core components:

1. FeatureCollection: Acts as a registry that holds the list of features to be calculated. It manages the execution (often in parallel) of all registered descriptors.
2. FeatureDescriptor: Defines a single feature. It requires:
   • series_name: The name of the input column(s).
   • function: The callable to apply.
   • window: The window size (sample-based integer or time-based string like "2days").
   • stride: The stride (sample-based integer or time-based string like "1hour").
3. FuncWrapper: Used to configure feature functions. It is useful when you need to:
   • Set custom output_names.
   • Define the input_type (e.g., pd.Series or np.array).
   • Pass additional **kwargs to the underlying function.

For simple functions (like np.mean), you can pass the function directly to FeatureDescriptor without a FuncWrapper.

from tsflex.features import FeatureDescriptor, FeatureCollection, FuncWrapper
import numpy as np

# Using simple function
fc = FeatureCollection(feature_descriptors=[
    FeatureDescriptor(np.mean, "series_a", "1hour", "15min")
])

# Using FuncWrapper for configuration
fc.add(FeatureDescriptor(
    function=FuncWrapper(func=np.std, output_names="std_val", input_type=np.array),
    series_name="series_a",
    window="1hour",
    stride="15min"
))

The tsflex toolkit is designed for flexible time series processing and feature extraction with the following characteristics:

• Flexibility: Supports multivariate/multimodal time series and integrates with common packages like scipy.signal, statsmodels.tsa, numpy, scipy.stats, antropy, nolds, seglearn, tsfresh, and tsfel. It supports multiple strides and window sizes.
• Efficiency: Uses view-based operations to ensure low memory peak and fast execution times.
• Intuitive API: Maintains the sequence-index of the data and produces interpretable output column names.
• Minimal Assumptions: Works with any sampling rate and handles asynchronous multivariate data (data with small time-offsets between modalities).
• Advanced Features: Supports FeatureCollection.reduce for faster inference, function execution time logging, serialization of SeriesPipeline and FeatureCollection, and time series chunking.

To extract features using tsflex, follow these three steps:

1. Load data: Prepare your sequence-indexed data (e.g., as a list of DataFrames with time indices).
2. Configure extraction: Create a FeatureCollection containing MultipleFeatureDescriptors. You can specify the functions to apply (e.g., numpy or scipy.stats functions), the target series_names, windows (sizes), and strides.
3. Calculate: Call .calculate() on your FeatureCollection object, passing your data list. Use approve_sparsity=True if dealing with sparse results.

tsflex handles multivariate data with varying sample rates and asynchronous modalities automatically.

import pandas as pd; import numpy as np; import scipy.stats as ss
from tsflex.features import MultipleFeatureDescriptors, FeatureCollection
from tsflex.utils.data import load_empatica_data

# 1. Load sequence-indexed data (in this case a time-index)
df_tmp, df_acc, df_ibi = load_empatica_data(['tmp', 'acc', 'ibi'])

# 2. Construct your feature extraction configuration
fc = FeatureCollection(
    MultipleFeatureDescriptors(
          functions=[np.min, np.mean, np.std, ss.skew, ss.kurtosis],
          series_names=["TMP", "ACC_x", "ACC_y", "IBI"],
          windows=["15min", "30min"],
          strides="15min",
    )
)

# 3. Extract features
fc.calculate(data=[df_tmp, df_acc, df_ibi], approve_sparsity=True)