Exposures

actimotus.Exposures dataclass

Aggregates activity data into summary exposure metrics.

This class takes the 1-second activity epochs (produced by Activities) and calculates aggregate exposure metrics over a specified time window. Metrics include total time spent in specific postures (e.g., Sedentary, MVPA), and frequency of transitions (e.g., sit-to-stand) and also data quality check indicating invalid data.

It supports generating results as raw DataFrame or visual plot.

Attributes:

Name	Type	Description
window	str | timedelta	The time window for aggregation. Accepts a timedelta object or a pandas-style string offset (e.g., '1d' for daily totals, '1h' for hourly). Defaults to daily aggregation.
fused	bool	If True, granular activity categories are merged into broader semantic groups before calculation. This simplifies the output by combining physiologically similar states. Fusion Mappings: Sedentary: Combines lie, sit, and kneel. Standing: Combines stand, squat, and shuffle. Walking: Combines walk, fast-walk, and stairs climbing.

Examples:

Standard daily exposures with full granular categories:

>>> exposures = Exposures()
>>> # results = exposures.compute(activities)

Weekly exposures with fused categories (grouping all walking types):

>>> exposures = Exposures(window='7d', fused=True)

compute

compute(df: DataFrame) -> pd.DataFrame

Calculates exposure metrics and validity flags for the given activity data.

This method aggregates the input time-series based on the configured window size (e.g., daily). It computes durations for each activity category and determines if the monitoring period is considered "valid."

Validity Criteria: A window is marked as valid (True) if the subject performed at least 10 minutes of active movement (Stairs + Walk) within that period.

Parameters:

Name	Type	Description	Default
df	DataFrame	A DataFrame containing 1-second activity epochs. It must be indexed by a DatetimeIndex and contain an 'activity' column.	required

Returns:

Type	Description
DataFrame	A DataFrame indexed by the time window (e.g., each day), containing:
DataFrame	valid: Boolean flag indicating if the window met the activity threshold.
DataFrame	[Activity Names]: Columns for each activity type (e.g., 'sit', 'stand', 'walk'), containing the total duration (timedelta) spent in that state.
DataFrame	[Fused Categories]: If fused=True, contains broader categories like 'sedentary' instead of granular ones.

Examples:

>>> exposures = Exposures(window='1d', fused=False)
>>> results = exposures.compute(activity_epochs_df)

plot

plot(
    df: DataFrame, language: dict[str, Any] | None = None
) -> alt.Chart

Generates an interactive Gantt-style chart of the activity timeline.

This method visualizes the 1-second activity epochs. If fused is enabled on this instance, the plot will automatically group similar activities (e.g., 'walk', 'stairs' -> 'Walking') and use the simplified color scheme.

Parameters:

Name	Type	Description	Default
df	DataFrame	The input DataFrame containing 1-second activity epochs. Must contain an 'activity' column.	required
language	dict[str, Any] | None	A configuration dictionary to customize chart labels and colors (e.g., for localization). If None, defaults to the standard English configuration.	None

Returns:

Type	Description
Chart	An Altair Chart object representing the activity timeline. To display it in a notebook, simply let the object return or call .display().

Examples:

Basic usage with default English labels:

>>> chart = exposures.plot(df)
>>> chart.save('timeline.html')

context staticmethod

context(
    df: DataFrame,
    intervals: DataFrame,
    context: str,
    activities: list[str] | None = None,
) -> pd.Series