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	The time window for aggregation, as a pandas offset string. Use uppercase calendar aliases for day/week windows ('1D' for daily totals, '7D' for weekly); sub-day windows like '1h' also work. Defaults to daily ('1D'). Day/week windows bucket on local calendar days, so across a DST transition a fall-back day is a genuine 25-hour window and a spring-forward day a 23-hour window (labelled at local midnight) — this is correct, not a defect.
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 5 minutes of walking within that period. Walk-only (not walk+stairs): stairs is easily confused with walking on a thigh sensor, so a walk+stairs sum can mask a window where genuine walking was suppressed by an orientation artifact.

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, diary: DataFrame) -> pd.DataFrame

Annotate the activity DataFrame with diary contexts.

For each distinct context in the diary, adds a boolean context__<name> column that is True for epochs inside any of that context's intervals (optionally gated by each interval's activities). Contexts may overlap; multiple intervals for one context union into a single column. Surrounding whitespace in context names is stripped, so ' work ' and 'work' collapse into one column. The input frame is not mutated — a copy is returned.

Parameters:

Name	Type	Description	Default
df	DataFrame	Activity DataFrame, timezone-aware DatetimeIndex, activity column.	required
diary	DataFrame	Clean diary with columns start, end, context and an optional per-row activities list, timezone-aware and in the same timezone as df's index.	required

Returns:

Type	Description
DataFrame	A copy of df with one context__<name> boolean column per context.