Skip to content

openavmkit.tuning

Hyperparameter tuning for tree-based models.

Uses Optuna to search hyperparameter spaces for XGBoost, LightGBM, and CatBoost models with k-fold cross-validation, optimizing for mean absolute percentage error. Called from :mod:openavmkit.modeling when a model entry requests tuning rather than fixed parameters.

All public APIs are private (underscore-prefixed) — tuning is invoked indirectly through model setup, not as a user-facing operation.

catboost_one_hot_max_size 

catboost_one_hot_max_size(categories='auto', platform=None)

CatBoost's one_hot_max_size for a model entry's categories setting, or None for CatBoost's own default.

Source code in openavmkit/tuning.py 
105
106
107
108
109
110
111
112
113
114
def catboost_one_hot_max_size(categories: str | None = "auto", platform: str | None = None) -> int | None:
    """CatBoost's ``one_hot_max_size`` for a model entry's ``categories`` setting, or None for CatBoost's own default."""
    categories = categories or "auto"
    if categories not in CATBOOST_CATEGORIES:
        raise ValueError(
            f'CatBoost "categories" must be one of {", ".join(CATBOOST_CATEGORIES)}, not "{categories}".'
        )
    if categories == "auto":
        categories = "one_hot" if (platform or sys.platform) == "win32" else "catboost"
    return CATBOOST_ONE_HOT_MAX if categories == "one_hot" else None

catboost_thread_count 

catboost_thread_count()

The threads a CatBoost fit or CV here may use: the fold's share when folds run in parallel (OPENAVMKIT_CATBOOST_THREADS), else the trial-level cap (OPENAVMKIT_TUNE_WORKERS), else CatBoost's own default (every core).

Source code in openavmkit/tuning.py 
58
59
60
61
62
63
64
65
66
67
68
69
def catboost_thread_count():
    """The threads a CatBoost fit or CV here may use: the fold's share when folds run in parallel
    (``OPENAVMKIT_CATBOOST_THREADS``), else the trial-level cap (``OPENAVMKIT_TUNE_WORKERS``), else CatBoost's own
    default (every core)."""
    for name in (CATBOOST_THREADS_ENV, "OPENAVMKIT_TUNE_WORKERS"):
        value = os.environ.get(name)
        if value:
            try:
                return max(1, int(value))
            except ValueError:
                pass
    return None