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 finite COMPLETE trial with the lowest cost, 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	Return the front knee using optional fixed scorer axes.
param_importances	Always None: the journal owns no native importance model.
pareto_front	Return finite non-dominated COMPLETE trials on optional fixed axes.
terminal_trials	Return every journal entry; this backend has no in-flight records.
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.

terminal_trials() → list[Trial]

Return every journal entry; this backend has no in-flight records.

Return type:

list[Trial]

best() → Trial | None

The finite COMPLETE trial with the lowest cost, 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(objective_axes: Sequence[str] | None = None) → list[Trial]

Return finite non-dominated COMPLETE trials on optional fixed axes.

Parameters:

objective_axes (Sequence[str] | None)

Return type:

list[Trial]

knee_point(front: list[Trial], objective_axes: Sequence[str] | None = None) → Trial | None

Return the front knee using optional fixed scorer axes.

Parameters:

• front (list[Trial])

• objective_axes (Sequence[str] | None)

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