Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/core_concepts/reproducibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,9 @@ pre.set_params(...) # raises FrozenRepresentationError while frozen
Freezing is useful when a representation is validated and about to ship. To make a fresh,
unfrozen copy, use `clone_unfitted()`. To retrain, `refit(X, y)` returns a **new** fitted
object and leaves the original untouched, and `mark_stale(reason)` records why an existing one
should no longer be used.
should no longer be used. The mark is advisory and describes the current fitted state: fitting
the same (unfrozen) object again with `fit` replaces that state, so a successful `fit` clears
the mark and the state returns to `FITTED`.

```{warning}
`fit`, `fit_transform`, and `set_params` on a frozen preprocessor raise `FrozenRepresentationError`. This is deliberate:
Expand Down
9 changes: 8 additions & 1 deletion pretab/preprocessor.py
Original file line number Diff line number Diff line change
Expand Up @@ -709,6 +709,11 @@ def fit(self, X, y=None, embeddings=None):

self._enforce_output_budget(X.shape[0])

# This fit replaces the fitted state that mark_stale() flagged as outdated.
# The attribute is removed instead of reset, so a spec of a never-stale
# preprocessor is unchanged.
self.__dict__.pop("_stale_reason", None)

if verbose >= 1:
numerical_summary = _method_summary(numerical_features, is_numerical=True, config=config)
categorical_summary = _method_summary(categorical_features, is_numerical=False, config=config)
Expand Down Expand Up @@ -1512,7 +1517,9 @@ def mark_stale(self, reason: str) -> "Preprocessor":

Records ``reason`` and flips :attr:`lifecycle_state_` to ``STALE`` (unless
already ``FROZEN``). Purely advisory: it does not alter the fitted state.
Returns ``self`` for chaining.
A later successful :meth:`fit` of this object replaces that state, so it
clears the mark and the state returns to ``FITTED``; a ``fit`` that raises
leaves the mark in place. Returns ``self`` for chaining.
"""
check_is_fitted(self)
self._stale_reason = reason
Expand Down
49 changes: 48 additions & 1 deletion tests/integration/test_frozen_lifecycle.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
import pandas as pd
import pytest

from pretab import FrozenRepresentationError, Preprocessor
from pretab import FrozenRepresentationError, OutputBudgetError, Preprocessor


@pytest.fixture
Expand Down Expand Up @@ -101,6 +101,53 @@ def test_mark_stale(frame, target):
assert p.stale_reason_ == "input schema drifted"


def test_fit_clears_the_stale_mark(frame, target):
"""A successful fit replaces the state the mark described; it used to stay STALE."""
p = _make().fit(frame, target)
p.mark_stale("drift")
p.fit(frame.assign(a=frame["a"] * 2), target)
assert p.lifecycle_state_ == "FITTED"
assert p.stale_reason_ is None


def test_fit_transform_clears_the_stale_mark(frame, target):
p = _make().fit(frame, target)
p.mark_stale("drift")
p.fit_transform(frame, target)
assert p.lifecycle_state_ == "FITTED"
assert p.stale_reason_ is None


def test_failed_fit_keeps_the_stale_mark(frame, target):
p = _make().fit(frame, target)
p.mark_stale("drift")
p.set_params(max_output_features=1)
with pytest.raises(OutputBudgetError):
p.fit(frame, target)
assert p.stale_reason_ == "drift"


def test_fit_does_not_add_stale_state_to_the_spec(frame, target):
"""Clearing the mark removes the attribute, so specs of never-stale fits are unchanged."""
never_stale = _make().fit(frame, target)
assert "_stale_reason" not in never_stale.to_spec()["state"]

refitted = _make().fit(frame, target)
refitted.mark_stale("drift")
refitted.fit(frame, target)
assert refitted.to_spec()["state"] == never_stale.to_spec()["state"]
assert refitted.fingerprint_ == never_stale.fingerprint_


def test_stale_mark_survives_a_spec_round_trip_until_refit(frame, target):
p = _make().fit(frame, target)
p.mark_stale("drift")
restored = Preprocessor.from_spec(p.to_spec())
assert restored.lifecycle_state_ == "STALE"
restored.fit(frame, target)
assert restored.lifecycle_state_ == "FITTED"


def test_frozen_takes_precedence_over_stale(frame, target):
p = _make().fit(frame, target)
p.mark_stale("drift")
Expand Down