API Reference

`tsfx`

`DynamicGroupBySettings(time_col, every, period, offset, datetime_format=None)`

Settings for dynamic (time-windowed) group-by extraction.

Parameters:

Name	Type	Description	Default
`time_col`	`str`	Name of the datetime column used for windowing.	required
`every`	`str`	Window stride (e.g. \"1d\", \"3y\").	required
`period`	`str`	Window length (e.g. \"3y\").	required
`offset`	`str`	Offset for the windowing grid (e.g. \"0y\").	required
`datetime_format`	`str \| None`	Format string used to parse time column values when needed.	`None`

`ExtractionSettings(grouping_cols, value_cols, feature_setting, config_path=None, dynamic_settings=None)`

Configuration for a feature extraction run.

Parameters:

Name	Type	Description	Default
`grouping_cols`	`Sequence[str]`	Column names used to group rows into separate time series (e.g. an id).	required
`value_cols`	`Sequence[str]`	Column names containing the numeric values to extract features from.	required
`feature_setting`	`FeatureSetting`	One of the `FeatureSetting` presets controlling which feature calculators run.	required
`config_path`	`str \| None`	Optional path to `.tsfx-config.toml` config file.	`None`
`dynamic_settings`	`DynamicGroupBySettings \| None`	Optional `DynamicGroupBySettings` for time-windowed extraction.	`None`

`FeatureSetting`

Bases: Enum

Preset groups of feature extractors.

Minimal: smallest, fastest set of features.
Efficient: balanced set of commonly useful features (default choice).
Comprehensive: largest set of features for maximum coverage.

`extract_features(lf, settings, streaming=False)`

Extract features from a Polars LazyFrame.

Short wrapper around tsfx.extract_features that runs feature extraction on a Polars LazyFrame and returns a flattened pl.DataFrame. Any Struct columns produced are unnested to top-level columns.

Parameters:

Name	Type	Description	Default
`lf`	`LazyFrame`	Input lazy frame.	required
`settings`	`ExtractionSettings`	Extraction configuration.	required
`streaming`	`bool`	Enable streaming mode.	`False`

Returns:

Type	Description
`DataFrame`	Flattened DataFrame with extracted features.

Example

import polars as pl
from tsfx import ExtractionSettings, FeatureSetting, extract_features

df = pl.DataFrame(
    {
        "id": ["a", "a", "a", "b", "b", "b", "c", "c", "c"],
        "val": [1.0, 2.0, 3.0, 1.0, 2.0, 3.0, 1.0, 2.0, 3.0],
        "value": [4.0, 5.0, 6.0, 6.0, 5.0, 4.0, 4.0, 5.0, 6.0],
    },
).lazy()

settings = ExtractionSettings(
    grouping_cols=["id"],
    feature_setting=FeatureSetting.Efficient,
    value_cols=["val", "value"],
)

gdf = extract_features(df, settings)