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

spforge/hyperparameter_tuning/__init__.py

@@ -7,6 +7,7 @@ from spforge.hyperparameter_tuning._default_search_spaces import (
     get_default_search_space,
     get_default_student_t_search_space,
     get_default_team_rating_search_space,
+    get_full_player_rating_search_space,
 )
 from spforge.hyperparameter_tuning._tuner import (
     EstimatorHyperparameterTuner,
@@ -28,4 +29,5 @@ __all__ = [
     "get_default_team_rating_search_space",
     "get_default_student_t_search_space",
     "get_default_search_space",
+    "get_full_player_rating_search_space",
 ]

spforge/hyperparameter_tuning/_default_search_spaces.py

@@ -128,6 +128,7 @@ def get_default_player_rating_search_space() -> dict[str, ParamSpec]:
     Default search space for PlayerRatingGenerator.
 
     Focuses on core parameters that have the most impact on performance.
+    Excludes performance_predictor and team-based start rating params.
 
     Returns:
         Dictionary mapping parameter names to ParamSpec objects
@@ -163,10 +164,6 @@ def get_default_player_rating_search_space() -> dict[str, ParamSpec]:
         "use_off_def_split": ParamSpec(
             param_type="bool",
         ),
-        "performance_predictor": ParamSpec(
-            param_type="categorical",
-            choices=["difference", "mean", "ignore_opponent"],
-        ),
         "start_league_quantile": ParamSpec(
             param_type="float",
             low=0.05,
@@ -177,24 +174,46 @@ def get_default_player_rating_search_space() -> dict[str, ParamSpec]:
             low=40,
             high=500,
         ),
-        "start_team_rating_subtract": ParamSpec(
-            param_type="float",
-            low=0.0,
-            high=200.0,
-        ),
-        "start_team_weight": ParamSpec(
-            param_type="float",
-            low=0.0,
-            high=1.0,
-        ),
-        "start_min_match_count_team_rating": ParamSpec(
-            param_type="int",
-            low=1,
-            high=10,
-        ),
     }
 
 
+def get_full_player_rating_search_space() -> dict[str, ParamSpec]:
+    """
+    Full search space for PlayerRatingGenerator including all tunable parameters.
+
+    Includes performance_predictor and team-based start rating parameters.
+    Use this when you want to tune all parameters.
+
+    Returns:
+        Dictionary mapping parameter names to ParamSpec objects
+    """
+    base = get_default_player_rating_search_space()
+    base.update(
+        {
+            "performance_predictor": ParamSpec(
+                param_type="categorical",
+                choices=["difference", "mean", "ignore_opponent"],
+            ),
+            "start_team_rating_subtract": ParamSpec(
+                param_type="float",
+                low=0.0,
+                high=200.0,
+            ),
+            "start_team_weight": ParamSpec(
+                param_type="float",
+                low=0.0,
+                high=1.0,
+            ),
+            "start_min_match_count_team_rating": ParamSpec(
+                param_type="int",
+                low=1,
+                high=10,
+            ),
+        }
+    )
+    return base
+
+
 def get_default_team_rating_search_space() -> dict[str, ParamSpec]:
     """
     Default search space for TeamRatingGenerator.
@@ -235,10 +254,6 @@ def get_default_team_rating_search_space() -> dict[str, ParamSpec]:
         "use_off_def_split": ParamSpec(
             param_type="bool",
         ),
-        "performance_predictor": ParamSpec(
-            param_type="categorical",
-            choices=["difference", "mean", "ignore_opponent"],
-        ),
     }
 
 

spforge/hyperparameter_tuning/_tuner.py

@@ -91,6 +91,9 @@ class RatingHyperparameterTuner:
         scorer: BaseScorer,
         direction: Literal["minimize", "maximize"],
         param_search_space: dict[str, ParamSpec] | None = None,
+        param_ranges: dict[str, tuple[float | int, float | int]] | None = None,
+        exclude_params: list[str] | None = None,
+        fixed_params: dict[str, Any] | None = None,
         n_trials: int = 50,
         n_jobs: int = 1,
         storage: str | None = None,
@@ -109,6 +112,14 @@ class RatingHyperparameterTuner:
             scorer: Scorer for evaluation (must have score(df) -> float | dict)
             direction: "minimize" or "maximize"
             param_search_space: Custom search space (merges with defaults if provided)
+            param_ranges: Easy range override for float/int params. Maps param name to
+                (low, high) tuple. Preserves param_type and log scale from defaults.
+                Example: {"confidence_weight": (0.2, 1.0)}
+            exclude_params: List of param names to exclude from tuning entirely.
+                Example: ["performance_predictor", "use_off_def_split"]
+            fixed_params: Parameters to fix at specific values (not tuned).
+                These values are applied to the rating generator each trial.
+                Example: {"performance_predictor": "mean"}
             n_trials: Number of optimization trials
             n_jobs: Number of parallel jobs (1 = sequential)
             storage: Optuna storage URL (e.g., "sqlite:///optuna.db") for persistence
@@ -123,6 +134,9 @@ class RatingHyperparameterTuner:
         self.scorer = scorer
         self.direction = direction
         self.custom_search_space = param_search_space
+        self.param_ranges = param_ranges
+        self.exclude_params = exclude_params or []
+        self.fixed_params = fixed_params or {}
         self.n_trials = n_trials
         self.n_jobs = n_jobs
         self.storage = storage
@@ -196,6 +210,9 @@ class RatingHyperparameterTuner:
         try:
             copied_gen = copy.deepcopy(self.rating_generator)
 
+            for param_name, param_value in self.fixed_params.items():
+                setattr(copied_gen, param_name, param_value)
+
             trial_params = self._suggest_params(trial, search_space)
 
             for param_name, param_value in trial_params.items():
@@ -243,18 +260,54 @@ class RatingHyperparameterTuner:
         defaults: dict[str, ParamSpec],
     ) -> dict[str, ParamSpec]:
         """
-        Merge custom search space with defaults (custom takes precedence).
+        Merge custom search space with defaults.
+
+        Priority order (highest to lowest):
+        1. exclude_params - removes param entirely
+        2. fixed_params - removes from search (applied separately)
+        3. custom (param_search_space) - full ParamSpec override
+        4. param_ranges - updates only low/high bounds
+        5. defaults - base search space
 
         Args:
             custom: Custom search space (may be None)
             defaults: Default search space
 
         Returns:
-            Merged search space
+            Merged search space (excludes fixed_params, those are applied separately)
         """
         merged = defaults.copy()
+
+        if self.param_ranges:
+            for param_name, (low, high) in self.param_ranges.items():
+                if param_name not in merged:
+                    raise ValueError(
+                        f"param_ranges contains unknown parameter: '{param_name}'. "
+                        f"Available parameters: {list(merged.keys())}"
+                    )
+                existing = merged[param_name]
+                if existing.param_type not in ("float", "int"):
+                    raise ValueError(
+                        f"param_ranges can only override float/int parameters. "
+                        f"'{param_name}' is {existing.param_type}."
+                    )
+                merged[param_name] = ParamSpec(
+                    param_type=existing.param_type,
+                    low=low,
+                    high=high,
+                    log=existing.log,
+                    step=existing.step,
+                )
+
         if custom:
             merged.update(custom)
+
+        for param_name in self.exclude_params:
+            merged.pop(param_name, None)
+
+        for param_name in self.fixed_params:
+            merged.pop(param_name, None)
+
         return merged
 
     @staticmethod

spforge/ratings/_player_rating.py

@@ -484,26 +484,31 @@ class PlayerRatingGenerator(RatingGenerator):
                     ),
                 )
 
-                off_perf = float(pre_player.match_performance.performance_value)
-                def_perf = float(team1_def_perf)  # same for all players on team1 (derived)
-
-                if not self.use_off_def_split:
-                    pred_def = pred_off
-                    def_perf = off_perf
-
-                mult_off = self._applied_multiplier_off(off_state)
-                mult_def = self._applied_multiplier_def(def_state)
-
-                off_change = (
-                    (off_perf - float(pred_off))
-                    * mult_off
-                    * float(pre_player.match_performance.participation_weight)
-                )
-                def_change = (
-                    (def_perf - float(pred_def))
-                    * mult_def
-                    * float(pre_player.match_performance.participation_weight)
-                )
+                perf_value = pre_player.match_performance.performance_value
+                if perf_value is None:
+                    off_change = 0.0
+                    def_change = 0.0
+                else:
+                    off_perf = float(perf_value)
+                    def_perf = float(team1_def_perf)
+
+                    if not self.use_off_def_split:
+                        pred_def = pred_off
+                        def_perf = off_perf
+
+                    mult_off = self._applied_multiplier_off(off_state)
+                    mult_def = self._applied_multiplier_def(def_state)
+
+                    off_change = (
+                        (off_perf - float(pred_off))
+                        * mult_off
+                        * float(pre_player.match_performance.participation_weight)
+                    )
+                    def_change = (
+                        (def_perf - float(pred_def))
+                        * mult_def
+                        * float(pre_player.match_performance.participation_weight)
+                    )
 
                 if math.isnan(off_change) or math.isnan(def_change):
                     raise ValueError(
@@ -562,32 +567,37 @@ class PlayerRatingGenerator(RatingGenerator):
                     ),
                 )
 
-                off_perf = float(pre_player.match_performance.performance_value)
-                def_perf = float(team2_def_perf)
-
-                if not self.use_off_def_split:
-                    pred_def = pred_off
-                    def_perf = off_perf
-
-                mult_off = self._applied_multiplier_off(off_state)
-                mult_def = self._applied_multiplier_def(def_state)
-
-                off_change = (
-                    (off_perf - float(pred_off))
-                    * mult_off
-                    * float(pre_player.match_performance.participation_weight)
-                )
-                def_change = (
-                    (def_perf - float(pred_def))
-                    * mult_def
-                    * float(pre_player.match_performance.participation_weight)
-                )
-
-                if math.isnan(off_change) or math.isnan(def_change):
-                    raise ValueError(
-                        f"NaN player rating change for player_id={pid}, match_id={r[cn.match_id]}"
+                perf_value = pre_player.match_performance.performance_value
+                if perf_value is None:
+                    off_change = 0.0
+                    def_change = 0.0
+                else:
+                    off_perf = float(perf_value)
+                    def_perf = float(team2_def_perf)
+
+                    if not self.use_off_def_split:
+                        pred_def = pred_off
+                        def_perf = off_perf
+
+                    mult_off = self._applied_multiplier_off(off_state)
+                    mult_def = self._applied_multiplier_def(def_state)
+
+                    off_change = (
+                        (off_perf - float(pred_off))
+                        * mult_off
+                        * float(pre_player.match_performance.participation_weight)
+                    )
+                    def_change = (
+                        (def_perf - float(pred_def))
+                        * mult_def
+                        * float(pre_player.match_performance.participation_weight)
                     )
 
+                    if math.isnan(off_change) or math.isnan(def_change):
+                        raise ValueError(
+                            f"NaN player rating change for player_id={pid}, match_id={r[cn.match_id]}"
+                        )
+
                 player_updates.append(
                     (
                         pid,
@@ -933,7 +943,7 @@ class PlayerRatingGenerator(RatingGenerator):
                     self.performance_column in team_player
                     and team_player[self.performance_column] is not None
                 )
-                else 0.0
+                else None
             )
 
             mp = MatchPerformance(
@@ -1023,18 +1033,22 @@ class PlayerRatingGenerator(RatingGenerator):
 
     def _team_off_perf_from_collection(self, c: PreMatchPlayersCollection) -> float:
         # observed offense perf = weighted mean of player performance_value using participation_weight if present
+        # skip players with null performance
         cn = self.column_names
         if not c.pre_match_player_ratings:
             return 0.0
         wsum = 0.0
         psum = 0.0
         for pre in c.pre_match_player_ratings:
+            perf_val = pre.match_performance.performance_value
+            if perf_val is None:
+                continue
             w = (
                 float(pre.match_performance.participation_weight)
                 if cn.participation_weight
                 else 1.0
             )
-            psum += float(pre.match_performance.performance_value) * w
+            psum += float(perf_val) * w
             wsum += w
         return psum / wsum if wsum else 0.0
 
@@ -1101,13 +1115,13 @@ class PlayerRatingGenerator(RatingGenerator):
             self.PLAYER_PRED_PERF_COL: [],
         }
 
-        def get_perf_value(team_player: dict) -> float:
+        def get_perf_value(team_player: dict) -> float | None:
             if (
                 self.performance_column in team_player
                 and team_player[self.performance_column] is not None
             ):
                 return float(team_player[self.performance_column])
-            return 0.0
+            return None
 
         def ensure_new_player(
             pid: str,
@@ -1187,8 +1201,9 @@ class PlayerRatingGenerator(RatingGenerator):
                     )
                     off_vals.append(float(local_off[pid].rating_value))
 
-                    psum += float(mp.performance_value) * float(pw)
-                    wsum += float(pw)
+                    if mp.performance_value is not None:
+                        psum += float(mp.performance_value) * float(pw)
+                        wsum += float(pw)
 
                 team_off_perf = psum / wsum if wsum else 0.0
                 return pre_list, player_ids, off_vals, proj_w, team_off_perf

{spforge-0.8.18.dist-info → spforge-0.8.20.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spforge
-Version: 0.8.18
+Version: 0.8.20
 Summary: A flexible framework for generating features, ratings, and building machine learning or other models for training and inference on sports data.
 Author-email: Mathias Holmstrøm <mathiasholmstom@gmail.com>
 License: See LICENSE file

{spforge-0.8.18.dist-info → spforge-0.8.20.dist-info}/RECORD

@@ -43,15 +43,15 @@ spforge/feature_generator/_rolling_mean_binary.py,sha256=lmODy-o9Dd9pb8IlA7g4UyA
 spforge/feature_generator/_rolling_mean_days.py,sha256=EZQmFmYVQB-JjZV5k8bOWnaTxNpPDCZAjdfdhiiG4r4,8415
 spforge/feature_generator/_rolling_window.py,sha256=HT8LezsRIPNAlMEoP9oTPW2bKFu55ZSRnQZGST7fncw,8836
 spforge/feature_generator/_utils.py,sha256=KDn33ia1OYJTK8THFpvc_uRiH_Bl3fImGqqbfzs0YA4,9654
-spforge/hyperparameter_tuning/__init__.py,sha256=N2sKG4SvG41hlsFT2kx_DQYMmXsQr-8031Tu_rxlxyY,1015
-spforge/hyperparameter_tuning/_default_search_spaces.py,sha256=Sm5IrHAW0-vRC8jqCPX0pDi_C-W3L_MoEKGA8bx1Zbc,7546
-spforge/hyperparameter_tuning/_tuner.py,sha256=uovhGqhe8-fdhi79aErUmE2h5NCycFQEIRv5WCjpC7E,16732
+spforge/hyperparameter_tuning/__init__.py,sha256=Vcl8rVlJ7M708iPgqe4XxpZWgJKGux0Y5HgMCymRsHg,1099
+spforge/hyperparameter_tuning/_default_search_spaces.py,sha256=SjwXLpvYIu_JY8uPRHeL5Kgp1aa0slWDz8qsKDaohWQ,8020
+spforge/hyperparameter_tuning/_tuner.py,sha256=M79q3saM6r0UZJsRUUgfdDr-3Qii-F2-wuSAZLFtZDo,19246
 spforge/performance_transformers/__init__.py,sha256=U6d7_kltbUMLYCGBk4QAFVPJTxXD3etD9qUftV-O3q4,422
 spforge/performance_transformers/_performance_manager.py,sha256=WmjmlMEnq7y75MiI_s9Y-9eMXIyhPTUKrwsXRtgYp0k,9620
 spforge/performance_transformers/_performances_transformers.py,sha256=0lxuWjAfWBRXRgQsNJHjw3P-nlTtHBu4_bOVdoy7hq4,15536
 spforge/ratings/__init__.py,sha256=OZVH2Lo6END3n1X8qi4QcyAPlThIwAYwVKCiIuOQSQU,576
 spforge/ratings/_base.py,sha256=dRMkIGj5-2zKddygaEA4g16WCyXon7v8Xa1ymm7IuoM,14335
-spforge/ratings/_player_rating.py,sha256=JSTXdaRw_b8ZoZxgmMnZrYG7gPg8GKawqalLd16SK1M,56066
+spforge/ratings/_player_rating.py,sha256=TI0mEGZKEkf86TzOcP689C1jClYrXncjOnGwtsltMrk,56734
 spforge/ratings/_team_rating.py,sha256=T0kFiv3ykYSrVGGsVRa8ZxLB0WMnagxqdFDzl9yZ_9g,24813
 spforge/ratings/enums.py,sha256=s7z_RcZS6Nlgfa_6tasO8_IABZJwywexe7sep9DJBgo,1739
 spforge/ratings/league_identifier.py,sha256=_KDUKOwoNU6RNFKE5jju4eYFGVNGBdJsv5mhNvMakfc,6019
@@ -71,7 +71,7 @@ spforge/transformers/_other_transformer.py,sha256=w2a7Wnki3vJe4GAkSa4kealw0GILIo
 spforge/transformers/_predictor.py,sha256=2sE6gfVrilXzPVcBurSrtqHw33v2ljygQcEYXt9LhZc,3119
 spforge/transformers/_simple_transformer.py,sha256=zGUFNQYMeoDSa2CoQejQNiNmKCBN5amWTvyOchiUHj0,5660
 spforge/transformers/_team_ratio_predictor.py,sha256=g8_bR53Yyv0iNCtol1O9bgJSeZcIco_AfbQuUxQJkeY,6884
-spforge-0.8.18.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+spforge-0.8.20.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
 tests/test_autopipeline.py,sha256=7cNAn-nmGolfyfk3THh9IKcHZfRA-pLYC_xAyMg-No4,26863
 tests/test_autopipeline_context.py,sha256=IuRUY4IA6uMObvbl2pXSaXO2_tl3qX6wEbTZY0dkTMI,1240
 tests/test_feature_generator_pipeline.py,sha256=CK0zVL8PfTncy3RmG9i-YpgwjOIV7yJhV7Q44tbetI8,19020
@@ -81,7 +81,7 @@ tests/end_to_end/test_estimator_hyperparameter_tuning.py,sha256=fZCJ9rrED2vT68B9
 tests/end_to_end/test_league_start_rating_optimizer.py,sha256=Mmct2ixp4c6L7PGym8wZc7E-Csozryt1g4_o6OCc1uI,3141
 tests/end_to_end/test_lol_player_kills.py,sha256=RJSYUbPrZ-RzSxGggj03yN0JKYeTB1JghVGYFMYia3Y,11891
 tests/end_to_end/test_nba_player_points.py,sha256=kyzjo7QIcvpteps29Wix6IS_eJG9d1gHLeWtIHpkWMs,9066
-tests/end_to_end/test_nba_player_ratings_hyperparameter_tuning.py,sha256=LXRkI_6Ho2kzJVbNAM17QFhx_MP9WdDJXCO9dWgJGNA,6491
+tests/end_to_end/test_nba_player_ratings_hyperparameter_tuning.py,sha256=0lI4Xtg3V-zmo6prgzdNG80yy7JjvFVO-J_OU0pljyc,6346
 tests/end_to_end/test_nba_prediction_consistency.py,sha256=o3DckJasx_I1ed6MhMYZUo2WSDvQ_p3HtJa9DCWTIYU,9857
 tests/estimator/test_sklearn_estimator.py,sha256=tVfOP9Wx-tV1b6DcHbGxQHZQzNPA0Iobq8jTcUrk59U,48668
 tests/feature_generator/test_lag.py,sha256=5Ffrv0V9cwkbkzRMPBe3_c_YNW-W2al-XH_acQIvdeg,19531
@@ -91,10 +91,10 @@ tests/feature_generator/test_rolling_mean_binary.py,sha256=KuIavJ37Pt8icAb50B23l
 tests/feature_generator/test_rolling_mean_days.py,sha256=EyOvdJDnmgPfe13uQBOkwo7fAteBQx-tnyuGM4ng2T8,18884
 tests/feature_generator/test_rolling_window.py,sha256=YBJo36OK3ILYeXrH06ylXqviUcCaGYaVQaK5RJzwM7Y,23239
 tests/hyperparameter_tuning/test_estimator_tuner.py,sha256=iewME41d6LR2aQ0OtohGFtN_ocJUwTeqvs6L0QDmfG4,4413
-tests/hyperparameter_tuning/test_rating_tuner.py,sha256=PyCFP3KPc4Iy9E_X9stCVxra14uMgC1tuRwuQ30rO_o,13195
+tests/hyperparameter_tuning/test_rating_tuner.py,sha256=usjC2ioO_yWRjjNAlRTyMVYheOrCi0kKocmHQHdTmpM,18699
 tests/performance_transformers/test_performance_manager.py,sha256=gjuuV_hb27kCo_kUecPKG3Cbot2Gqis1W3kw2A4ovS4,10690
 tests/performance_transformers/test_performances_transformers.py,sha256=A-tGiCx7kXrj1cVj03Bc7prOeZ1_Ryz8YFx9uj3eK6w,11064
-tests/ratings/test_player_rating_generator.py,sha256=SKLaBQBsHYslc2Nia2AxZ8A9Cy16MbZAWjLyOjvcMnA,64094
+tests/ratings/test_player_rating_generator.py,sha256=Bb_KR61-DbRUSiZDyfdSvZpMrJ0QDGHxGMFBNTq3Igw,70813
 tests/ratings/test_player_rating_no_mutation.py,sha256=GzO3Hl__5K68DS3uRLefwnbcTJOvBM7cZqww4M21UZM,8493
 tests/ratings/test_ratings_property.py,sha256=ckyfGILXa4tfQvsgyXEzBDNr2DUmHwFRV13N60w66iE,6561
 tests/ratings/test_team_rating_generator.py,sha256=cDnf1zHiYC7pkgydE3MYr8wSTJIq-bPfSqhIRI_4Tic,95357
@@ -107,7 +107,7 @@ tests/transformers/test_other_transformer.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRk
 tests/transformers/test_predictor_transformer.py,sha256=N1aBYLjN3ldpYZLwjih_gTFYSMitrZu-PNK78W6RHaQ,6877
 tests/transformers/test_simple_transformer.py,sha256=wWR0qjLb_uS4HXrJgGdiqugOY1X7kwd1_OPS02IT2b8,4676
 tests/transformers/test_team_ratio_predictor.py,sha256=fOUP_JvNJi-3kom3ZOs1EdG0I6Z8hpLpYKNHu1eWtOw,8562
-spforge-0.8.18.dist-info/METADATA,sha256=54l0UTrew2ot0_4k22hLKL-oXbQ4hlA1_KAXIqf_umw,20048
-spforge-0.8.18.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-spforge-0.8.18.dist-info/top_level.txt,sha256=6UW2M5a7WKOeaAi900qQmRKNj5-HZzE8-eUD9Y9LTq0,23
-spforge-0.8.18.dist-info/RECORD,,
+spforge-0.8.20.dist-info/METADATA,sha256=27uVILTzrjbdXCa91c0X4d9Fbfrw1bIOyuHFy45Nejw,20048
+spforge-0.8.20.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+spforge-0.8.20.dist-info/top_level.txt,sha256=6UW2M5a7WKOeaAi900qQmRKNj5-HZzE8-eUD9Y9LTq0,23
+spforge-0.8.20.dist-info/RECORD,,

tests/end_to_end/test_nba_player_ratings_hyperparameter_tuning.py

@@ -96,12 +96,8 @@ def test_nba_player_ratings_hyperparameter_tuning__workflow_completes(
         "confidence_value_denom",
         "confidence_max_sum",
         "use_off_def_split",
-        "performance_predictor",
-        "start_team_weight",
         "start_league_quantile",
         "start_min_count_for_percentiles",
-        "start_min_match_count_team_rating",
-        "start_team_rating_subtract",
     }
     assert set(result.best_params.keys()) == expected_params
 

tests/hyperparameter_tuning/test_rating_tuner.py

@@ -454,3 +454,160 @@ def test_param_spec__categorical_requires_choices():
 
     with pytest.raises(ValueError, match="requires choices"):
         spec.suggest(trial, "test_param")
+
+
+def test_param_ranges__overrides_bounds(
+    player_rating_generator, cross_validator, scorer, sample_player_df_pd
+):
+    """Test that param_ranges overrides low/high bounds while preserving param_type."""
+    tuner = RatingHyperparameterTuner(
+        rating_generator=player_rating_generator,
+        cross_validator=cross_validator,
+        scorer=scorer,
+        direction="minimize",
+        param_ranges={
+            "confidence_weight": (0.2, 0.3),
+        },
+        n_trials=3,
+        show_progress_bar=False,
+    )
+
+    result = tuner.optimize(sample_player_df_pd)
+
+    assert "confidence_weight" in result.best_params
+    assert 0.2 <= result.best_params["confidence_weight"] <= 0.3
+
+
+def test_exclude_params__removes_from_search(
+    player_rating_generator, cross_validator, scorer, sample_player_df_pd
+):
+    """Test that exclude_params removes parameters from search space."""
+    tuner = RatingHyperparameterTuner(
+        rating_generator=player_rating_generator,
+        cross_validator=cross_validator,
+        scorer=scorer,
+        direction="minimize",
+        exclude_params=["use_off_def_split", "confidence_weight"],
+        n_trials=3,
+        show_progress_bar=False,
+    )
+
+    result = tuner.optimize(sample_player_df_pd)
+
+    assert "use_off_def_split" not in result.best_params
+    assert "confidence_weight" not in result.best_params
+    assert "rating_change_multiplier_offense" in result.best_params
+
+
+def test_fixed_params__applies_values_without_tuning(
+    player_rating_generator, cross_validator, scorer, sample_player_df_pd
+):
+    """Test that fixed_params sets values without including in search space."""
+    tuner = RatingHyperparameterTuner(
+        rating_generator=player_rating_generator,
+        cross_validator=cross_validator,
+        scorer=scorer,
+        direction="minimize",
+        fixed_params={"use_off_def_split": False},
+        n_trials=3,
+        show_progress_bar=False,
+    )
+
+    result = tuner.optimize(sample_player_df_pd)
+
+    assert "use_off_def_split" not in result.best_params
+
+
+def test_param_ranges__unknown_param_raises_error(
+    player_rating_generator, cross_validator, scorer, sample_player_df_pd
+):
+    """Test that param_ranges with unknown param raises ValueError."""
+    tuner = RatingHyperparameterTuner(
+        rating_generator=player_rating_generator,
+        cross_validator=cross_validator,
+        scorer=scorer,
+        direction="minimize",
+        param_ranges={"nonexistent_param": (0.0, 1.0)},
+        n_trials=3,
+        show_progress_bar=False,
+    )
+
+    with pytest.raises(ValueError, match="unknown parameter"):
+        tuner.optimize(sample_player_df_pd)
+
+
+def test_param_ranges__non_numeric_param_raises_error(
+    player_rating_generator, cross_validator, scorer, sample_player_df_pd
+):
+    """Test that param_ranges on non-float/int param raises ValueError."""
+    tuner = RatingHyperparameterTuner(
+        rating_generator=player_rating_generator,
+        cross_validator=cross_validator,
+        scorer=scorer,
+        direction="minimize",
+        param_ranges={"use_off_def_split": (0, 1)},
+        n_trials=3,
+        show_progress_bar=False,
+    )
+
+    with pytest.raises(ValueError, match="can only override float/int"):
+        tuner.optimize(sample_player_df_pd)
+
+
+def test_combined_api__param_ranges_exclude_fixed(
+    player_rating_generator, cross_validator, scorer, sample_player_df_pd
+):
+    """Test using param_ranges, exclude_params, and fixed_params together."""
+    tuner = RatingHyperparameterTuner(
+        rating_generator=player_rating_generator,
+        cross_validator=cross_validator,
+        scorer=scorer,
+        direction="minimize",
+        param_ranges={
+            "confidence_weight": (0.2, 1.0),
+            "rating_change_multiplier_offense": (10.0, 150.0),
+        },
+        exclude_params=["start_league_quantile"],
+        fixed_params={"use_off_def_split": False},
+        n_trials=3,
+        show_progress_bar=False,
+    )
+
+    result = tuner.optimize(sample_player_df_pd)
+
+    assert 0.2 <= result.best_params["confidence_weight"] <= 1.0
+    assert 10.0 <= result.best_params["rating_change_multiplier_offense"] <= 150.0
+    assert "start_league_quantile" not in result.best_params
+    assert "use_off_def_split" not in result.best_params
+
+
+def test_default_search_space__excludes_performance_predictor_and_team_start(
+    player_rating_generator,
+):
+    """Test that performance_predictor and team start params are not in default search space."""
+    from spforge.hyperparameter_tuning._default_search_spaces import (
+        get_default_search_space,
+    )
+
+    defaults = get_default_search_space(player_rating_generator)
+
+    assert "performance_predictor" not in defaults
+    assert "start_team_rating_subtract" not in defaults
+    assert "start_team_weight" not in defaults
+    assert "start_min_match_count_team_rating" not in defaults
+
+
+def test_full_player_rating_search_space__includes_all_params():
+    """Test that full search space includes performance_predictor and team start params."""
+    from spforge.hyperparameter_tuning._default_search_spaces import (
+        get_full_player_rating_search_space,
+    )
+
+    full = get_full_player_rating_search_space()
+
+    assert "performance_predictor" in full
+    assert "start_team_rating_subtract" in full
+    assert "start_team_weight" in full
+    assert "start_min_match_count_team_rating" in full
+    assert "rating_change_multiplier_offense" in full
+    assert "confidence_weight" in full

tests/ratings/test_player_rating_generator.py

@@ -722,6 +722,198 @@ def test_fit_transform_null_performance_handling(base_cn, sample_df):
     assert len(res) == 4
 
 
+def test_fit_transform_null_performance__no_rating_change(base_cn):
+    """Players with null performance should have zero rating change, not be treated as 0.0 perf."""
+    # Match 1: Both players have performance (P1=0.6, P2=0.4)
+    # Match 2: P1 has null performance, P2 has 0.6
+    # Match 3: Both players have performance again
+    df = pl.DataFrame(
+        {
+            "pid": ["P1", "P2", "P1", "P2", "P1", "P2"],
+            "tid": ["T1", "T2", "T1", "T2", "T1", "T2"],
+            "mid": ["M1", "M1", "M2", "M2", "M3", "M3"],
+            "dt": [
+                "2024-01-01",
+                "2024-01-01",
+                "2024-01-02",
+                "2024-01-02",
+                "2024-01-03",
+                "2024-01-03",
+            ],
+            "perf": [0.6, 0.4, None, 0.6, 0.6, 0.4],  # P1 has null in M2
+            "pw": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
+        }
+    )
+
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    result = gen.fit_transform(df)
+
+    # Get P1's pre-match rating for M2 (after M1) and M3 (after M2 with null perf)
+    p1_rating_before_m2 = result.filter(
+        (pl.col("pid") == "P1") & (pl.col("mid") == "M2")
+    )["player_off_rating_perf"][0]
+    p1_rating_before_m3 = result.filter(
+        (pl.col("pid") == "P1") & (pl.col("mid") == "M3")
+    )["player_off_rating_perf"][0]
+
+    # Key assertion: P1's rating before M3 should equal rating before M2
+    # because null performance in M2 means NO rating change
+    assert p1_rating_before_m3 == p1_rating_before_m2, (
+        f"P1's rating changed after null performance game! "
+        f"Before M2={p1_rating_before_m2}, Before M3={p1_rating_before_m3}"
+    )
+
+    # Also verify null is not treated as 0.0 by comparing with explicit 0.0
+    df_with_zero = df.with_columns(
+        pl.when((pl.col("pid") == "P1") & (pl.col("mid") == "M2"))
+        .then(0.0)
+        .otherwise(pl.col("perf"))
+        .alias("perf")
+    )
+
+    gen_zero = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    result_zero = gen_zero.fit_transform(df_with_zero)
+
+    p1_rating_before_m3_with_zero = result_zero.filter(
+        (pl.col("pid") == "P1") & (pl.col("mid") == "M3")
+    )["player_off_rating_perf"][0]
+
+    # With 0.0 perf, rating should drop (different from null)
+    assert p1_rating_before_m3 > p1_rating_before_m3_with_zero, (
+        f"Null performance is being treated as 0.0! "
+        f"Rating with null={p1_rating_before_m3}, rating with 0.0={p1_rating_before_m3_with_zero}"
+    )
+
+
+def test_fit_transform_null_performance__still_outputs_player_rating(base_cn):
+    """Players with null performance should still have their pre-match rating in output."""
+    df = pl.DataFrame(
+        {
+            "pid": ["P1", "P2", "P3", "P4"],
+            "tid": ["T1", "T1", "T2", "T2"],
+            "mid": ["M1", "M1", "M1", "M1"],
+            "dt": ["2024-01-01"] * 4,
+            "perf": [0.6, None, 0.4, 0.5],  # P2 has null performance
+            "pw": [1.0, 1.0, 1.0, 1.0],
+        }
+    )
+
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    result = gen.fit_transform(df)
+
+    # P2 should still be in output with their pre-match rating
+    assert len(result) == 4
+    p2_row = result.filter(pl.col("pid") == "P2")
+    assert len(p2_row) == 1
+    assert "player_off_rating_perf" in result.columns
+    # P2's rating should be the start rating (1000.0) since they're new and had no update
+    assert p2_row["player_off_rating_perf"][0] == 1000.0
+
+
+def test_transform_null_performance__no_rating_change(base_cn):
+    """In transform (historical), null performance should result in no rating change."""
+    # First fit with some data
+    fit_df = pl.DataFrame(
+        {
+            "pid": ["P1", "P2"],
+            "tid": ["T1", "T2"],
+            "mid": ["M1", "M1"],
+            "dt": ["2024-01-01", "2024-01-01"],
+            "perf": [0.6, 0.4],
+            "pw": [1.0, 1.0],
+        }
+    )
+
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    gen.fit_transform(fit_df)
+
+    p1_rating_before = gen._player_off_ratings["P1"].rating_value
+
+    # Now transform with P1 having null performance
+    transform_df = pl.DataFrame(
+        {
+            "pid": ["P1", "P2"],
+            "tid": ["T1", "T2"],
+            "mid": ["M2", "M2"],
+            "dt": ["2024-01-02", "2024-01-02"],
+            "perf": [None, 0.6],  # P1 has null
+            "pw": [1.0, 1.0],
+        }
+    )
+
+    gen.transform(transform_df)
+
+    p1_rating_after = gen._player_off_ratings["P1"].rating_value
+
+    # P1's rating should not change significantly (only confidence decay, not performance-based)
+    # Since null perf means no rating change from performance
+    assert abs(p1_rating_after - p1_rating_before) < 0.01, (
+        f"P1's rating changed significantly with null performance: "
+        f"before={p1_rating_before}, after={p1_rating_after}"
+    )
+
+
+def test_future_transform_null_performance__outputs_projections(base_cn):
+    """In future_transform, null performance should still output rating projections."""
+    # First fit with some data
+    fit_df = pl.DataFrame(
+        {
+            "pid": ["P1", "P2"],
+            "tid": ["T1", "T2"],
+            "mid": ["M1", "M1"],
+            "dt": ["2024-01-01", "2024-01-01"],
+            "perf": [0.6, 0.4],
+            "pw": [1.0, 1.0],
+        }
+    )
+
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    gen.fit_transform(fit_df)
+
+    p1_rating_before = gen._player_off_ratings["P1"].rating_value
+
+    # Future transform (no performance needed, but if null it shouldn't affect anything)
+    future_df = pl.DataFrame(
+        {
+            "pid": ["P1", "P2"],
+            "tid": ["T1", "T2"],
+            "mid": ["M2", "M2"],
+            "dt": ["2024-01-02", "2024-01-02"],
+            "pw": [1.0, 1.0],
+            # No perf column - this is a future match
+        }
+    )
+
+    result = gen.future_transform(future_df)
+
+    # Should output projections for all players
+    assert len(result) == 2
+    assert "player_off_rating_perf" in result.columns
+
+    # Ratings should NOT be updated (future_transform doesn't update state)
+    assert gen._player_off_ratings["P1"].rating_value == p1_rating_before
+
+
 # --- transform & future_transform Tests ---