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

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(
@@ -1662,3 +1719,100 @@ def test_player_rating_team_with_strong_offense_and_weak_defense_gets_expected_r
 
     assert a_off > start_rating
     assert a_def < start_rating
+
+
+def test_fit_transform__player_rating_difference_from_team_projected_feature(base_cn, sample_df):
+    """PLAYER_RATING_DIFFERENCE_FROM_TEAM_PROJECTED computes player_off_rating - team_off_rating_projected."""
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        auto_scale_performance=True,
+        features_out=[
+            RatingKnownFeatures.PLAYER_RATING_DIFFERENCE_FROM_TEAM_PROJECTED,
+            RatingKnownFeatures.PLAYER_OFF_RATING,
+            RatingKnownFeatures.TEAM_OFF_RATING_PROJECTED,
+        ],
+    )
+    result = gen.fit_transform(sample_df)
+
+    diff_col = "player_rating_difference_from_team_projected_perf"
+    player_col = "player_off_rating_perf"
+    team_col = "team_off_rating_projected_perf"
+
+    assert diff_col in result.columns
+    assert player_col in result.columns
+    assert team_col in result.columns
+
+    for row in result.iter_rows(named=True):
+        expected = row[player_col] - row[team_col]
+        assert row[diff_col] == pytest.approx(expected, rel=1e-9)
+
+
+def test_fit_transform__start_league_quantile_uses_existing_player_ratings(base_cn):
+    """
+    Bug reproduction: start_league_quantile should use percentile of existing player
+    ratings for new players, but update_players_to_leagues is never called so
+    _league_player_ratings stays empty and all new players get default rating.
+
+    Expected: New player P_NEW should start at 5th percentile of existing ratings (~920)
+    Actual: New player starts at default 1000 because _league_player_ratings is empty
+    """
+    import numpy as np
+
+    num_existing_players = 60
+    player_ids = [f"P{i}" for i in range(num_existing_players)]
+    team_ids = [f"T{i % 2 + 1}" for i in range(num_existing_players)]
+
+    df1 = pl.DataFrame(
+        {
+            "pid": player_ids,
+            "tid": team_ids,
+            "mid": ["M1"] * num_existing_players,
+            "dt": ["2024-01-01"] * num_existing_players,
+            "perf": [0.3 + (i % 10) * 0.07 for i in range(num_existing_players)],
+            "pw": [1.0] * num_existing_players,
+        }
+    )
+
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        auto_scale_performance=True,
+        start_league_quantile=0.05,
+        start_min_count_for_percentiles=50,
+        features_out=[RatingKnownFeatures.PLAYER_OFF_RATING],
+    )
+    gen.fit_transform(df1)
+
+    existing_ratings = [
+        gen._player_off_ratings[pid].rating_value for pid in player_ids
+    ]
+    expected_quantile_rating = np.percentile(existing_ratings, 5)
+
+    srg = gen.start_rating_generator
+    assert len(srg._league_player_ratings.get(None, [])) >= 50, (
+        f"Expected _league_player_ratings to have >=50 entries but got "
+        f"{len(srg._league_player_ratings.get(None, []))}. "
+        "update_players_to_leagues is never called."
+    )
+
+    df2 = pl.DataFrame(
+        {
+            "pid": ["P_NEW", "P0"],
+            "tid": ["T1", "T2"],
+            "mid": ["M2", "M2"],
+            "dt": ["2024-01-02", "2024-01-02"],
+            "pw": [1.0, 1.0],
+        }
+    )
+    result = gen.future_transform(df2)
+
+    new_player_start_rating = result.filter(pl.col("pid") == "P_NEW")[
+        "player_off_rating_perf"
+    ][0]
+
+    assert new_player_start_rating == pytest.approx(expected_quantile_rating, rel=0.1), (
+        f"New player should start at 5th percentile ({expected_quantile_rating:.1f}) "
+        f"but got {new_player_start_rating:.1f}. "
+        "start_league_quantile has no effect because update_players_to_leagues is never called."
+    )

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}"
+        )

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