peach.tl.SearchConfig

class peach.tl.SearchConfig(n_archetypes_range=None, hidden_dims_options=None, cv_folds=5, max_epochs_cv=100, early_stopping_patience=5, subsample_fraction=0.5, max_cells_cv=15000, speed_preset='balanced', use_pcha_init=True, inflation_factor_range=None, random_state=42)

Bases: object

Configuration for hyperparameter search space and CV settings.

Defines the hyperparameter grid to search and cross-validation parameters. Speed presets automatically adjust epochs and early stopping for different use cases.

Parameters:

• n_archetypes_range (list[int] | None, default: None) – Range of archetype numbers to test. If None, defaults to [2, 3, 4, 5, 6, 7].

• hidden_dims_options (list[list[int]] | None, default: None) – Network architectures to test. If None, defaults to standard options: [[128, 64], [256, 128, 64], [128], [512, 256, 128]].

• inflation_factor_range (list[float] | None, default: None) – Inflation factors to test. If None, uses [1.5] (Helsinki optimal). Set to multiple values (e.g., [1.0, 1.5, 2.0]) to search inflation.

• cv_folds (int, default: 5) – Number of cross-validation folds.

• max_epochs_cv (int, default: 100) – Maximum epochs per CV fold (overridden by speed_preset).

• early_stopping_patience (int, default: 5) – Patience for early stopping (overridden by speed_preset).

• subsample_fraction (float, default: 0.5) – Fraction of data to use for CV when dataset > max_cells_cv.

• max_cells_cv (int, default: 15000) – Maximum cells for CV. Larger datasets are subsampled.

• speed_preset (str, default: "balanced") –

  Training speed preset. Options:

  • "fast" : 25 epochs, patience=3 (quick exploration)

  • "balanced" : 50 epochs, patience=5 (recommended)

  • "thorough" : 100 epochs, patience=8 (comprehensive)

• use_pcha_init (bool, default: True) – Whether to use PCHA initialization for archetypes.

• random_state (int, default: 42) – Random seed for reproducibility.

_search_inflation

Internal flag indicating whether inflation is being searched (True if inflation_factor_range was explicitly provided).

Type:

bool

Raises:

ValueError – If n_archetypes_range contains non-positive integers. If cv_folds <= 0. If max_epochs_cv <= 0. If subsample_fraction not in (0, 1]. If max_cells_cv <= 0. If inflation_factor_range contains non-positive values.

Examples

>>> # Basic configuration
>>> config = SearchConfig(n_archetypes_range=[3, 4, 5], cv_folds=3, speed_preset="fast")
>>> # Search inflation factors
>>> config = SearchConfig(n_archetypes_range=[4, 5, 6], inflation_factor_range=[1.0, 1.5, 2.0], cv_folds=5)
>>> print(f"Searching inflation: {config._search_inflation}")  # True

See also

ArchetypalGridSearch

Uses this configuration

peach.tl.hyperparameter_search

User-facing wrapper

__init__(n_archetypes_range=None, hidden_dims_options=None, cv_folds=5, max_epochs_cv=100, early_stopping_patience=5, subsample_fraction=0.5, max_cells_cv=15000, speed_preset='balanced', use_pcha_init=True, inflation_factor_range=None, random_state=42)

Methods

__init__([n_archetypes_range, ...])

Attributes

cv_folds
early_stopping_patience
hidden_dims_options
inflation_factor_range
max_cells_cv
max_epochs_cv
n_archetypes_range
random_state
speed_preset
subsample_fraction
use_pcha_init

n_archetypes_range: list[int] = None

hidden_dims_options: list[list[int]] = None

cv_folds: int = 5

max_epochs_cv: int = 100

early_stopping_patience: int = 5

subsample_fraction: float = 0.5

max_cells_cv: int = 15000

speed_preset: str = 'balanced'

use_pcha_init: bool = True

inflation_factor_range: list[float] = None

random_state: int = 42

__post_init__()

Initialize defaults and validate inputs.