Callbacks API
from sklearn_genetic.callbacks import (
ThresholdStopping,
ConsecutiveStopping,
DeltaThreshold,
TimerStopping,
ProgressBar,
LogbookSaver,
ModelCheckpoint,
TensorBoard,
BaseCallback,
)Callbacks are passed to fit(X, y, callbacks=[...]). After each generation, on_step is called on every callback. If any callback returns True from on_step, the search stops at the end of that generation.
Available metric names for stopping callbacks: "fitness", "fitness_std", "fitness_best", "fitness_max", "fitness_min".
BaseCallback
Base class for custom callbacks. Subclass and override the methods you need.
class BaseCallback:
def on_start(self, estimator=None): ... # called before generation 0
def on_step(self, record=None, logbook=None, estimator=None) -> bool: ... # True = stop
def on_end(self, logbook=None, estimator=None): ... # called after the last generationon_step returning True stops the search. False (or None) continues.
ThresholdStopping
Stops when the metric reaches or exceeds a target value.
ThresholdStopping(threshold, metric="fitness")| Parameter | Type | Default | Description |
|---|---|---|---|
threshold | float | — | Stop when metric ≥ threshold |
metric | str | "fitness" | History column to watch |
Example: stop when mean population accuracy exceeds 0.98:
ThresholdStopping(threshold=0.98, metric="fitness_max")ConsecutiveStopping
Compares the current value with each of the previous N values and stops if it improves on none of them. Score metrics follow the search criterion: lower values improve a minimizing search and higher values improve a maximizing search. For fitness_std, an increase in dispersion counts as improvement in either direction.
ConsecutiveStopping(generations, metric="fitness")| Parameter | Type | Default | Description |
|---|---|---|---|
generations | int | — | Number of non-improving consecutive generations before stopping |
metric | str | "fitness" | History column to watch |
Example: stop if fitness_best hasn't improved in 8 generations:
ConsecutiveStopping(generations=8, metric="fitness_best")DeltaThreshold
Stops when the spread (max − min) of the metric across the last N generations falls below a threshold — detects convergence.
DeltaThreshold(threshold, generations=2, metric="fitness")| Parameter | Type | Default | Description |
|---|---|---|---|
threshold | float | — | Stop when max(metric[-N:]) - min(metric[-N:]) ≤ threshold |
generations | int | 2 | Window size |
metric | str | "fitness" | History column to watch |
TimerStopping
Stops starting new candidate batches after the wall-clock limit. An in-flight cross-validation batch, final selection and refit can finish after the limit. At least one initial batch completes so the search can return a fitted model.
TimerStopping(total_seconds)| Parameter | Type | Description |
|---|---|---|
total_seconds | float | Stop after this many elapsed seconds |
ProgressBar
Displays a tqdm progress bar. No parameters required.
ProgressBar()LogbookSaver
Writes the per-candidate evaluation records with joblib after each generation. The saved object can be iterated to inspect each row. Use ModelCheckpoint for search snapshots.
LogbookSaver(checkpoint_path)| Parameter | Type | Description |
|---|---|---|
checkpoint_path | str or Path | File path for the pickled logbook |
Restore with:
from joblib import load
logbook = load("./logbook.pkl")ModelCheckpoint
Saves a snapshot at a reported generation. DEAP stores its historical continuation state. SciPy, pymoo, Nevergrad and CatCMAwM resume from a completed generation when you pass the same checkpoint path to fit again with the same data, settings and environment. Older shared-runtime snapshots with resumable=False remain readable for inspection. See the resume recipe and the optional plugin protocol. Use a fresh path for an independent run and load only trusted snapshots.
ModelCheckpoint(checkpoint_path)| Parameter | Type | Description |
|---|---|---|
checkpoint_path | str or Path | File path for the checkpoint |
Inspect a saved snapshot from either format:
from sklearn_genetic.callbacks import ModelCheckpoint
snapshot = ModelCheckpoint("./checkpoint.pkl").load()
print(len(snapshot["logbook"])) # generation records
if "optimizer_checkpoint_version" in snapshot:
print(snapshot["backend"], snapshot["resumable"], len(snapshot["candidate_records"]))
else:
print(snapshot["estimator_state"]["generations"]) # historical DEAP formatLegacy TensorBoard callback
TensorBoard remains available for existing integrations. It writes the five generation fitness metrics as TensorFlow scalars and requires a separate TensorFlow installation. Importing sklearn_genetic.callbacks does not import TensorFlow.
TensorBoard(log_dir="./logs", run_id=None)| Parameter | Type | Description |
|---|---|---|
log_dir | str | Parent directory for summary files |
run_id | str or None | Subdirectory; defaults to a timestamp |
For current workflows, use LivePlot and plot_search_overview with sklearn-genetic-opt[plot] instead.
See Also
- Callbacks Guide — usage examples and combining callbacks
- Custom Callbacks — writing your own callback