mostlyright.spine

mr.spine() — the BYO bridge into the guarded align world (04).

spine(df, *, entity, decision_time, y, label_available_time=None) lifts a user-built frame into the canonical SpineContract shape (station, decision_time, label_available_time, y_*) with EXPLICIT column mapping. It is the rung-2 escape hatch for “I built my own target frame — let me into the guarded world”: the researcher names which of their columns is the entity, which is the point-in-time decision_time cutoff, and which are the y targets.

Threat (PIT integrity): the mapping is NEVER guessed. A frame missing the mapped decision_time (or entity / a y column) raises ContractError through the shared _errmsg builder (R-17) — a wrong column mapping (a label leaking as decision_time) can never slip through silently. The user’s entity column is renamed to the canonical station key (the shape align() / SpineContract consume); when the user does not map a label_available_time it defaults to decision_time (a conservative, non-leaking default — the label is treated as known no earlier than the decision).

Reuses the label-axis machinery (align_byo_labels / _coerce_date_column) so a Feast-shaped entity_df whose decision_time lives in a datetime index is handled identically to the BYO-label path — the guarded world is canonical.

Functions

spine(df, *, entity, decision_time, y[, …])	Map a BYO frame into the canonical guarded spine shape.

mostlyright.spine.spine(df, , entity, decision_time, y, label_available_time=None)

Map a BYO frame into the canonical guarded spine shape.

• Parameters:
  • df (DataFrame) – The user-built target frame.
  • entity (str) – The column naming the entity (renamed to the canonical station key).
  • decision_time (str) – The column holding the per-row point-in-time cutoff. If it is absent as a column but lives in a datetime / date-named index, the index is lifted into a column first (reusing _coerce_date_column).
  • y (str | list[str] | tuple[str, ...]) – The target column name(s). A spine with no target is meaningless.
  • label_available_time (str | None) – Optional column naming when the label became known; defaults to decision_time when unmapped (conservative, non-leaking).
• Return type: DataFrame
• Returns: A SpineContract-valid frame (station, decision_time, label_available_time, *y).
• Raises: ContractError – a mapped column (entity / decision_time / a y) is absent from the frame (— the mapping is never guessed).