normalizer

normalizer

Public to_event_log entry point — looks up the adapter and runs it.

to_event_log

to_event_log(
    dataframe: DataFrame,
    *,
    detector: str,
    objects: Mapping[str, object] | None = None,
    qualifiers: Mapping[str, str] | None = None,
    o2o: TableInput = None,
    object_changes: TableInput = None,
    validate: bool = True,
    timestamp: object | None = None
) -> EventLog

Normalize a detector frame (a detector's output DataFrame) into the canonical event log.

Timestamps: tz-aware times are converted to UTC; naive times are taken to be UTC (localize them first if they are local wall-clock times). Interval rows that end before they start are dropped with a :class:~ts_shape.errors.DataQualityWarning.

Event ids (ocel:eid) are content-based: a hash of the detector, the row's source_uuid, its timestamps, the activity and every other column of the row. They are reproducible across runs, independent of row order, and the same detector on two machines does not collide.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	The detector frame.	required
detector	str	"ClassName.method_name" -- the key used in the taxonomy registry and the value written to ts_shape:detector. Deprecated names resolve to the current ones.	required
objects	Mapping[str, object] | None	Binds OCEL object types to, per type: a column name of dataframe (e.g. {"asset": "source_uuid"}); any other string or scalar -- a literal broadcast to every row ({"line": "L1"}); None binds no object; a callable taking a row dict and returning an oid; a pd.Series aligned with dataframe by index label (a length or label mismatch raises ValueError). Types listed in the rule's produces_objects are also auto-extracted from standard columns (source_uuid -> asset) when not bound explicitly.	None
qualifiers	Mapping[str, str] | None	Relation qualifier per object type.	None
o2o	TableInput	OCEL 2.0 object-to-object relations, a DataFrame or iterable of dict rows with ocel:oid / ocel:oid2 (ocel:qualifier optional); see :func:~ts_shape.eventlog.schema.empty_o2o.	None
object_changes	TableInput	Time-varying object attributes with ocel:oid, ocel:type, ocel:field, ocel:timestamp (ocel:value optional); see :func:~ts_shape.eventlog.schema.empty_object_changes. Naive timestamps are read as UTC.	None
validate	bool	Check the result against the canonical schema.	True
timestamp	object | None	Timestamp of the events of a static shape detector (which has no time column). Default: the Unix epoch (1970-01-01T00:00Z), so results are reproducible.	None

Returns:

Type	Description
EventLog	The canonical :class:~ts_shape.eventlog.model.EventLog.

Raises:

Type	Description
ValueError	For a malformed detector name, a misaligned Series binding or a table missing required columns.
KeyError	When the detector has no taxonomy entry, or the frame lacks the time columns of its shape.