Skip to content

Callbacks API ​

python
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.

python
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 generation

on_step returning True stops the search. False (or None) continues.

ThresholdStopping ​

Stops when the metric reaches or exceeds a target value.

python
ThresholdStopping(threshold, metric="fitness")
ParameterTypeDefaultDescription
thresholdfloat—Stop when metric ≥ threshold
metricstr"fitness"History column to watch

Example: stop when mean population accuracy exceeds 0.98:

python
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.

python
ConsecutiveStopping(generations, metric="fitness")
ParameterTypeDefaultDescription
generationsint—Number of non-improving consecutive generations before stopping
metricstr"fitness"History column to watch

Example: stop if fitness_best hasn't improved in 8 generations:

python
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.

python
DeltaThreshold(threshold, generations=2, metric="fitness")
ParameterTypeDefaultDescription
thresholdfloat—Stop when max(metric[-N:]) - min(metric[-N:]) ≤ threshold
generationsint2Window size
metricstr"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.

python
TimerStopping(total_seconds)
ParameterTypeDescription
total_secondsfloatStop after this many elapsed seconds

ProgressBar ​

Displays a tqdm progress bar. No parameters required.

python
ProgressBar()

LogbookSaver ​

Saves the generation logbook to a file after each generation using joblib.dump.

python
LogbookSaver(checkpoint_path)
ParameterTypeDescription
checkpoint_pathstr or PathFile path for the pickled logbook

Restore with:

python
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.

python
ModelCheckpoint(checkpoint_path)
ParameterTypeDescription
checkpoint_pathstr or PathFile path for the checkpoint

Inspect the saved state:

python
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.

python
TensorBoard(log_dir="./logs", run_id=None)
ParameterTypeDescription
log_dirstrParent directory for summary files
run_idstr or NoneSubdirectory; defaults to a timestamp

For current workflows, use LivePlot and plot_search_overview with sklearn-genetic-opt[plot] instead.

See Also ​

Released under the MIT License.