phenotypic.tune.JournalStudyStore

class phenotypic.tune.JournalStudyStore(trials: list[Trial] | None = None)

Bases: object

An append-only journal of trials with best-tracking + parquet I/O.

The Phase-1 concrete StudyStore backend. It resumes by replay (the engine fast-forwards the deterministic strategy past the recorded trials), so is_resumable_in_place() is False — distinguishing it from a future Optuna RDBStorage backend whose own storage reconstructs the sampler state.

Methods

__init__	Initialize the journal.
append	Record one completed trial.
best	The non-failed trial with the lowest cost score, or None.
completed_count	The number of completed (non-failed) trials; pruned counts as done.
from_parquet	Reload a journal previously written by to_parquet().
is_resumable_in_place	Always False: the journal resumes by deterministic replay.
knee_point	The front trial at max perpendicular distance to the chord.
param_importances	Always None: the journal owns no native importance model.
pareto_front	The non-dominated trials by their objectives sidecar (plan §0a).
to_dataframe	One row per trial; params/terms/objectives as JSON strings.
to_parquet	Write the journal to path atomically (creating parent dirs).

Attributes

trials

A copy of the journaled trials in order.

Parameters:

trials (Optional[list[Trial]])

__init__(trials: list[Trial] | None = None) → None

Initialize the journal.

Parameters:

trials (list[Trial] | None) – Optional seed trials (e.g. a resumed run’s prior journal).

Return type:

None

append(trial: Trial) → None

Record one completed trial.

Parameters:

trial (Trial)

Return type:

None

property trials: list[Trial]

A copy of the journaled trials in order.

best() → Trial | None

The non-failed trial with the lowest cost score, or None.

Return type:

Trial | None

is_resumable_in_place() → bool

Always False: the journal resumes by deterministic replay.

Return type:

bool

completed_count() → int

The number of completed (non-failed) trials; pruned counts as done.

Return type:

int

param_importances() → dict[str, float] | None

Always None: the journal owns no native importance model.

The screening layer falls back to its RandomForest + permutation estimate over the journaled trials (screening-importance.md §1).

Return type:

dict[str, float] | None

pareto_front() → list[Trial]

The non-dominated trials by their objectives sidecar (plan §0a).

Delegates to the store-agnostic pareto_front_of() over the journaled trials. A single-objective journal (no trial carries objectives) returns [] while scalar best() still works.

Return type:

list[Trial]

knee_point(front: list[Trial]) → Trial | None

The front trial at max perpendicular distance to the chord.

Delegates to the store-agnostic knee_point_of(); None for an empty front.

Parameters:

front (list[Trial])

Return type:

Trial | None

to_dataframe() → pandas.DataFrame

One row per trial; params/terms/objectives as JSON strings.

objectives_json is None for single-objective trials (the column holds null) and json.dumps(t.objectives) for multi-objective ones.

Return type:

pandas.DataFrame

to_parquet(path: Path) → None

Write the journal to path atomically (creating parent dirs).

Writes to a sibling <path>.tmp first, then os.replace`s it over ``path`() (atomic on POSIX). A killed worker / full disk mid-serialize therefore leaves any pre-existing trials.parquet intact rather than a truncated file, and the temp is removed on failure so no .tmp debris lingers. The temp sibling shares path’s directory so the rename stays on one filesystem (the atomicity precondition).

Parameters:

path (Path)

Return type:

None

classmethod from_parquet(path: Path) → JournalStudyStore

Reload a journal previously written by to_parquet().

Reads objectives_json defensively: a legacy Phase-1/2 parquet predating the multi-objective sidecar (plan §0a) has no such column, and a single-objective trial stores null — both resolve to objectives=None so older journals still load.

Parameters:

path (Path)

Return type:

JournalStudyStore