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
Saves the generation logbook to a file after each generation using joblib.dump.
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 the search configuration, generation history and runtime state, including cached candidate scores, archived elites and random generator states. Each successful write replaces the previous snapshot. See the checkpoint recipe to resume a search.
ModelCheckpoint(checkpoint_path)| Parameter | Type | Description |
|---|---|---|
checkpoint_path | str or Path | File path for the checkpoint |
Inspect the saved state:
import pickle
with open("./checkpoint.pkl", "rb") as f:
checkpoint = pickle.load(f)
estimator_state = checkpoint["estimator_state"]
logbook = checkpoint["logbook"]Legacy 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