context_enricher

context_enricher ¤

ContextEnricher ¤

ContextEnricher(
    dataframe: DataFrame, *, uuid_column: str = "uuid"
)

Enrich timeseries DataFrames with contextual metadata.

Merges metadata (descriptions, units, tolerances, value mappings) onto timeseries data using UUID-based lookups. This enables downstream analytics to access context without separate lookups.

Each enrich_* call works on the result of the previous one, so the calls chain; :meth:get_enriched_dataframe returns the cumulative result. Keys are compared as text (a numeric uuid column matches string uuids). A lookup table with duplicate keys, or a column that already exists in the data, raises ValueError instead of silently picking a row or adding _x / _y columns.

Example usage::

enricher = ContextEnricher(timeseries_df)

# Add descriptions and units from metadata
enricher.enrich_with_metadata(
    metadata_df,
    metadata_uuid_column="uuid",
    columns=["description", "unit", "area"],
)

# Add tolerance limits (on top of the metadata columns)
enricher.enrich_with_tolerances(
    tolerance_df,
    tolerance_uuid_column="uuid",
    low_col="low_limit",
    high_col="high_limit",
)
enriched = enricher.get_enriched_dataframe()

Initialize with a timeseries DataFrame.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Timeseries DataFrame with a UUID column.	required
`uuid_column`	`str`	Column name for signal UUID.	`'uuid'`

enrich_with_metadata ¤

enrich_with_metadata(
    metadata: DataFrame,
    *,
    metadata_uuid_column: str = "uuid",
    columns: list[str] | None = None
) -> pd.DataFrame

Join metadata columns onto timeseries by UUID.

Parameters:

Name	Type	Description	Default
`metadata`	`DataFrame`	Metadata DataFrame containing signal info.	required
`metadata_uuid_column`	`str`	UUID column in metadata (formerly `metadata_uuid_col`).	`'uuid'`
`columns`	`list[str] \| None`	Specific columns to merge. If None, merges all non-UUID columns.	`None`

Returns:

Type	Description
`DataFrame`	The enriched DataFrame (also kept for the next `enrich_*` call).

Raises:

Type	Description
`ColumnNotFoundError`	When a named column is missing.
`ValueError`	For duplicate uuids in `metadata` or a column that already exists in the data.

enrich_with_tolerances ¤

enrich_with_tolerances(
    tolerances: DataFrame,
    *,
    tolerance_uuid_column: str = "uuid",
    low_col: str = "low_limit",
    high_col: str = "high_limit"
) -> pd.DataFrame

Attach tolerance limits from a tolerance DataFrame.

Parameters:

Name	Type	Description	Default
`tolerances`	`DataFrame`	DataFrame with UUID, low_limit, high_limit columns.	required
`tolerance_uuid_column`	`str`	UUID column in tolerances (formerly `tolerance_uuid_col`).	`'uuid'`
`low_col`	`str`	Column with lower tolerance limit.	`'low_limit'`
`high_col`	`str`	Column with upper tolerance limit.	`'high_limit'`

Returns:

Type	Description
`DataFrame`	The enriched DataFrame (also kept for the next `enrich_*` call).

Raises:

Type	Description
`ColumnNotFoundError`	When a named column is missing.
`ValueError`	For duplicate uuids in `tolerances` or a limit column that already exists in the data.

enrich_with_mapping ¤

enrich_with_mapping(
    mapping: DataFrame,
    *,
    mapping_uuid_column: str = "uuid",
    raw_value_col: str = "raw_value",
    mapped_value_col: str = "mapped_value",
    value_column: str = "value_string"
) -> pd.DataFrame

Apply value mappings from a mapping DataFrame.

Maps raw values (e.g. numeric codes) to descriptive strings using a UUID-specific mapping table. Raw values are compared as text, so the code 1 (integer) matches the raw value "1".

Parameters:

Name	Type	Description	Default
`mapping`	`DataFrame`	DataFrame with uuid, raw_value, mapped_value columns.	required
`mapping_uuid_column`	`str`	UUID column in mapping (formerly `mapping_uuid_col`).	`'uuid'`
`raw_value_col`	`str`	Column with raw values to match.	`'raw_value'`
`mapped_value_col`	`str`	Column with mapped/descriptive values.	`'mapped_value'`
`value_column`	`str`	Column in timeseries to match against raw values.	`'value_string'`

Returns:

Type	Description
`DataFrame`	The DataFrame with a `mapped_value` column appended (also kept
`DataFrame`	for the next `enrich_*` call).

Raises:

Type	Description
`ColumnNotFoundError`	When a named column is missing.
`ValueError`	For duplicate `(uuid, raw value)` pairs, or when the data already has a `mapped_value` column.

get_enriched_dataframe ¤

get_enriched_dataframe() -> pd.DataFrame

Return the cumulative result of every enrich_* call so far.