spforge 0.8.27__py3-none-any.whl → 0.8.30__py3-none-any.whl

tests/ratings/test_player_rating_generator.py

@@ -4,7 +4,12 @@ import polars as pl
 import pytest
 
 from spforge import ColumnNames
-from spforge.data_structures import PlayerRating, RatingState
+from spforge.data_structures import (
+    MatchPerformance,
+    PlayerRating,
+    PreMatchPlayerRating,
+    PreMatchTeamRating,
+)
 from spforge.ratings import PlayerRatingGenerator, RatingKnownFeatures, RatingUnknownFeatures
 
 
@@ -138,6 +143,60 @@ def test_fit_transform_participation_weight_scaling(base_cn):
     assert half_rating > 0
 
 
+def test_player_rating_generator_team_rating_coef_affects_predictor(base_cn):
+    """Passing a team rating coefficient should affect the predictor used by the generator."""
+    generator = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        performance_predictor="difference",
+        team_rating_diff_coef=0.5,
+        rating_diff_coef=0.0,
+        rating_diff_team_from_entity_coef=0.0,
+    )
+
+    predictor = generator._performance_predictor
+    match_perf = MatchPerformance(
+        performance_value=0.5,
+        participation_weight=1.0,
+        projected_participation_weight=1.0,
+    )
+    player_rating = PreMatchPlayerRating(
+        id="P1",
+        rating_value=100.0,
+        games_played=1,
+        league=None,
+        position=None,
+        match_performance=match_perf,
+    )
+    opponent_team_rating = PreMatchTeamRating(id="Opp", players=[], rating_value=100.0)
+    high_team_rating = PreMatchTeamRating(
+        id="TeamHigh",
+        players=[player_rating],
+        rating_value=110.0,
+    )
+    low_team_rating = PreMatchTeamRating(
+        id="TeamLow",
+        players=[player_rating],
+        rating_value=90.0,
+    )
+
+    high_pred = predictor.predict_performance(
+        player_rating=player_rating,
+        opponent_team_rating=opponent_team_rating,
+        team_rating=high_team_rating,
+    )
+    low_pred = predictor.predict_performance(
+        player_rating=player_rating,
+        opponent_team_rating=opponent_team_rating,
+        team_rating=low_team_rating,
+    )
+
+    assert predictor.team_rating_diff_coef == 0.5
+    assert high_pred > low_pred
+    assert high_pred > 0.5
+    assert low_pred < 0.5
+
+
 def test_fit_transform_batch_update_logic(base_cn):
     """Test that ratings do not update between matches if update_match_id is the same."""
     from dataclasses import replace
@@ -2352,3 +2411,413 @@ def test_fit_transform_backward_compatible_without_playing_time_columns(base_cn)
     # Ratings should be updated normally
     assert gen._player_off_ratings["P1"].rating_value != 1000.0
     assert gen._player_off_ratings["P3"].rating_value > gen._player_off_ratings["P4"].rating_value
+
+
+def test_fit_transform_ignore_opponent_predictor_adapts_to_performance_drift(base_cn):
+    """
+    Test that PlayerRatingNonOpponentPerformancePredictor converges to actual
+    performance with fixed reference (not stuck at 0.5 like rolling average).
+
+    With pre-scaled data (mean=0.48 ≠ 0.5), predictions should converge to 0.48,
+    not stay stuck at 0.5. This verifies the fixed reference allows convergence.
+    """
+    import numpy as np
+
+    np.random.seed(42)  # Reproducible test
+    n_matches = 1500
+    n_players_per_team = 5
+    n_teams = 2
+
+    # Target mean intentionally NOT 0.5 to test convergence
+    target_mean = 0.48
+
+    data = {
+        "pid": [],
+        "tid": [],
+        "mid": [],
+        "dt": [],
+        "perf": [],
+        "pw": [],
+    }
+
+    match_id = 0
+    for i in range(n_matches // 2):
+        date = datetime(2019, 1, 1) + timedelta(days=i * 2)
+        date_str = date.strftime("%Y-%m-%d")
+
+        # Generate performance data already in [0,1] with mean at target
+        # Small std to keep values tightly around target mean
+        for team_idx in range(n_teams):
+            team_id = f"T{team_idx + 1}"
+            for player_idx in range(n_players_per_team):
+                player_id = f"P{team_idx}_{player_idx}"
+                # Draw from normal distribution, clip to [0,1]
+                perf = np.random.normal(target_mean, 0.08)
+                perf = max(0.0, min(1.0, perf))
+
+                data["pid"].append(player_id)
+                data["tid"].append(team_id)
+                data["mid"].append(f"M{match_id}")
+                data["dt"].append(date_str)
+                data["perf"].append(perf)
+                data["pw"].append(1.0)
+
+        match_id += 1
+
+    df = pl.DataFrame(data)
+
+    # Verify input data has mean ≠ 0.5 (before any scaling)
+    input_mean = sum(data["perf"]) / len(data["perf"])
+    assert abs(input_mean - target_mean) < 0.01, f"Input data mean should be ~{target_mean}"
+
+    # Use ignore_opponent predictor with fixed reference
+    # CRITICAL: auto_scale_performance=False to preserve the input mean
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        performance_predictor="ignore_opponent",
+        auto_scale_performance=False,  # Keep input mean at 0.48
+        start_harcoded_start_rating=1000.0,
+        rating_change_multiplier_offense=100,  # Faster convergence for test
+        rating_change_multiplier_defense=100,
+        non_predictor_features_out=[RatingUnknownFeatures.PLAYER_PREDICTED_PERFORMANCE],
+    )
+
+    result = gen.fit_transform(df)
+
+    # Check tail (after convergence period)
+    tail_start_match = (n_matches // 2) - 200
+    tail_df = result.filter(
+        pl.col("mid").cast(pl.Utf8).str.extract(r"M(\d+)", 1).cast(pl.Int32) >= tail_start_match
+    )
+
+    tail_actual = tail_df["perf"].to_list()
+    tail_preds = tail_df["player_predicted_performance_perf"].to_list()
+
+    mean_actual = sum(tail_actual) / len(tail_actual)
+    mean_pred = sum(tail_preds) / len(tail_preds)
+
+    # With fixed reference, predictions should converge close to actual mean
+    deviation = abs(mean_pred - mean_actual)
+    assert deviation < 0.015, (
+        f"Mean predicted performance {mean_pred:.4f} deviates from "
+        f"actual mean {mean_actual:.4f} by {deviation:.4f}. "
+        f"With fixed reference, predictions should converge to actual performance mean."
+    )
+
+    # Verify we're not stuck at 0.5 (the original rolling average bug)
+    assert abs(mean_pred - 0.5) > 0.01, (
+        f"Mean predicted performance {mean_pred:.4f} is too close to 0.5. "
+        f"System appears stuck at sigmoid midpoint (original rolling average bug)."
+    )
+
+
+def test_fit_transform_ignore_opponent_with_autoscale_and_temporal_drift(base_cn):
+    """
+    Test that fixed reference works with auto_scale_performance=True and temporal drift.
+
+    With balanced data (overall mean=0.5) and temporal drift (early=0.505, late=0.495):
+    - Auto_scale preserves overall mean at 0.5
+    - Predictions track the SCALED values (not raw 0.505/0.495)
+    - Drift is preserved (early predictions > late predictions)
+    """
+    import numpy as np
+
+    np.random.seed(42)
+    n_matches = 1000
+    n_players_per_team = 5
+
+    data = {
+        "pid": [],
+        "tid": [],
+        "mid": [],
+        "dt": [],
+        "perf": [],
+        "pw": [],
+    }
+
+    match_id = 0
+    for i in range(n_matches // 2):
+        date = datetime(2019, 1, 1) + timedelta(days=i * 2)
+        date_str = date.strftime("%Y-%m-%d")
+
+        # Temporal drift: 0.505 -> 0.495 (overall mean = 0.5)
+        progress = i / (n_matches // 2)
+        period_mean = 0.505 - (0.01 * progress)
+
+        for team_idx in range(2):
+            team_id = f"T{team_idx + 1}"
+            for player_idx in range(n_players_per_team):
+                player_id = f"P{team_idx}_{player_idx}"
+                # Add variance around period mean
+                perf = np.random.normal(period_mean, 0.03)
+                perf = max(0.0, min(1.0, perf))
+
+                data["pid"].append(player_id)
+                data["tid"].append(team_id)
+                data["mid"].append(f"M{match_id}")
+                data["dt"].append(date_str)
+                data["perf"].append(perf)
+                data["pw"].append(1.0)
+
+        match_id += 1
+
+    df = pl.DataFrame(data)
+
+    # Verify raw data is balanced
+    raw_mean = sum(data["perf"]) / len(data["perf"])
+    assert abs(raw_mean - 0.5) < 0.01, f"Raw data should have mean ≈ 0.5, got {raw_mean}"
+
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        performance_predictor="ignore_opponent",
+        auto_scale_performance=True,  # ← Key: with auto_scale
+        start_harcoded_start_rating=1000.0,
+        rating_change_multiplier_offense=100,
+        rating_change_multiplier_defense=100,
+        non_predictor_features_out=[RatingUnknownFeatures.PLAYER_PREDICTED_PERFORMANCE],
+    )
+
+    result = gen.fit_transform(df)
+
+    # Check that auto_scale created the performance column
+    assert "performance__perf" in result.columns
+
+    # Get overall scaled mean
+    all_scaled = result["performance__perf"].to_list()
+    overall_scaled_mean = sum(all_scaled) / len(all_scaled)
+
+    # Verify overall scaled mean ≈ 0.5 (auto_scale preserves balance)
+    assert abs(overall_scaled_mean - 0.5) < 0.01, (
+        f"Auto_scale should preserve overall mean at 0.5, got {overall_scaled_mean}"
+    )
+
+    # Get early and late periods
+    early_df = result.filter(
+        pl.col("mid").cast(pl.Utf8).str.extract(r"M(\d+)", 1).cast(pl.Int32) < 100
+    )
+    late_df = result.filter(
+        pl.col("mid").cast(pl.Utf8).str.extract(r"M(\d+)", 1).cast(pl.Int32) >= (n_matches//2 - 100)
+    )
+
+    early_actual_scaled = early_df["performance__perf"].to_list()
+    early_preds = early_df["player_predicted_performance_perf"].to_list()
+    late_actual_scaled = late_df["performance__perf"].to_list()
+    late_preds = late_df["player_predicted_performance_perf"].to_list()
+
+    early_actual_mean = sum(early_actual_scaled) / len(early_actual_scaled)
+    early_pred_mean = sum(early_preds) / len(early_preds)
+    late_actual_mean = sum(late_actual_scaled) / len(late_actual_scaled)
+    late_pred_mean = sum(late_preds) / len(late_preds)
+
+    # Verify drift is preserved after scaling (strict bounds based on 0.505→0.495 drift)
+    assert early_actual_mean > 0.51, (
+        f"Early period should be > 0.51 after scaling, got {early_actual_mean:.4f}"
+    )
+    assert late_actual_mean < 0.49, (
+        f"Late period should be < 0.49 after scaling, got {late_actual_mean:.4f}"
+    )
+
+    # Verify drift magnitude is significant
+    drift_magnitude = early_actual_mean - late_actual_mean
+    assert drift_magnitude > 0.02, (
+        f"Drift magnitude should be > 0.02, got {drift_magnitude:.4f}"
+    )
+
+    # Verify predictions track the SCALED values (not raw 0.505/0.495)
+    # Tolerance: 0.025 accounts for convergence lag with temporal drift
+    early_deviation = abs(early_pred_mean - early_actual_mean)
+    late_deviation = abs(late_pred_mean - late_actual_mean)
+
+    assert early_deviation < 0.025, (
+        f"Early predictions should converge to scaled actual ({early_actual_mean:.4f}), "
+        f"got {early_pred_mean:.4f}, deviation={early_deviation:.4f}"
+    )
+    assert late_deviation < 0.025, (
+        f"Late predictions should converge to scaled actual ({late_actual_mean:.4f}), "
+        f"got {late_pred_mean:.4f}, deviation={late_deviation:.4f}"
+    )
+
+    # Verify drift is tracked in predictions
+    assert early_pred_mean > late_pred_mean, (
+        f"Predictions should track temporal drift: early ({early_pred_mean:.4f}) > late ({late_pred_mean:.4f})"
+    )
+
+
+def test_ignore_opponent_predictor_reference_rating_set_correctly(base_cn):
+    """
+    Test that PlayerRatingNonOpponentPerformancePredictor._reference_rating
+    is set correctly from start rating parameters.
+    """
+    # Test 1: With hardcoded start rating
+    gen1 = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        performance_predictor="ignore_opponent",
+        auto_scale_performance=True,
+        start_harcoded_start_rating=1100.0,
+    )
+    assert gen1._performance_predictor._reference_rating == 1100.0, (
+        f"Expected reference rating 1100.0, got {gen1._performance_predictor._reference_rating}"
+    )
+
+    # Test 2: Without hardcoded start (should default to 1000)
+    gen2 = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        performance_predictor="ignore_opponent",
+        auto_scale_performance=True,
+    )
+    assert gen2._performance_predictor._reference_rating == 1000.0, (
+        f"Expected reference rating 1000.0, got {gen2._performance_predictor._reference_rating}"
+    )
+
+    # Test 3: With league ratings (single league)
+    gen3 = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        performance_predictor="ignore_opponent",
+        auto_scale_performance=True,
+        start_league_ratings={"NBA": 1150},
+    )
+    assert gen3._performance_predictor._reference_rating == 1150.0, (
+        f"Expected reference rating 1150.0, got {gen3._performance_predictor._reference_rating}"
+    )
+
+    # Test 4: With multiple league ratings (should use mean)
+    gen4 = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        performance_predictor="ignore_opponent",
+        auto_scale_performance=True,
+        start_league_ratings={"NBA": 1100, "G-League": 900, "EuroLeague": 1000},
+    )
+    expected_mean = (1100 + 900 + 1000) / 3
+    assert gen4._performance_predictor._reference_rating == expected_mean, (
+        f"Expected reference rating {expected_mean}, got {gen4._performance_predictor._reference_rating}"
+    )
+
+    # Test 5: Hardcoded start rating takes precedence over league ratings
+    gen5 = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        performance_predictor="ignore_opponent",
+        auto_scale_performance=True,
+        start_harcoded_start_rating=1200.0,
+        start_league_ratings={"NBA": 1100},
+    )
+    assert gen5._performance_predictor._reference_rating == 1200.0, (
+        f"Expected hardcoded start rating 1200.0 to take precedence, got {gen5._performance_predictor._reference_rating}"
+    )
+
+
+def test_separate_offense_defense_participation_weights(base_cn):
+    """Test that offense and defense use separate participation weights.
+
+    When participation_weight represents offensive activity (e.g., shots attempted),
+    using it for both offense and defense updates creates bias. This test verifies
+    that defense_participation_weight is used for defensive rating updates.
+    """
+    from dataclasses import replace
+
+    cn = replace(
+        base_cn,
+        participation_weight="shots_attempted",
+        defense_participation_weight="minutes",
+    )
+
+    # Create a scenario where a high-volume shooter (many shots) faces a low-volume shooter
+    # The high-volume shooter should have larger offensive updates but equal defensive updates
+    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, 0.4, 0.5, 0.5],  # Varying performance values
+            "shots_attempted": [10.0, 10.0, 10.0, 10.0],  # Same offensive activity
+            "minutes": [30.0, 30.0, 30.0, 30.0],  # Same defensive activity
+        }
+    )
+
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=cn,
+        auto_scale_performance=True,
+        rating_change_multiplier_offense=50,
+        rating_change_multiplier_defense=50,
+    )
+
+    result = gen.fit_transform(df)
+
+    # Verify that the defense_participation_weight column is present in the data
+    assert "minutes" in df.columns
+
+    # All players performed equally (0.5) with equal participation weights,
+    # so ratings should be symmetric
+    assert "P1" in gen._player_off_ratings
+    assert "P1" in gen._player_def_ratings
+
+    # Now test with different participation weights for offense vs defense
+    df2 = pl.DataFrame(
+        {
+            "pid": ["P1", "P2", "P3", "P4"],
+            "tid": ["T1", "T1", "T2", "T2"],
+            "mid": ["M2", "M2", "M2", "M2"],
+            "dt": ["2024-01-02"] * 4,
+            "perf": [0.6, 0.4, 0.5, 0.5],
+            "shots_attempted": [20.0, 5.0, 10.0, 10.0],  # P1 shoots much more
+            "minutes": [30.0, 30.0, 30.0, 30.0],  # But all play same minutes
+        }
+    )
+
+    result2 = gen.fit_transform(df2)
+
+    # P1 should have larger offensive rating changes due to high shots_attempted
+    # but equal defensive rating changes due to equal minutes played
+    p1_off = gen._player_off_ratings["P1"]
+    p2_off = gen._player_off_ratings["P2"]
+    p1_def = gen._player_def_ratings["P1"]
+    p2_def = gen._player_def_ratings["P2"]
+
+    # Both players have same games_played count for defense
+    assert p1_def.games_played == p2_def.games_played
+
+    # Verify that ratings were updated
+    assert p1_off.games_played > 0
+    assert p2_off.games_played > 0
+
+
+@pytest.mark.parametrize("library", ["polars", "pandas"])
+def test_defense_participation_weight_backwards_compatibility(base_cn, library):
+    """Test that when defense_participation_weight is not set, it defaults to participation_weight."""
+    import pandas as pd
+
+    df_data = {
+        "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.5, 0.5],
+        "pw": [1.0, 0.5, 0.8, 0.8],
+    }
+
+    if library == "polars":
+        df = pl.DataFrame(df_data)
+    else:
+        df = pd.DataFrame(df_data)
+
+    # When defense_participation_weight is None, it should default to participation_weight
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        auto_scale_performance=True,
+    )
+
+    result = gen.fit_transform(df)
+
+    # Should work without errors
+    assert result is not None
+    assert len(gen._player_off_ratings) > 0
+    assert len(gen._player_def_ratings) > 0