spforge 0.8.9__tar.gz → 0.8.11__tar.gz

{spforge-0.8.9/spforge.egg-info → spforge-0.8.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spforge
-Version: 0.8.9
+Version: 0.8.11
 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.9 → spforge-0.8.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spforge"
-version = "0.8.9"
+version = "0.8.11"
 description = "A flexible framework for generating features, ratings, and building machine learning or other models for training and inference on sports data."
 readme = "README.md"
 requires-python = ">=3.11"

{spforge-0.8.9 → spforge-0.8.11}/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
@@ -33,6 +34,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):
@@ -81,6 +84,7 @@ class PlayerRatingGenerator(RatingGenerator):
         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__(
@@ -164,6 +168,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
 
@@ -189,9 +194,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
@@ -240,6 +275,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:
@@ -254,7 +290,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 (
@@ -267,16 +303,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
@@ -296,13 +354,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
@@ -327,7 +387,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
@@ -763,9 +824,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)
@@ -821,14 +886,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 = (
@@ -1054,14 +1128,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(

{spforge-0.8.9 → spforge-0.8.11}/spforge/ratings/utils.py

@@ -2,6 +2,10 @@ import polars as pl
 
 from spforge.data_structures import ColumnNames
 
+# Internal column names for scaled participation weights
+_SCALED_PW = "__scaled_participation_weight__"
+_SCALED_PPW = "__scaled_projected_participation_weight__"
+
 
 def add_team_rating(
     df: pl.DataFrame,
@@ -46,11 +50,14 @@ def add_team_rating_projected(
     tid = column_names.team_id
     ppw = column_names.projected_participation_weight
 
-    if ppw:
+    # Use scaled column if available (clipped to [0, 1]), otherwise raw column
+    weight_col = _SCALED_PPW if _SCALED_PPW in df.columns else ppw
+
+    if weight_col and weight_col in df.columns:
         return df.with_columns(
             (
-                (pl.col(ppw) * pl.col(player_rating_col)).sum().over([mid, tid])
-                / pl.col(ppw).sum().over([mid, tid])
+                (pl.col(weight_col) * pl.col(player_rating_col)).sum().over([mid, tid])
+                / pl.col(weight_col).sum().over([mid, tid])
             ).alias(team_rating_out)
         )
 
@@ -118,11 +125,14 @@ def add_rating_mean_projected(
     mid = column_names.match_id
     ppw = column_names.projected_participation_weight
 
-    if ppw:
+    # Use scaled column if available (clipped to [0, 1]), otherwise raw column
+    weight_col = _SCALED_PPW if _SCALED_PPW in df.columns else ppw
+
+    if weight_col and weight_col in df.columns:
         return df.with_columns(
             (
-                (pl.col(ppw) * pl.col(player_rating_col)).sum().over(mid)
-                / pl.col(ppw).sum().over(mid)
+                (pl.col(weight_col) * pl.col(player_rating_col)).sum().over(mid)
+                / pl.col(weight_col).sum().over(mid)
             ).alias(rating_mean_out)
         )
 

{spforge-0.8.9 → spforge-0.8.11/spforge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spforge
-Version: 0.8.9
+Version: 0.8.11
 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.9 → spforge-0.8.11}/spforge.egg-info/SOURCES.txt

@@ -103,8 +103,10 @@ tests/hyperparameter_tuning/test_rating_tuner.py
 tests/performance_transformers/test_performance_manager.py
 tests/performance_transformers/test_performances_transformers.py
 tests/ratings/test_player_rating_generator.py
+tests/ratings/test_player_rating_no_mutation.py
 tests/ratings/test_ratings_property.py
 tests/ratings/test_team_rating_generator.py
+tests/ratings/test_utils_scaled_weights.py
 tests/scorer/test_score.py
 tests/scorer/test_score_aggregation_granularity.py
 tests/transformers/test_estimator_transformer_context.py

{spforge-0.8.9 → spforge-0.8.11}/tests/ratings/test_player_rating_generator.py

@@ -551,6 +551,63 @@ def test_fit_transform_scales_participation_weight_by_fit_quantile(base_cn):
     assert p1_change / p2_change == pytest.approx(expected_ratio, rel=1e-6)
 
 
+def test_fit_transform_auto_scales_participation_weight_when_out_of_bounds(base_cn):
+    """Automatically enable scaling when participation weights exceed [0, 1]."""
+    df = pl.DataFrame(
+        {
+            "pid": ["P1", "P2", "O1", "O2"],
+            "tid": ["T1", "T1", "T2", "T2"],
+            "mid": ["M1", "M1", "M1", "M1"],
+            "dt": ["2024-01-01"] * 4,
+            "perf": [0.9, 0.9, 0.1, 0.1],
+            "pw": [10.0, 20.0, 10.0, 10.0],
+        }
+    )
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        auto_scale_performance=True,
+        start_harcoded_start_rating=1000.0,
+    )
+    gen.fit_transform(df)
+
+    start_rating = 1000.0
+    p1_change = gen._player_off_ratings["P1"].rating_value - start_rating
+    p2_change = gen._player_off_ratings["P2"].rating_value - start_rating
+
+    q = df["pw"].quantile(0.99, "linear")
+    expected_ratio = min(1.0, 10.0 / q) / min(1.0, 20.0 / q)
+
+    assert gen.scale_participation_weights is True
+    assert p1_change / p2_change == pytest.approx(expected_ratio, rel=1e-6)
+
+
+def test_fit_transform_auto_scale_logs_warning_when_out_of_bounds(base_cn, caplog):
+    """Auto-scaling should emit a warning when participation weights exceed [0, 1]."""
+    df = pl.DataFrame(
+        {
+            "pid": ["P1", "P2", "O1", "O2"],
+            "tid": ["T1", "T1", "T2", "T2"],
+            "mid": ["M1", "M1", "M1", "M1"],
+            "dt": ["2024-01-01"] * 4,
+            "perf": [0.9, 0.9, 0.1, 0.1],
+            "pw": [10.0, 20.0, 10.0, 10.0],
+        }
+    )
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        auto_scale_performance=True,
+        start_harcoded_start_rating=1000.0,
+    )
+    with caplog.at_level("WARNING"):
+        gen.fit_transform(df)
+
+    assert any(
+        "Auto-scaling participation weights" in record.message for record in caplog.records
+    )
+
+
 def test_future_transform_scales_projected_participation_weight_by_fit_quantile():
     """Future projected participation weights should scale with fit quantile and be clipped."""
     cn = ColumnNames(

spforge-0.8.11/tests/ratings/test_player_rating_no_mutation.py

@@ -0,0 +1,214 @@
+"""Tests to ensure PlayerRatingGenerator does not mutate input columns."""
+
+import polars as pl
+import pytest
+
+from spforge import ColumnNames
+from spforge.ratings import PlayerRatingGenerator, RatingKnownFeatures
+
+
+@pytest.fixture
+def cn_with_projected():
+    """ColumnNames with both participation_weight and projected_participation_weight."""
+    return ColumnNames(
+        player_id="pid",
+        team_id="tid",
+        match_id="mid",
+        start_date="dt",
+        update_match_id="mid",
+        participation_weight="minutes",
+        projected_participation_weight="minutes_prediction",
+    )
+
+
+@pytest.fixture
+def fit_df():
+    """Training data with minutes > 1 (will trigger auto-scaling)."""
+    return 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, 0.4, 0.7, 0.3],
+            "minutes": [30.0, 25.0, 32.0, 28.0],
+            "minutes_prediction": [28.0, 24.0, 30.0, 26.0],
+        }
+    )
+
+
+@pytest.fixture
+def future_df():
+    """Future prediction data with minutes > 1 (will trigger auto-scaling)."""
+    return pl.DataFrame(
+        {
+            "pid": ["P1", "P2", "P3", "P4"],
+            "tid": ["T1", "T1", "T2", "T2"],
+            "mid": ["M2", "M2", "M2", "M2"],
+            "dt": ["2024-01-02"] * 4,
+            "minutes": [30.0, 25.0, 32.0, 28.0],
+            "minutes_prediction": [28.0, 24.0, 30.0, 26.0],
+        }
+    )
+
+
+def test_fit_transform_does_not_mutate_participation_weight(cn_with_projected, fit_df):
+    """fit_transform should not modify the participation_weight column values."""
+    # Join result with original to compare values by player_id
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=cn_with_projected,
+        auto_scale_performance=True,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    result = gen.fit_transform(fit_df)
+
+    # Check that each player's minutes value is preserved
+    original_by_player = dict(zip(fit_df["pid"].to_list(), fit_df["minutes"].to_list()))
+    result_by_player = dict(zip(result["pid"].to_list(), result["minutes"].to_list()))
+
+    for pid, original_val in original_by_player.items():
+        result_val = result_by_player[pid]
+        assert result_val == original_val, (
+            f"participation_weight for player {pid} was mutated. "
+            f"Expected {original_val}, got {result_val}"
+        )
+
+
+def test_fit_transform_does_not_mutate_projected_participation_weight(cn_with_projected, fit_df):
+    """fit_transform should not modify the projected_participation_weight column values."""
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=cn_with_projected,
+        auto_scale_performance=True,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    result = gen.fit_transform(fit_df)
+
+    # Check that each player's minutes_prediction value is preserved
+    original_by_player = dict(zip(fit_df["pid"].to_list(), fit_df["minutes_prediction"].to_list()))
+    result_by_player = dict(zip(result["pid"].to_list(), result["minutes_prediction"].to_list()))
+
+    for pid, original_val in original_by_player.items():
+        result_val = result_by_player[pid]
+        assert result_val == original_val, (
+            f"projected_participation_weight for player {pid} was mutated. "
+            f"Expected {original_val}, got {result_val}"
+        )
+
+
+def test_transform_does_not_mutate_participation_weight(cn_with_projected, fit_df, future_df):
+    """transform should not modify the participation_weight column values."""
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=cn_with_projected,
+        auto_scale_performance=True,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    gen.fit_transform(fit_df)
+
+    result = gen.transform(future_df)
+
+    # Check that each player's minutes value is preserved
+    original_by_player = dict(zip(future_df["pid"].to_list(), future_df["minutes"].to_list()))
+    result_by_player = dict(zip(result["pid"].to_list(), result["minutes"].to_list()))
+
+    for pid, original_val in original_by_player.items():
+        result_val = result_by_player[pid]
+        assert result_val == original_val, (
+            f"participation_weight for player {pid} was mutated during transform. "
+            f"Expected {original_val}, got {result_val}"
+        )
+
+
+def test_transform_does_not_mutate_projected_participation_weight(cn_with_projected, fit_df, future_df):
+    """transform should not modify the projected_participation_weight column values."""
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=cn_with_projected,
+        auto_scale_performance=True,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    gen.fit_transform(fit_df)
+
+    result = gen.transform(future_df)
+
+    # Check that each player's minutes_prediction value is preserved
+    original_by_player = dict(zip(future_df["pid"].to_list(), future_df["minutes_prediction"].to_list()))
+    result_by_player = dict(zip(result["pid"].to_list(), result["minutes_prediction"].to_list()))
+
+    for pid, original_val in original_by_player.items():
+        result_val = result_by_player[pid]
+        assert result_val == original_val, (
+            f"projected_participation_weight for player {pid} was mutated during transform. "
+            f"Expected {original_val}, got {result_val}"
+        )
+
+
+def test_future_transform_does_not_mutate_participation_weight(cn_with_projected, fit_df, future_df):
+    """future_transform should not modify the participation_weight column values."""
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=cn_with_projected,
+        auto_scale_performance=True,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    gen.fit_transform(fit_df)
+
+    original_minutes = future_df["minutes"].to_list()
+    result = gen.future_transform(future_df)
+
+    # The minutes column should have the same values as before
+    result_minutes = result["minutes"].to_list()
+    assert result_minutes == original_minutes, (
+        f"participation_weight column was mutated during future_transform. "
+        f"Expected {original_minutes}, got {result_minutes}"
+    )
+
+
+def test_future_transform_does_not_mutate_projected_participation_weight(cn_with_projected, fit_df, future_df):
+    """future_transform should not modify the projected_participation_weight column values."""
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=cn_with_projected,
+        auto_scale_performance=True,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    gen.fit_transform(fit_df)
+
+    original_minutes_pred = future_df["minutes_prediction"].to_list()
+    result = gen.future_transform(future_df)
+
+    # The minutes_prediction column should have the same values as before
+    result_minutes_pred = result["minutes_prediction"].to_list()
+    assert result_minutes_pred == original_minutes_pred, (
+        f"projected_participation_weight column was mutated during future_transform. "
+        f"Expected {original_minutes_pred}, got {result_minutes_pred}"
+    )
+
+
+def test_multiple_transforms_do_not_compound_scaling(cn_with_projected, fit_df, future_df):
+    """Multiple transform calls should not compound the scaling effect."""
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=cn_with_projected,
+        auto_scale_performance=True,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    gen.fit_transform(fit_df)
+
+    # Call transform multiple times
+    result1 = gen.transform(future_df)
+    result2 = gen.transform(result1)
+    result3 = gen.transform(result2)
+
+    # After 3 transforms, each player's values should still be the same as original
+    original_by_player = dict(zip(future_df["pid"].to_list(), future_df["minutes_prediction"].to_list()))
+    final_by_player = dict(zip(result3["pid"].to_list(), result3["minutes_prediction"].to_list()))
+
+    for pid, original_val in original_by_player.items():
+        final_val = final_by_player[pid]
+        assert final_val == original_val, (
+            f"Multiple transforms compounded the scaling for player {pid}. "
+            f"Expected {original_val}, got {final_val}"
+        )

spforge-0.8.11/tests/ratings/test_utils_scaled_weights.py

@@ -0,0 +1,136 @@
+"""Tests to ensure utility functions use scaled participation weights when available."""
+
+import polars as pl
+import pytest
+
+from spforge import ColumnNames
+from spforge.ratings.utils import (
+    _SCALED_PPW,
+    add_team_rating_projected,
+    add_rating_mean_projected,
+)
+
+
+@pytest.fixture
+def column_names():
+    return ColumnNames(
+        player_id="pid",
+        team_id="tid",
+        match_id="mid",
+        start_date="dt",
+        projected_participation_weight="ppw",
+    )
+
+
+@pytest.fixture
+def df_with_scaled():
+    """DataFrame with both raw and scaled projected participation weights."""
+    return pl.DataFrame({
+        "pid": ["A", "B", "C", "D"],
+        "tid": ["T1", "T1", "T2", "T2"],
+        "mid": ["M1", "M1", "M1", "M1"],
+        "dt": ["2024-01-01"] * 4,
+        "rating": [1100.0, 900.0, 1050.0, 950.0],
+        "ppw": [20.0, 5.0, 10.0, 10.0],  # Raw weights (would give wrong answer)
+        _SCALED_PPW: [1.0, 0.5, 1.0, 1.0],  # Scaled/clipped weights
+    })
+
+
+@pytest.fixture
+def df_without_scaled():
+    """DataFrame with only raw projected participation weights (no scaled column)."""
+    return pl.DataFrame({
+        "pid": ["A", "B", "C", "D"],
+        "tid": ["T1", "T1", "T2", "T2"],
+        "mid": ["M1", "M1", "M1", "M1"],
+        "dt": ["2024-01-01"] * 4,
+        "rating": [1100.0, 900.0, 1050.0, 950.0],
+        "ppw": [0.8, 0.4, 1.0, 1.0],  # Already scaled weights
+    })
+
+
+def test_add_team_rating_projected_uses_scaled_column(column_names, df_with_scaled):
+    """add_team_rating_projected should use _SCALED_PPW when available."""
+    result = add_team_rating_projected(
+        df=df_with_scaled,
+        column_names=column_names,
+        player_rating_col="rating",
+        team_rating_out="team_rating",
+    )
+
+    # With scaled weights (1.0, 0.5), T1 team rating = (1100*1.0 + 900*0.5) / (1.0+0.5) = 1450/1.5 = 966.67
+    # If it used raw weights (20.0, 5.0), it would be (1100*20 + 900*5) / 25 = 26500/25 = 1060
+    t1_rating = result.filter(pl.col("tid") == "T1")["team_rating"][0]
+
+    expected_with_scaled = (1100.0 * 1.0 + 900.0 * 0.5) / (1.0 + 0.5)
+    wrong_with_raw = (1100.0 * 20.0 + 900.0 * 5.0) / (20.0 + 5.0)
+
+    assert t1_rating == pytest.approx(expected_with_scaled, rel=1e-6)
+    assert t1_rating != pytest.approx(wrong_with_raw, rel=1e-6)
+
+
+def test_add_team_rating_projected_falls_back_to_raw(column_names, df_without_scaled):
+    """add_team_rating_projected should use raw ppw when _SCALED_PPW is not available."""
+    result = add_team_rating_projected(
+        df=df_without_scaled,
+        column_names=column_names,
+        player_rating_col="rating",
+        team_rating_out="team_rating",
+    )
+
+    # With raw weights (0.8, 0.4), T1 team rating = (1100*0.8 + 900*0.4) / (0.8+0.4) = 1240/1.2 = 1033.33
+    t1_rating = result.filter(pl.col("tid") == "T1")["team_rating"][0]
+
+    expected = (1100.0 * 0.8 + 900.0 * 0.4) / (0.8 + 0.4)
+    assert t1_rating == pytest.approx(expected, rel=1e-6)
+
+
+def test_add_rating_mean_projected_uses_scaled_column(column_names, df_with_scaled):
+    """add_rating_mean_projected should use _SCALED_PPW when available."""
+    result = add_rating_mean_projected(
+        df=df_with_scaled,
+        column_names=column_names,
+        player_rating_col="rating",
+        rating_mean_out="mean_rating",
+    )
+
+    # With scaled weights, mean = (1100*1.0 + 900*0.5 + 1050*1.0 + 950*1.0) / (1.0+0.5+1.0+1.0)
+    # = (1100 + 450 + 1050 + 950) / 3.5 = 3550/3.5 = 1014.29
+    mean_rating = result["mean_rating"][0]
+
+    expected_with_scaled = (1100.0*1.0 + 900.0*0.5 + 1050.0*1.0 + 950.0*1.0) / (1.0+0.5+1.0+1.0)
+    wrong_with_raw = (1100.0*20.0 + 900.0*5.0 + 1050.0*10.0 + 950.0*10.0) / (20.0+5.0+10.0+10.0)
+
+    assert mean_rating == pytest.approx(expected_with_scaled, rel=1e-6)
+    assert mean_rating != pytest.approx(wrong_with_raw, rel=1e-6)
+
+
+def test_add_rating_mean_projected_falls_back_to_raw(column_names, df_without_scaled):
+    """add_rating_mean_projected should use raw ppw when _SCALED_PPW is not available."""
+    result = add_rating_mean_projected(
+        df=df_without_scaled,
+        column_names=column_names,
+        player_rating_col="rating",
+        rating_mean_out="mean_rating",
+    )
+
+    # With raw weights (0.8, 0.4, 1.0, 1.0)
+    mean_rating = result["mean_rating"][0]
+
+    expected = (1100.0*0.8 + 900.0*0.4 + 1050.0*1.0 + 950.0*1.0) / (0.8+0.4+1.0+1.0)
+    assert mean_rating == pytest.approx(expected, rel=1e-6)
+
+
+def test_scaled_weights_not_in_output(column_names, df_with_scaled):
+    """Verify utility functions don't add scaled columns to output unnecessarily."""
+    result = add_team_rating_projected(
+        df=df_with_scaled,
+        column_names=column_names,
+        player_rating_col="rating",
+        team_rating_out="team_rating",
+    )
+
+    # The scaled column should still be present (it was in input)
+    # but no new internal columns should be added
+    assert _SCALED_PPW in result.columns
+    assert "team_rating" in result.columns