Features

actimotus.Features dataclass

Processes raw accelerometer data to extract features.

This class provides a pipeline for transforming raw accelerometer time-series data into a set of features. The process includes input validation, sampling frequency detection, resampling, optional auto-calibration, and the computation of metrics (e.g., High-Low ratio, step-related metrics).

The class can process data in a single batch or in overlapping chunks to mimic Sens's infrastructure.

Attributes:

Name	Type	Description
system_frequency	int	The target frequency (in Hz) to which data is resampled. Warning: Defaults to 30 Hz. Changing this is not recommended as downstream pipelines depend on this frequency.
validation	bool	If True, performs schema and format validation on the input.
calibrate	bool	If True, applies gravitational auto-calibration to the raw data.
chunking	bool	If True, processes the data in overlapping chunks.
size	timedelta	The duration of each data chunk. Only used if chunking is True.
overlap	timedelta	The duration of overlap between consecutive chunks. Only used if chunking is True.

Examples:

Basic usage with default settings:

>>> from datetime import timedelta
>>> extractor = Features()
>>> # features = extractor.compute(df)

Configuration for chunked processing:

>>> extractor = Features(
...     chunking=True,
...     size=timedelta(days=1),
...     overlap=timedelta(minutes=15)
... )

compute

compute(
    df: DataFrame, sampling_frequency: float | None = None
) -> pd.DataFrame

Computes extracted features from raw accelerometer data.

This method orchestrates the pipeline: it handles format validation, frequency inference, resampling, and optional calibration. It then dispatches the computation to either a chunked or batch processing backend based on the instance configuration.

Parameters:

Name	Type	Description	Default
df	DataFrame	The input DataFrame containing accelerometer data. Must possess a DatetimeIndex and contain only accelerometer columns (axes X, Y, Z).	required
sampling_frequency	float | None	The sampling frequency of the data in Hertz. If None, it is inferred automatically from the index of df.	None

Returns:

Type	Description
DataFrame	A DataFrame containing the computed features.

Examples:

Basic usage where frequency is inferred:

>>> extractor = Features()
>>> features = extractor.compute(df)

Explicitly providing frequency:

>>> features = extractor.compute(df, sampling_frequency=12.5)