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

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

tests/scorer/test_score.py

@@ -2138,3 +2138,145 @@ def test_scorers_respect_validation_column(scorer_factory, df_factory):
     score_all = scorer_factory().score(df)
     score_valid = scorer_factory().score(df_valid)
     assert score_all == score_valid
+
+
+# ============================================================================
+# PWMSE evaluation_labels Extension Tests
+# ============================================================================
+
+
+@pytest.mark.parametrize("df_type", [pl.DataFrame, pd.DataFrame])
+def test_pwmse__evaluation_labels_extends_predictions(df_type):
+    """PWMSE with evaluation_labels as superset extends predictions with small probs."""
+    df = create_dataframe(
+        df_type,
+        {
+            "pred": [
+                [0.3, 0.5, 0.2],
+                [0.2, 0.6, 0.2],
+            ],
+            "target": [0, 1],
+        },
+    )
+
+    scorer = PWMSE(
+        pred_column="pred",
+        target="target",
+        labels=[0, 1, 2],
+        evaluation_labels=[-1, 0, 1, 2, 3],
+    )
+    score = scorer.score(df)
+
+    n_eval_labels = 5
+    eps = 1e-5
+    preds_original = np.array([[0.3, 0.5, 0.2], [0.2, 0.6, 0.2]])
+    extended = np.full((2, n_eval_labels), eps, dtype=np.float64)
+    extended[:, 1] = preds_original[:, 0]
+    extended[:, 2] = preds_original[:, 1]
+    extended[:, 3] = preds_original[:, 2]
+    row_sums = extended.sum(axis=1, keepdims=True)
+    preds_renorm = extended / row_sums
+
+    eval_labels = np.array([-1, 0, 1, 2, 3], dtype=np.float64)
+    targets = np.array([0, 1], dtype=np.float64)
+    diffs_sqd = (eval_labels[None, :] - targets[:, None]) ** 2
+    expected = float((diffs_sqd * preds_renorm).sum(axis=1).mean())
+
+    assert abs(score - expected) < 1e-10
+
+
+@pytest.mark.parametrize("df_type", [pl.DataFrame, pd.DataFrame])
+def test_pwmse__evaluation_labels_exact_match(df_type):
+    """PWMSE with evaluation_labels identical to labels (no-op)."""
+    df = create_dataframe(
+        df_type,
+        {
+            "pred": [
+                [0.3, 0.5, 0.2],
+                [0.2, 0.6, 0.2],
+            ],
+            "target": [0, 1],
+        },
+    )
+
+    scorer_with_eval = PWMSE(
+        pred_column="pred",
+        target="target",
+        labels=[0, 1, 2],
+        evaluation_labels=[0, 1, 2],
+    )
+    scorer_without_eval = PWMSE(
+        pred_column="pred",
+        target="target",
+        labels=[0, 1, 2],
+    )
+
+    score_with = scorer_with_eval.score(df)
+    score_without = scorer_without_eval.score(df)
+
+    assert abs(score_with - score_without) < 1e-10
+
+
+@pytest.mark.parametrize("df_type", [pl.DataFrame, pd.DataFrame])
+def test_pwmse__evaluation_labels_partial_overlap_raises(df_type):
+    """PWMSE with partial overlap between labels and evaluation_labels raises."""
+    with pytest.raises(ValueError, match="evaluation_labels must be a subset or superset"):
+        PWMSE(
+            pred_column="pred",
+            target="target",
+            labels=[0, 1, 2],
+            evaluation_labels=[1, 2, 3],
+        )
+
+
+@pytest.mark.parametrize("df_type", [pl.DataFrame, pd.DataFrame])
+def test_pwmse__evaluation_labels_extends_with_compare_to_naive(df_type):
+    """PWMSE extension mode works correctly with compare_to_naive."""
+    df = create_dataframe(
+        df_type,
+        {
+            "pred": [
+                [0.8, 0.15, 0.05],
+                [0.1, 0.7, 0.2],
+                [0.05, 0.15, 0.8],
+                [0.3, 0.4, 0.3],
+            ],
+            "target": [0, 1, 2, 1],
+        },
+    )
+
+    scorer = PWMSE(
+        pred_column="pred",
+        target="target",
+        labels=[0, 1, 2],
+        evaluation_labels=[-1, 0, 1, 2, 3],
+        compare_to_naive=True,
+    )
+    score = scorer.score(df)
+
+    n_eval_labels = 5
+    eps = 1e-5
+    preds_original = np.array([
+        [0.8, 0.15, 0.05],
+        [0.1, 0.7, 0.2],
+        [0.05, 0.15, 0.8],
+        [0.3, 0.4, 0.3],
+    ])
+    extended = np.full((4, n_eval_labels), eps, dtype=np.float64)
+    extended[:, 1] = preds_original[:, 0]
+    extended[:, 2] = preds_original[:, 1]
+    extended[:, 3] = preds_original[:, 2]
+    row_sums = extended.sum(axis=1, keepdims=True)
+    preds_renorm = extended / row_sums
+
+    eval_labels = np.array([-1, 0, 1, 2, 3], dtype=np.float64)
+    targets = np.array([0, 1, 2, 1], dtype=np.float64)
+    diffs_sqd = (eval_labels[None, :] - targets[:, None]) ** 2
+    model_score = float((diffs_sqd * preds_renorm).sum(axis=1).mean())
+
+    naive_probs = np.array([0.0, 0.25, 0.5, 0.25, 0.0])
+    naive_preds = np.tile(naive_probs, (4, 1))
+    naive_score = float((diffs_sqd * naive_preds).sum(axis=1).mean())
+
+    expected = naive_score - model_score
+    assert abs(score - expected) < 1e-10