Skip to content

_output

_output ¤

Canonical event-output column schema and helpers for ts-shape detectors.

Every public DataFrame-returning method on a detector class under ts_shape.events.* MUST emit one of three canonical shapes:

  • point -- a single timestamp per row, in the systime column.
  • interval -- explicit start / end columns plus duration_seconds.
  • summary -- a windowed aggregate; same time columns as interval.

Use :func:empty_event_df whenever a method has no rows to return, and :func:finalize_point_df, :func:finalize_interval_df, or :func:finalize_summary_df to attach standard identity columns and ensure canonical column ordering before returning. This guarantees consumers see the same column names regardless of detector pack or method.

validate_event_output ¤

validate_event_output(
    df: DataFrame, shape: Shape
) -> pd.DataFrame

Assert that df conforms to the canonical schema for shape.

A lightweight contract check for detector output: confirms the required columns for the given shape are present. Use it in tests or at the end of a custom detector to guarantee downstream consumers (event-log normalizers, OCEL/XES exporters) see the expected columns.

Parameters:

Name Type Description Default
df DataFrame

The detector output to validate.

 required
shape Shape

One of "point", "interval" or "summary".

 required

Returns:

Type Description
DataFrame

The same df unchanged, so the call can wrap a return value.

Raises:

Type Description
TypeError

If df is not a DataFrame.
ValueError

If shape is unknown or required columns are missing.

empty_event_df ¤

empty_event_df(
    shape: Shape, extra_cols: Sequence[str] = ()
) -> pd.DataFrame

Return an empty DataFrame with the canonical columns for shape.

extra_cols are appended after the required columns and may include optional standard columns (severity, value, is_delta) plus detector-specific columns. Duplicates are removed while preserving order.

finalize_point_df ¤

finalize_point_df(
    df: DataFrame,
    *,
    uuid: str | None,
    source_uuid: str | None,
    time_col: str = COL_SYSTIME
) -> pd.DataFrame

Attach identity columns and canonical column order to a point-event df.

If time_col differs from systime the column is renamed. Existing uuid / source_uuid columns are preserved if present; otherwise the supplied scalars are broadcast.

finalize_interval_df ¤

finalize_interval_df(
    df: DataFrame,
    *,
    uuid: str | None,
    source_uuid: str | None
) -> pd.DataFrame

Attach identity columns, compute duration_seconds, and canonicalize order.

The DataFrame must already contain start and end (datetime) columns.

finalize_summary_df ¤

finalize_summary_df(
    df: DataFrame,
    *,
    uuid: str | None = None,
    source_uuid: str | None = None
) -> pd.DataFrame

Attach optional identity columns and canonicalize a summary/window df.

The DataFrame must already contain start and end (datetime) columns. uuid / source_uuid are optional for summary rows; pass None to omit when the aggregate spans multiple sources.