spforge 0.8.18__py3-none-any.whl → 0.8.19__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-0.8.18.dist-info → spforge-0.8.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spforge
-Version: 0.8.18
+Version: 0.8.19
 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.19.dist-info}/RECORD

@@ -43,9 +43,9 @@ 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
@@ -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.19.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,7 +91,7 @@ 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
@@ -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.19.dist-info/METADATA,sha256=4q1uKNTzmI9bwRwMJQaM0N6SAaC1RDembf_Gfbm2-mw,20048
+spforge-0.8.19.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+spforge-0.8.19.dist-info/top_level.txt,sha256=6UW2M5a7WKOeaAi900qQmRKNj5-HZzE8-eUD9Y9LTq0,23
+spforge-0.8.19.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