API Reference

GridSearchCV

gs = sp.GridSearchCV(estimator, param_grid, cv=5, seed=42, scoring="auto")
gs.fit(X, y)

RandomizedSearchCV

rs = sp.RandomizedSearchCV(estimator, param_distributions, n_iter=10, cv=5, seed=42, scoring="auto")
rs.fit(X, y)

HalvingGridSearchCV

hgs = sp.HalvingGridSearchCV(estimator, param_grid, cv=5, factor=3, seed=42, scoring="auto")
hgs.fit(X, y)

HalvingRandomSearchCV

hrs = sp.HalvingRandomSearchCV(estimator, param_distributions, n_candidates=256, cv=5, factor=3, seed=42, scoring="auto")
hrs.fit(X, y)

Constructor parameters — GridSearchCV

Constructor parameters — RandomizedSearchCV

Constructor parameters — HalvingGridSearchCV

Constructor parameters — HalvingRandomSearchCV

Attributes (all classes)

Scoring

"auto" selects the default metric: R² for regressors, accuracy for classifiers.

Regression metrics

Classification metrics

import seraplot as sp
import numpy as np

X = np.random.randn(500, 5)
y = X @ np.array([1.0, -2.0, 0.5, 1.5, -0.8]) + np.random.randn(500) * 0.5

gs = sp.GridSearchCV(
    "Ridge",
    {"alpha": [0.01, 0.1, 1.0, 10.0]},
    cv=5,
    scoring="neg_mean_squared_error",
)
gs.fit(X, y)
print(f"Best params: {gs.best_params_}")
print(f"Best score:  {gs.best_score_:.4f}")

import seraplot as sp
import numpy as np

X = np.random.randn(500, 10)
y = (X[:, 0] + X[:, 1] > 0).astype(int)

rs = sp.RandomizedSearchCV(
    "RandomForestClassifier",
    {
        "n_estimators": [50, 100, 200],
        "max_depth": [3, 5, 10, 15],
        "min_samples_split": [2, 5, 10],
    },
    n_iter=20,
    cv=5,
    scoring="f1",
)
rs.fit(X, y)
print(f"Best params: {rs.best_params_}")
print(f"Best score:  {rs.best_score_:.4f}")

import seraplot as sp
import numpy as np

X = np.random.randn(1000, 8)
y = X @ np.random.randn(8) + np.random.randn(1000) * 0.3

hrs = sp.HalvingRandomSearchCV(
    "Lasso",
    {"alpha": [0.001, 0.01, 0.1, 0.5, 1.0, 5.0, 10.0]},
    n_candidates=256,
    factor=3,
    cv=5,
)
hrs.fit(X, y)
print(f"Best params:  {hrs.best_params_}")
print(f"Best score:   {hrs.best_score_:.4f}")
print(f"Iterations:   {hrs.n_iterations_}")

Algorithmic Functioning

Cross-Validation

Each candidate is evaluated using stratified k-fold (classification) or shuffled k-fold (regression). For $k$ folds, the dataset is split into $k$ subsets; the model trains on $k-1$ folds and scores on the held-out fold. The final score is the mean over all $k$ folds:

Exhaustive vs Random Search

GridSearchCV evaluates every combination in the Cartesian product of the parameter grid:

where $|V_j|$ is the number of values for the $j$-th parameter.

RandomizedSearchCV samples $n_{\text{iter}}$ combinations uniformly at random.

Successive Halving

HalvingGridSearchCV and HalvingRandomSearchCV use the successive halving strategy. Starting with a small resource budget $r_0$ and all candidates, each round:

1. Evaluate all remaining candidates with resource $r_i$
2. Keep the top $\frac{1}{\text{factor}}$ candidates
3. Increase the resource: $r_{i+1} = r_i \times \text{factor}$

The initial resource is:

and $C$ is the number of candidates. This eliminates weak configurations early while spending full resources only on promising ones.

Optimizations

Benchmarks vs scikit-learn GridSearchCV