spforge 0.8.4__py3-none-any.whl → 0.8.18__py3-none-any.whl

spforge/hyperparameter_tuning/_tuner.py

@@ -45,6 +45,8 @@ class ParamSpec:
         elif self.param_type == "int":
             if self.low is None or self.high is None:
                 raise ValueError(f"int parameter '{name}' requires low and high bounds")
+            if self.step is None:
+                return trial.suggest_int(name, int(self.low), int(self.high))
             return trial.suggest_int(name, int(self.low), int(self.high), step=self.step)
         elif self.param_type == "categorical":
             if self.choices is None:
@@ -272,3 +274,193 @@ class RatingHyperparameterTuner:
                 raise ValueError("Scorer returned invalid values in dict")
             return float(np.mean(values))
         return float(score)
+
+
+def _is_estimator(obj: object) -> bool:
+    return hasattr(obj, "get_params") and hasattr(obj, "set_params")
+
+
+def _get_leaf_estimator_paths(estimator: Any) -> dict[str, Any]:
+    if not _is_estimator(estimator):
+        raise ValueError("estimator must implement get_params and set_params")
+
+    params = estimator.get_params(deep=True)
+    estimator_keys = [k for k, v in params.items() if _is_estimator(v)]
+
+    if not estimator_keys:
+        return {"": estimator}
+
+    leaves: list[str] = []
+    for key in estimator_keys:
+        if not any(other != key and other.startswith(f"{key}__") for other in estimator_keys):
+            leaves.append(key)
+
+    return {key: params[key] for key in sorted(leaves)}
+
+
+def _build_search_space_for_targets(
+    targets: dict[str, dict[str, ParamSpec]],
+) -> dict[str, ParamSpec]:
+    search_space: dict[str, ParamSpec] = {}
+    for path, params in targets.items():
+        for param_name, param_spec in params.items():
+            full_name = f"{path}__{param_name}" if path else param_name
+            if full_name in search_space:
+                raise ValueError(f"Duplicate parameter name detected: {full_name}")
+            search_space[full_name] = param_spec
+    return search_space
+
+
+def _enqueue_predicted_r_weight_zero(study: optuna.Study, search_space: dict[str, ParamSpec]):
+    zero_params: dict[str, float] = {}
+    for name, spec in search_space.items():
+        if not name.endswith("predicted_r_weight"):
+            continue
+        if spec.param_type not in {"float", "int"}:
+            continue
+        if spec.low is None or spec.high is None:
+            continue
+        if spec.low <= 0 <= spec.high:
+            zero_params[name] = 0.0
+
+    if zero_params:
+        study.enqueue_trial(zero_params)
+
+
+class EstimatorHyperparameterTuner:
+    """
+    Hyperparameter tuner for sklearn-compatible estimators.
+
+    Supports nested estimators and can target deepest leaf estimators.
+    """
+
+    def __init__(
+        self,
+        estimator: Any,
+        cross_validator: MatchKFoldCrossValidator,
+        scorer: BaseScorer,
+        direction: Literal["minimize", "maximize"],
+        param_search_space: dict[str, ParamSpec] | None = None,
+        param_targets: dict[str, dict[str, ParamSpec]] | None = None,
+        n_trials: int = 50,
+        n_jobs: int = 1,
+        storage: str | None = None,
+        study_name: str | None = None,
+        timeout: float | None = None,
+        show_progress_bar: bool = True,
+        sampler: optuna.samplers.BaseSampler | None = None,
+        pruner: optuna.pruners.BasePruner | None = None,
+    ):
+        self.estimator = estimator
+        self.cross_validator = cross_validator
+        self.scorer = scorer
+        self.direction = direction
+        self.param_search_space = param_search_space
+        self.param_targets = param_targets
+        self.n_trials = n_trials
+        self.n_jobs = n_jobs
+        self.storage = storage
+        self.study_name = study_name
+        self.timeout = timeout
+        self.show_progress_bar = show_progress_bar
+        self.sampler = sampler
+        self.pruner = pruner
+
+        if direction not in ["minimize", "maximize"]:
+            raise ValueError(f"direction must be 'minimize' or 'maximize', got: {direction}")
+
+        if storage is not None and study_name is None:
+            raise ValueError("study_name is required when using storage")
+
+        if param_search_space is not None and param_targets is not None:
+            raise ValueError("param_search_space and param_targets cannot both be provided")
+
+    def optimize(self, df: IntoFrameT) -> OptunaResult:
+        from spforge.hyperparameter_tuning._default_search_spaces import (
+            get_default_estimator_search_space,
+        )
+
+        leaf_estimators = _get_leaf_estimator_paths(self.estimator)
+        default_targets = {
+            path: get_default_estimator_search_space(est)
+            for path, est in leaf_estimators.items()
+        }
+        default_targets = {path: space for path, space in default_targets.items() if space}
+
+        if self.param_targets is not None:
+            unknown = set(self.param_targets) - set(leaf_estimators)
+            if unknown:
+                raise ValueError(f"param_targets contains unknown estimator paths: {unknown}")
+            targets = self.param_targets
+        elif self.param_search_space is not None:
+            targets = {path: self.param_search_space for path in leaf_estimators}
+        elif default_targets:
+            targets = default_targets
+        else:
+            raise ValueError(
+                "param_search_space is required when no default search space is available"
+            )
+
+        search_space = _build_search_space_for_targets(targets)
+        if not search_space:
+            raise ValueError("Resolved search space is empty")
+
+        study = optuna.create_study(
+            direction=self.direction,
+            sampler=self.sampler,
+            pruner=self.pruner,
+            storage=self.storage,
+            study_name=self.study_name,
+            load_if_exists=True if self.storage else False,
+        )
+
+        _enqueue_predicted_r_weight_zero(study, search_space)
+
+        study.optimize(
+            lambda trial: self._objective(trial, df, search_space),
+            n_trials=self.n_trials,
+            n_jobs=self.n_jobs,
+            timeout=self.timeout,
+            show_progress_bar=self.show_progress_bar,
+        )
+
+        return OptunaResult(
+            best_params=study.best_params,
+            best_value=study.best_value,
+            best_trial=study.best_trial,
+            study=study,
+        )
+
+    def _objective(
+        self, trial: optuna.Trial, df: IntoFrameT, search_space: dict[str, ParamSpec]
+    ) -> float:
+        try:
+            trial_params = self._suggest_params(trial, search_space)
+
+            copied_estimator = copy.deepcopy(self.estimator)
+            copied_estimator.set_params(**trial_params)
+
+            cv = copy.deepcopy(self.cross_validator)
+            cv.estimator = copied_estimator
+
+            validation_df = cv.generate_validation_df(df)
+            score = self.scorer.score(validation_df)
+            score_value = RatingHyperparameterTuner._aggregate_score(score)
+
+            if math.isnan(score_value) or math.isinf(score_value):
+                logger.warning(f"Trial {trial.number} returned invalid score: {score_value}")
+                return float("inf") if self.direction == "minimize" else float("-inf")
+
+            return score_value
+
+        except Exception as e:
+            logger.warning(f"Trial {trial.number} failed with error: {e}")
+            return float("inf") if self.direction == "minimize" else float("-inf")
+
+    def _suggest_params(
+        self, trial: optuna.Trial, search_space: dict[str, ParamSpec]
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        for param_name, param_spec in search_space.items():
+            params[param_name] = param_spec.suggest(trial, param_name)
+        return params

spforge/performance_transformers/_performance_manager.py

@@ -250,8 +250,6 @@ class PerformanceWeightsManager(PerformanceManager):
                 )
             )
 
-        sum_weight = sum([w.weight for w in self.weights])
-
         for column_weight in self.weights:
             weight_col = f"weight__{column_weight.name}"
             feature_col = column_weight.name
@@ -261,14 +259,14 @@ class PerformanceWeightsManager(PerformanceManager):
                 df = df.with_columns(
                     (
                         nw.col(tmp_out_performance_colum_name)
-                        + (nw.col(weight_col) / sum_weight * (1 - nw.col(feature_name)))
+                        + (nw.col(weight_col) * (1 - nw.col(feature_name)))
                     ).alias(tmp_out_performance_colum_name)
                 )
             else:
                 df = df.with_columns(
                     (
                         nw.col(tmp_out_performance_colum_name)
-                        + (nw.col(weight_col) / sum_weight * nw.col(feature_name))
+                        + (nw.col(weight_col) * nw.col(feature_name))
                     ).alias(tmp_out_performance_colum_name)
                 )
 

spforge/ratings/__init__.py

@@ -6,3 +6,7 @@ from .enums import (
     RatingUnknownFeatures as RatingUnknownFeatures,
 )
 from .league_identifier import LeagueIdentifier as LeagueIdentifier
+from .league_start_rating_optimizer import (
+    LeagueStartRatingOptimizationResult as LeagueStartRatingOptimizationResult,
+    LeagueStartRatingOptimizer as LeagueStartRatingOptimizer,
+)

spforge/ratings/_player_rating.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import copy
 import math
+import logging
 from typing import Any, Literal
 
 import narwhals.stable.v2 as nw
@@ -15,6 +16,7 @@ from spforge.data_structures import (
     MatchPerformance,
     MatchPlayer,
     PlayerRating,
+    PlayerRatingChange,
     PlayerRatingsResult,
     PreMatchPlayerRating,
     PreMatchPlayersCollection,
@@ -33,6 +35,8 @@ from spforge.ratings.utils import (
 from spforge.feature_generator._utils import to_polars
 
 PLAYER_STATS = "__PLAYER_STATS"
+_SCALED_PW = "__scaled_participation_weight__"
+_SCALED_PPW = "__scaled_projected_participation_weight__"
 
 
 class PlayerRatingGenerator(RatingGenerator):
@@ -75,12 +79,13 @@ class PlayerRatingGenerator(RatingGenerator):
         start_min_count_for_percentiles: int = 50,
         start_team_rating_subtract: float = 80,
         start_team_weight: float = 0,
-        start_max_days_ago_league_entities: int = 120,
+        start_max_days_ago_league_entities: int = 600,
         start_min_match_count_team_rating: int = 2,
         start_harcoded_start_rating: float | None = None,
         column_names: ColumnNames | None = None,
         output_suffix: str | None = None,
         scale_participation_weights: bool = False,
+        auto_scale_participation_weights: bool = True,
         **kwargs: Any,
     ):
         super().__init__(
@@ -129,6 +134,9 @@ class PlayerRatingGenerator(RatingGenerator):
             str(RatingKnownFeatures.PLAYER_RATING_DIFFERENCE_PROJECTED)
         )
         self.MEAN_PROJ_COL = self._suffix(str(RatingKnownFeatures.RATING_MEAN_PROJECTED))
+        self.PLAYER_DIFF_FROM_TEAM_PROJ_COL = self._suffix(
+            str(RatingKnownFeatures.PLAYER_RATING_DIFFERENCE_FROM_TEAM_PROJECTED)
+        )
 
         self.TEAM_OFF_RATING_PROJ_COL = self._suffix(
             str(RatingKnownFeatures.TEAM_OFF_RATING_PROJECTED)
@@ -161,6 +169,7 @@ class PlayerRatingGenerator(RatingGenerator):
 
         self.use_off_def_split = bool(use_off_def_split)
         self.scale_participation_weights = bool(scale_participation_weights)
+        self.auto_scale_participation_weights = bool(auto_scale_participation_weights)
         self._participation_weight_max: float | None = None
         self._projected_participation_weight_max: float | None = None
 
@@ -186,9 +195,39 @@ class PlayerRatingGenerator(RatingGenerator):
         column_names: ColumnNames | None = None,
     ) -> DataFrame | IntoFrameT:
         self.column_names = column_names if column_names else self.column_names
+        self._maybe_enable_participation_weight_scaling(df)
         self._set_participation_weight_max(df)
         return super().fit_transform(df, column_names)
 
+    def _maybe_enable_participation_weight_scaling(self, df: DataFrame) -> None:
+        if self.scale_participation_weights or not self.auto_scale_participation_weights:
+            return
+        cn = self.column_names
+        if not cn:
+            return
+
+        pl_df = df.to_native() if df.implementation.is_polars() else df.to_polars().to_native()
+
+        def _out_of_bounds(col_name: str | None) -> bool:
+            if not col_name or col_name not in df.columns:
+                return False
+            col = pl_df[col_name]
+            min_val = col.min()
+            max_val = col.max()
+            if min_val is None or max_val is None:
+                return False
+            eps = 1e-6
+            return min_val < -eps or max_val > (1.0 + eps)
+
+        if _out_of_bounds(cn.participation_weight) or _out_of_bounds(
+            cn.projected_participation_weight
+        ):
+            self.scale_participation_weights = True
+            logging.warning(
+                "Auto-scaling participation weights because values exceed [0, 1]. "
+                "Set scale_participation_weights=True explicitly to silence this warning."
+            )
+
     def _ensure_player_off(self, player_id: str) -> PlayerRating:
         if player_id not in self._player_off_ratings:
             # create with start generator later; initialize to 0 now; overwritten when needed
@@ -237,6 +276,7 @@ class PlayerRatingGenerator(RatingGenerator):
             self._projected_participation_weight_max = self._participation_weight_max
 
     def _scale_participation_weight_columns(self, df: pl.DataFrame) -> pl.DataFrame:
+        """Create internal scaled participation weight columns without mutating originals."""
         if not self.scale_participation_weights:
             return df
         if self._participation_weight_max is None or self._participation_weight_max <= 0:
@@ -251,7 +291,7 @@ class PlayerRatingGenerator(RatingGenerator):
             df = df.with_columns(
                 (pl.col(cn.participation_weight) / denom)
                 .clip(0.0, 1.0)
-                .alias(cn.participation_weight)
+                .alias(_SCALED_PW)
             )
 
         if (
@@ -264,16 +304,38 @@ class PlayerRatingGenerator(RatingGenerator):
             df = df.with_columns(
                 (pl.col(cn.projected_participation_weight) / denom)
                 .clip(0.0, 1.0)
-                .alias(cn.projected_participation_weight)
+                .alias(_SCALED_PPW)
             )
 
         return df
 
+    def _get_participation_weight_col(self) -> str:
+        """Get the column name to use for participation weight (scaled if available)."""
+        cn = self.column_names
+        if self.scale_participation_weights and cn and cn.participation_weight:
+            return _SCALED_PW
+        return cn.participation_weight if cn else ""
+
+    def _get_projected_participation_weight_col(self) -> str:
+        """Get the column name to use for projected participation weight (scaled if available)."""
+        cn = self.column_names
+        if self.scale_participation_weights and cn and cn.projected_participation_weight:
+            return _SCALED_PPW
+        return cn.projected_participation_weight if cn else ""
+
+    def _remove_internal_scaled_columns(self, df: pl.DataFrame) -> pl.DataFrame:
+        """Remove internal scaled columns before returning."""
+        cols_to_drop = [c for c in [_SCALED_PW, _SCALED_PPW] if c in df.columns]
+        if cols_to_drop:
+            df = df.drop(cols_to_drop)
+        return df
+
     def _historical_transform(self, df: pl.DataFrame) -> pl.DataFrame:
         df = self._scale_participation_weight_columns(df)
         match_df = self._create_match_df(df)
         ratings = self._calculate_ratings(match_df)
 
+        # Keep scaled columns for now - they're needed by _add_rating_features
         cols = [
             c
             for c in df.columns
@@ -293,13 +355,15 @@ class PlayerRatingGenerator(RatingGenerator):
             on=[self.column_names.player_id, self.column_names.match_id, self.column_names.team_id],
         )
 
-        return self._add_rating_features(df)
+        result = self._add_rating_features(df)
+        return self._remove_internal_scaled_columns(result)
 
     def _future_transform(self, df: pl.DataFrame) -> pl.DataFrame:
         df = self._scale_participation_weight_columns(df)
         match_df = self._create_match_df(df)
         ratings = self._calculate_future_ratings(match_df)
 
+        # Keep scaled columns for now - they're needed by _add_rating_features
         cols = [
             c
             for c in df.columns
@@ -324,7 +388,8 @@ class PlayerRatingGenerator(RatingGenerator):
             how="left",
         )
 
-        return self._add_rating_features(df_with_ratings)
+        result = self._add_rating_features(df_with_ratings)
+        return self._remove_internal_scaled_columns(result)
 
     def _calculate_ratings(self, match_df: pl.DataFrame) -> pl.DataFrame:
         cn = self.column_names
@@ -378,9 +443,9 @@ class PlayerRatingGenerator(RatingGenerator):
             team1_off_rating, team1_def_rating = self._team_off_def_rating_from_collection(c1)
             team2_off_rating, team2_def_rating = self._team_off_def_rating_from_collection(c2)
 
-            player_updates: list[tuple[str, str, float, float, float, float, float, float, int]] = (
-                []
-            )
+            player_updates: list[
+                tuple[str, str, float, float, float, float, float, float, int, str | None]
+            ] = []
 
             for pre_player in c1.pre_match_player_ratings:
                 pid = pre_player.id
@@ -456,6 +521,7 @@ class PlayerRatingGenerator(RatingGenerator):
                         float(off_change),
                         float(def_change),
                         day_number,
+                        pre_player.league,
                     )
                 )
 
@@ -533,6 +599,7 @@ class PlayerRatingGenerator(RatingGenerator):
                         float(off_change),
                         float(def_change),
                         day_number,
+                        pre_player.league,
                     )
                 )
 
@@ -547,6 +614,7 @@ class PlayerRatingGenerator(RatingGenerator):
                 _off_change,
                 _def_change,
                 _dn,
+                _league,
             ) in player_updates:
                 out[cn.player_id].append(pid)
                 out[cn.match_id].append(match_id)
@@ -563,15 +631,18 @@ class PlayerRatingGenerator(RatingGenerator):
             for (
                 pid,
                 team_id,
-                _off_pre,
+                off_pre,
                 _def_pre,
                 _pred_off,
                 _pred_def,
                 off_change,
                 def_change,
                 dn,
+                league,
             ) in player_updates:
-                pending_team_updates.append((pid, team_id, off_change, def_change, dn))
+                pending_team_updates.append(
+                    (pid, team_id, off_pre, off_change, def_change, dn, league)
+                )
 
             if last_update_id is None:
                 last_update_id = update_id
@@ -581,9 +652,11 @@ class PlayerRatingGenerator(RatingGenerator):
 
         return pl.DataFrame(out, strict=False)
 
-    def _apply_player_updates(self, updates: list[tuple[str, str, float, float, int]]) -> None:
+    def _apply_player_updates(
+        self, updates: list[tuple[str, str, float, float, float, int, str | None]]
+    ) -> None:
 
-        for player_id, team_id, off_change, def_change, day_number in updates:
+        for player_id, team_id, pre_rating, off_change, def_change, day_number, league in updates:
             off_state = self._player_off_ratings[player_id]
             off_state.confidence_sum = self._calculate_post_match_confidence_sum(
                 entity_rating=off_state,
@@ -606,6 +679,19 @@ class PlayerRatingGenerator(RatingGenerator):
             def_state.last_match_day_number = int(day_number)
             def_state.most_recent_team_id = team_id
 
+            self.start_rating_generator.update_players_to_leagues(
+                PlayerRatingChange(
+                    id=player_id,
+                    day_number=day_number,
+                    league=league,
+                    participation_weight=1.0,
+                    predicted_performance=0.0,
+                    performance=0.0,
+                    pre_match_rating_value=pre_rating,
+                    rating_change_value=off_change,
+                )
+            )
+
     def _add_rating_features(self, df: pl.DataFrame) -> pl.DataFrame:
         cols_to_add = set((self._features_out or []) + (self.non_predictor_features_out or []))
 
@@ -618,6 +704,7 @@ class PlayerRatingGenerator(RatingGenerator):
             or self.OPP_RATING_PROJ_COL in cols_to_add
             or self.DIFF_PROJ_COL in cols_to_add
             or self.MEAN_PROJ_COL in cols_to_add
+            or self.PLAYER_DIFF_FROM_TEAM_PROJ_COL in cols_to_add
         ):
             df = add_team_rating_projected(
                 df=df,
@@ -673,6 +760,13 @@ class PlayerRatingGenerator(RatingGenerator):
                 )
             )
 
+        if self.PLAYER_DIFF_FROM_TEAM_PROJ_COL in cols_to_add:
+            df = df.with_columns(
+                (pl.col(self.PLAYER_OFF_RATING_COL) - pl.col(self.TEAM_OFF_RATING_PROJ_COL)).alias(
+                    self.PLAYER_DIFF_FROM_TEAM_PROJ_COL
+                )
+            )
+
         if (
             self.TEAM_RATING_COL in cols_to_add
             or self.OPP_RATING_COL in cols_to_add
@@ -752,9 +846,13 @@ class PlayerRatingGenerator(RatingGenerator):
 
         if cn.participation_weight and cn.participation_weight in df.columns:
             player_stat_cols.append(cn.participation_weight)
+        if _SCALED_PW in df.columns:
+            player_stat_cols.append(_SCALED_PW)
 
         if cn.projected_participation_weight and cn.projected_participation_weight in df.columns:
             player_stat_cols.append(cn.projected_participation_weight)
+        if _SCALED_PPW in df.columns:
+            player_stat_cols.append(_SCALED_PPW)
 
         if cn.position and cn.position in df.columns:
             player_stat_cols.append(cn.position)
@@ -810,14 +908,23 @@ class PlayerRatingGenerator(RatingGenerator):
             position = team_player.get(cn.position)
             player_league = team_player.get(cn.league, None)
 
-            participation_weight = (
-                team_player.get(cn.participation_weight, 1.0) if cn.participation_weight else 1.0
-            )
-            projected_participation_weight = (
-                team_player.get(cn.projected_participation_weight, participation_weight)
-                if cn.projected_participation_weight
-                else participation_weight
-            )
+            # Use scaled participation weight if available, otherwise use original
+            if _SCALED_PW in team_player:
+                participation_weight = team_player.get(_SCALED_PW, 1.0)
+            elif cn.participation_weight:
+                participation_weight = team_player.get(cn.participation_weight, 1.0)
+            else:
+                participation_weight = 1.0
+
+            # Use scaled projected participation weight if available, otherwise use original
+            if _SCALED_PPW in team_player:
+                projected_participation_weight = team_player.get(_SCALED_PPW, participation_weight)
+            elif cn.projected_participation_weight:
+                projected_participation_weight = team_player.get(
+                    cn.projected_participation_weight, participation_weight
+                )
+            else:
+                projected_participation_weight = participation_weight
             projected_participation_weights.append(projected_participation_weight)
 
             perf_val = (
@@ -1043,14 +1150,21 @@ class PlayerRatingGenerator(RatingGenerator):
                     position = tp.get(cn.position)
                     league = tp.get(cn.league, None)
 
-                    pw = (
-                        tp.get(cn.participation_weight, 1.0) if cn.participation_weight else 1.0
-                    )
-                    ppw = (
-                        tp.get(cn.projected_participation_weight, pw)
-                        if cn.projected_participation_weight
-                        else pw
-                    )
+                    # Use scaled participation weight if available, otherwise use original
+                    if _SCALED_PW in tp:
+                        pw = tp.get(_SCALED_PW, 1.0)
+                    elif cn.participation_weight:
+                        pw = tp.get(cn.participation_weight, 1.0)
+                    else:
+                        pw = 1.0
+
+                    # Use scaled projected participation weight if available, otherwise use original
+                    if _SCALED_PPW in tp:
+                        ppw = tp.get(_SCALED_PPW, pw)
+                    elif cn.projected_participation_weight:
+                        ppw = tp.get(cn.projected_participation_weight, pw)
+                    else:
+                        ppw = pw
                     proj_w.append(float(ppw))
 
                     mp = MatchPerformance(