spforge 0.8.5__py3-none-any.whl → 0.8.7__py3-none-any.whl

examples/lol/pipeline_transformer_example.py

@@ -1,123 +1,106 @@
+import polars as pl
 from lightgbm import LGBMRegressor
-from sklearn.linear_model import LogisticRegression
 
 from examples import get_sub_sample_lol_data
 from spforge import AutoPipeline, ColumnNames, FeatureGeneratorPipeline
-from spforge.cross_validator import MatchKFoldCrossValidator
-from spforge.distributions import (
-    NegativeBinomialEstimator,
-)
+from spforge.distributions import NegativeBinomialEstimator
 from spforge.feature_generator import LagTransformer, RollingWindowTransformer
-from spforge.performance_transformers._performance_manager import ColumnWeight
-from spforge.ratings import (
-    PlayerRatingGenerator,
-    RatingKnownFeatures,
-)
+from spforge.transformers import EstimatorTransformer
 
 column_names = ColumnNames(
     team_id="teamname",
     match_id="gameid",
     start_date="date",
-    player_id="playername",
+    player_id="player_uid",
     league="league",
     position="position",
 )
-df = get_sub_sample_lol_data(as_pandas=True)
+
+df = get_sub_sample_lol_data(as_pandas=False, as_polars=True)
 df = (
-    df.loc[lambda x: x.position != "team"]
-    .assign(team_count=df.groupby("gameid")["teamname"].transform("nunique"))
-    .loc[lambda x: x.team_count == 2]
-    .assign(player_count=df.groupby(["gameid", "teamname"])["playername"].transform("nunique"))
-    .loc[lambda x: x.player_count == 5]
+    df.with_columns(
+        pl.concat_str([pl.col("playername"), pl.col("teamname")], separator="__").alias(
+            column_names.player_id
+        )
+    )
+    .filter(pl.col(column_names.position) != "team")
+    .with_columns(
+        pl.col(column_names.team_id)
+        .n_unique()
+        .over(column_names.match_id)
+        .alias("team_count"),
+        pl.col(column_names.player_id)
+        .n_unique()
+        .over([column_names.match_id, column_names.team_id])
+        .alias("player_count"),
+    )
+    .filter((pl.col("team_count") == 2) & (pl.col("player_count") == 5))
+    .drop(["team_count", "player_count"])
+    .unique(subset=[column_names.match_id, column_names.player_id, column_names.team_id])
+    .sort(
+        [
+            column_names.start_date,
+            column_names.match_id,
+            column_names.team_id,
+            column_names.player_id,
+        ]
+    )
 )
-df = df.assign(team_count=df.groupby("gameid")["teamname"].transform("nunique")).loc[
-    lambda x: x.team_count == 2
-]
-
-df = df.drop_duplicates(subset=["gameid", "playername", "teamname"])
 
-# Pretends the last 10 games are future games. The most will be trained on everything before that.
-most_recent_10_games = df[column_names.match_id].unique()[-10:]
-historical_df = df[~df[column_names.match_id].isin(most_recent_10_games)]
-future_df = df[df[column_names.match_id].isin(most_recent_10_games)].drop(columns=["result"])
-rating_generator_player_kills = PlayerRatingGenerator(
-    features_out=[RatingKnownFeatures.PLAYER_RATING],
-    performance_column="performance_kills",
-    auto_scale_performance=True,
-    performance_weights=[ColumnWeight(name="kills", weight=1)],
+most_recent_10_games = (
+    df.select(pl.col(column_names.match_id))
+    .unique(maintain_order=True)
+    .tail(10)
+    .get_column(column_names.match_id)
+    .to_list()
 )
-rating_generator_result = PlayerRatingGenerator(
-    features_out=[RatingKnownFeatures.TEAM_RATING_DIFFERENCE_PROJECTED],
-    performance_column="result",
-    non_predictor_features_out=[RatingKnownFeatures.PLAYER_RATING],
-)
-
+historical_df = df.filter(~pl.col(column_names.match_id).is_in(most_recent_10_games))
+future_df = df.filter(pl.col(column_names.match_id).is_in(most_recent_10_games)).drop("kills")
 
-lag_generators = [
-    LagTransformer(
-        features=["kills", "deaths", "result"], lag_length=3, granularity=["playername"]
-    ),
+lag_transformers = [
+    LagTransformer(features=["kills", "deaths"], lag_length=3, granularity=["player_uid"]),
     RollingWindowTransformer(
-        features=["kills", "deaths", "result"],
+        features=["kills", "deaths"],
         window=20,
         min_periods=1,
-        granularity=["playername"],
+        granularity=["player_uid"],
     ),
 ]
 
 features_generator = FeatureGeneratorPipeline(
     column_names=column_names,
-    feature_generators=[rating_generator_player_kills, rating_generator_result, *lag_generators],
+    feature_generators=lag_transformers,
 )
 
-historical_df = features_generator.fit_transform(historical_df)
-
-game_winner_predictor = SklearnPredictor(
-    estimator=LogisticRegression(),
-    target="result",
-    features=rating_generator_result.features_out,
-    granularity=[column_names.match_id, column_names.team_id],
-)
-game_winner_pipeline = AutoPipeline(
-    predictor=game_winner_predictor, one_hot_encode_cat_features=True, impute_missing_values=True
-)
+historical_df = features_generator.fit_transform(historical_df).to_pandas()
+future_df = features_generator.future_transform(future_df).to_pandas()
 
-player_kills_predictor = SklearnPredictor(
-    estimator=LGBMRegressor(verbose=-100),
-    target="kills",
-    features=[game_winner_predictor.pred_column, *features_generator.features_out],
+point_estimate_transformer = EstimatorTransformer(
+    prediction_column_name="kills_estimate",
+    estimator=LGBMRegressor(verbose=-100, random_state=42),
+    features=features_generator.features_out,
 )
 
-cross_validator_game_winner = MatchKFoldCrossValidator(
-    date_column_name=column_names.start_date,
-    match_id_column_name=column_names.match_id,
-    estimator=game_winner_predictor,
+probability_estimator = NegativeBinomialEstimator(
+    max_value=15,
+    point_estimate_pred_column="kills_estimate",
+    r_specific_granularity=[column_names.player_id],
+    predicted_r_weight=1,
+    column_names=column_names,
 )
 
-game_winner_predictor.train(historical_df)
-historical_df = cross_validator_game_winner.generate_validation_df(historical_df)
-
-cross_validator_player_kills = MatchKFoldCrossValidator(
-    date_column_name=column_names.start_date,
-    match_id_column_name=column_names.match_id,
-    estimator=player_kills_predictor,
+pipeline = AutoPipeline(
+    estimator=probability_estimator,
+    estimator_features=features_generator.features_out,
+    predictor_transformers=[point_estimate_transformer],
 )
 
-player_kills_predictor.train(historical_df)
-print(player_kills_predictor.features)
-historical_df = cross_validator_player_kills.generate_validation_df(historical_df)
-
-future_df = features_generator.future_transform(future_df)
-future_df = game_winner_predictor.predict(future_df)
-future_df = player_kills_predictor.predict(future_df)
-
-probability_predictor = NegativeBinomialEstimator(
-    target="kills",
-    point_estimate_pred_column=player_kills_predictor.pred_column,
-    max_value=15,
-)
+pipeline.fit(X=historical_df, y=historical_df["kills"])
 
-probability_predictor.train(historical_df)
-future_df = probability_predictor.predict(future_df)
+future_point_estimates = pipeline.predict(future_df)
+future_probabilities = pipeline.predict_proba(future_df)
+future_df["kills_pred"] = future_point_estimates
 
-print(future_df.head(10))
+print(future_df.head(5))
+print(f"Probability matrix shape: {future_probabilities.shape}")
+print(f"First row probabilities (0-15 kills): {future_probabilities[0]}")

examples/nba/cross_validation_example.py

@@ -51,7 +51,7 @@ print("\nApproach 1: LGBMClassifier (direct probability prediction)")
 print("-" * 70)
 pipeline_classifier = AutoPipeline(
     estimator=LGBMClassifier(verbose=-100, random_state=42),
-    feature_names=features_generator.features_out,
+    estimator_features=features_generator.features_out,
 )
 
 cross_validator_classifier = MatchKFoldCrossValidator(
@@ -60,7 +60,7 @@ cross_validator_classifier = MatchKFoldCrossValidator(
     estimator=pipeline_classifier,
     prediction_column_name="points_probabilities_classifier",
     target_column="points",
-    features=pipeline_classifier.feature_names,
+    features=pipeline_classifier.required_features,
 )
 validation_df_classifier = cross_validator_classifier.generate_validation_df(df=df)
 
@@ -80,20 +80,13 @@ print("-" * 70)
 predictor_negbin = NegativeBinomialEstimator(
     max_value=40,
     point_estimate_pred_column="points_estimate",
-    r_specific_granularity=["player_id"],
     predicted_r_weight=1,
     column_names=column_names,
 )
 
 pipeline_negbin = AutoPipeline(
     estimator=predictor_negbin,
-    feature_names=features_generator.features_out,
-    context_feature_names=[
-        column_names.player_id,
-        column_names.start_date,
-        column_names.team_id,
-        column_names.match_id,
-    ],
+    estimator_features=features_generator.features_out,
     predictor_transformers=[
         EstimatorTransformer(
             prediction_column_name="points_estimate",
@@ -109,7 +102,7 @@ cross_validator_negbin = MatchKFoldCrossValidator(
     estimator=pipeline_negbin,
     prediction_column_name="points_probabilities_negbin",
     target_column="points",
-    features=pipeline_negbin.context_feature_names + pipeline_negbin.feature_names,
+    features=pipeline_negbin.required_features,
 )
 validation_df_negbin = cross_validator_negbin.generate_validation_df(df=df)
 

examples/nba/feature_engineering_example.py

@@ -13,7 +13,7 @@ Key concepts covered:
 - State management: fit_transform vs future_transform
 """
 
-import pandas as pd
+import polars as pl
 
 from examples import get_sub_sample_nba_data
 from spforge import FeatureGeneratorPipeline
@@ -22,7 +22,7 @@ from spforge.feature_generator import LagTransformer, RollingWindowTransformer
 from spforge.ratings import PlayerRatingGenerator, RatingKnownFeatures
 
 # Load sample NBA data
-df = get_sub_sample_nba_data(as_pandas=True, as_polars=False)
+df = get_sub_sample_nba_data(as_pandas=False, as_polars=True)
 
 # Define column mappings for your dataset
 # This tells spforge which columns contain team IDs, player IDs, dates, etc.
@@ -35,7 +35,7 @@ column_names = ColumnNames(
 
 # CRITICAL: Always sort data chronologically before generating features
 # This ensures temporal ordering and prevents future leakage (using future data to predict the past)
-df = df.sort_values(
+df = df.sort(
     [
         column_names.start_date,  # First by date
         column_names.match_id,  # Then by match
@@ -46,13 +46,21 @@ df = df.sort_values(
 
 # Keep only games with exactly 2 teams (filter out invalid data)
 df = (
-    df.assign(team_count=df.groupby(column_names.match_id)[column_names.team_id].transform("nunique"))
-    .loc[lambda x: x.team_count == 2]
-    .drop(columns=["team_count"])
+    df.with_columns(
+        pl.col(column_names.team_id)
+        .n_unique()
+        .over(column_names.match_id)
+        .alias("team_count")
+    )
+    .filter(pl.col("team_count") == 2)
+    .drop("team_count")
 )
 
-print(f"Dataset: {len(df)} rows, {df[column_names.match_id].nunique()} games")
-print(f"Date range: {df[column_names.start_date].min()} to {df[column_names.start_date].max()}")
+match_count = df.select(pl.col(column_names.match_id).n_unique()).to_series().item()
+start_date = df.select(pl.col(column_names.start_date).min()).to_series().item()
+end_date = df.select(pl.col(column_names.start_date).max()).to_series().item()
+print(f"Dataset: {len(df)} rows, {match_count} games")
+print(f"Date range: {start_date} to {end_date}")
 print()
 
 # ====================================================================
@@ -125,12 +133,22 @@ print()
 # ====================================================================
 
 # Split data into historical (for training) and future (for prediction)
-most_recent_5_games = df[column_names.match_id].unique()[-5:]
-historical_df = df[~df[column_names.match_id].isin(most_recent_5_games)].copy()
-future_df = df[df[column_names.match_id].isin(most_recent_5_games)].copy()
+most_recent_5_games = (
+    df.select(pl.col(column_names.match_id))
+    .unique(maintain_order=True)
+    .tail(5)
+    .get_column(column_names.match_id)
+    .to_list()
+)
+historical_df = df.filter(~pl.col(column_names.match_id).is_in(most_recent_5_games))
+future_df = df.filter(pl.col(column_names.match_id).is_in(most_recent_5_games))
 
-print(f"Historical data: {len(historical_df)} rows, {historical_df[column_names.match_id].nunique()} games")
-print(f"Future data: {len(future_df)} rows, {future_df[column_names.match_id].nunique()} games")
+historical_games = (
+    historical_df.select(pl.col(column_names.match_id).n_unique()).to_series().item()
+)
+future_games = future_df.select(pl.col(column_names.match_id).n_unique()).to_series().item()
+print(f"Historical data: {len(historical_df)} rows, {historical_games} games")
+print(f"Future data: {len(future_df)} rows, {future_games} games")
 print()
 
 # FIT_TRANSFORM: Learn from historical data
@@ -138,7 +156,7 @@ print()
 # - Lags/rolling windows build up from initial games
 # - Internal state (ratings, windows) is MUTATED
 print("Applying fit_transform to historical data...")
-historical_df = features_pipeline.fit_transform(historical_df)
+historical_df = features_pipeline.fit_transform(historical_df).to_pandas()
 print(f"  Generated {len(features_pipeline.features_out)} features:")
 for feature in features_pipeline.features_out:
     print(f"    - {feature}")
@@ -149,7 +167,7 @@ print()
 # - Appends current game to lag/rolling windows but doesn't persist the update
 # - This is what you use in production: generate features without affecting your model's state
 print("Applying future_transform to future data (read-only)...")
-future_df_transformed = features_pipeline.future_transform(future_df)
+future_df_transformed = features_pipeline.future_transform(future_df).to_pandas()
 print(f"  Future data now has {len(future_df_transformed.columns)} columns")
 print()
 

examples/nba/game_winner_example.py

@@ -1,12 +1,13 @@
-import pandas as pd
+import polars as pl
 from sklearn.linear_model import LogisticRegression
 
+from examples import get_sub_sample_nba_data
 from spforge.autopipeline import AutoPipeline
 from spforge.data_structures import ColumnNames
 from spforge.ratings import RatingKnownFeatures
 from spforge.ratings._player_rating import PlayerRatingGenerator
 
-df = pd.read_parquet("data/game_player_subsample.parquet")
+df = get_sub_sample_nba_data(as_pandas=False, as_polars=True)
 
 # Defines the column names as they appear in the dataframe
 column_names = ColumnNames(
@@ -16,8 +17,8 @@ column_names = ColumnNames(
     player_id="player_name",
 )
 # Sorts the dataframe. The dataframe must always be sorted as below
-df = df.sort_values(
-    by=[
+df = df.sort(
+    [
         column_names.start_date,
         column_names.match_id,
         column_names.team_id,
@@ -27,17 +28,26 @@ df = df.sort_values(
 
 # Drops games with less or more than 2 teams
 df = (
-    df.assign(
-        team_count=df.groupby(column_names.match_id)[column_names.team_id].transform("nunique")
+    df.with_columns(
+        pl.col(column_names.team_id)
+        .n_unique()
+        .over(column_names.match_id)
+        .alias("team_count")
     )
-    .loc[lambda x: x.team_count == 2]
-    .drop(columns=["team_count"])
+    .filter(pl.col("team_count") == 2)
+    .drop("team_count")
 )
 
 # Pretends the last 10 games are future games. The most will be trained on everything before that.
-most_recent_10_games = df[column_names.match_id].unique()[-10:]
-historical_df = df[~df[column_names.match_id].isin(most_recent_10_games)]
-future_df = df[df[column_names.match_id].isin(most_recent_10_games)].drop(columns=["won"])
+most_recent_10_games = (
+    df.select(pl.col(column_names.match_id))
+    .unique(maintain_order=True)
+    .tail(10)
+    .get_column(column_names.match_id)
+    .to_list()
+)
+historical_df = df.filter(~pl.col(column_names.match_id).is_in(most_recent_10_games))
+future_df = df.filter(pl.col(column_names.match_id).is_in(most_recent_10_games)).drop("won")
 
 # Defining a simple rating-generator. It will use the "won" column to update the ratings.
 # In contrast to a typical Elo, ratings will follow players.
@@ -49,7 +59,7 @@ rating_generator = PlayerRatingGenerator(
     column_names=column_names,
     non_predictor_features_out=[RatingKnownFeatures.PLAYER_RATING],
 )
-historical_df = rating_generator.fit_transform(historical_df)
+historical_df = rating_generator.fit_transform(historical_df).to_pandas()
 
 # Defines the predictor. A machine-learning model will be used to predict game winner on a game-team-level.
 # Mean team-ratings will be calculated (from player-level) and rating-difference between the 2 teams calculated.
@@ -61,13 +71,13 @@ historical_df = rating_generator.fit_transform(historical_df)
 pipeline = AutoPipeline(
     estimator=LogisticRegression(),
     granularity=["game_id", "team_id"],
-    feature_names=rating_generator.features_out + ["location"],
+    estimator_features=rating_generator.features_out + ["location"],
 )
 
 pipeline.fit(X=historical_df, y=historical_df["won"])
 
 # Future predictions on future results
-future_df = rating_generator.future_transform(future_df)
+future_df = rating_generator.future_transform(future_df).to_pandas()
 future_predictions = pipeline.predict_proba(future_df)[:, 1]
 future_df["game_winner_probability"] = future_predictions
 # Grouping predictions from game-player level to game-level.

examples/nba/predictor_transformers_example.py

@@ -12,7 +12,7 @@ Key concepts covered:
 - Hierarchical modeling: Team strength → Player performance
 """
 
-import pandas as pd
+import polars as pl
 from lightgbm import LGBMRegressor
 from sklearn.linear_model import LogisticRegression
 
@@ -24,7 +24,7 @@ from spforge.ratings import PlayerRatingGenerator, RatingKnownFeatures
 from spforge.transformers import EstimatorTransformer
 
 # Load sample NBA data
-df = get_sub_sample_nba_data(as_pandas=True, as_polars=False)
+df = get_sub_sample_nba_data(as_pandas=False, as_polars=True)
 
 # Define column mappings
 column_names = ColumnNames(
@@ -35,7 +35,7 @@ column_names = ColumnNames(
 )
 
 # Sort data chronologically (critical for temporal correctness)
-df = df.sort_values(
+df = df.sort(
     [
         column_names.start_date,
         column_names.match_id,
@@ -46,18 +46,31 @@ df = df.sort_values(
 
 # Filter to valid games
 df = (
-    df.assign(team_count=df.groupby(column_names.match_id)[column_names.team_id].transform("nunique"))
-    .loc[lambda x: x.team_count == 2]
-    .drop(columns=["team_count"])
+    df.with_columns(
+        pl.col(column_names.team_id)
+        .n_unique()
+        .over(column_names.match_id)
+        .alias("team_count")
+    )
+    .filter(pl.col("team_count") == 2)
+    .drop("team_count")
 )
 
 # Train/test split (using temporal ordering)
-most_recent_10_games = df[column_names.match_id].unique()[-10:]
-train_df = df[~df[column_names.match_id].isin(most_recent_10_games)].copy()
-test_df = df[df[column_names.match_id].isin(most_recent_10_games)].copy()
+most_recent_10_games = (
+    df.select(pl.col(column_names.match_id))
+    .unique(maintain_order=True)
+    .tail(10)
+    .get_column(column_names.match_id)
+    .to_list()
+)
+train_df = df.filter(~pl.col(column_names.match_id).is_in(most_recent_10_games))
+test_df = df.filter(pl.col(column_names.match_id).is_in(most_recent_10_games))
 
-print(f"Training: {len(train_df)} rows, {train_df[column_names.match_id].nunique()} games")
-print(f"Testing: {len(test_df)} rows, {test_df[column_names.match_id].nunique()} games")
+train_games = train_df.select(pl.col(column_names.match_id).n_unique()).to_series().item()
+test_games = test_df.select(pl.col(column_names.match_id).n_unique()).to_series().item()
+print(f"Training: {len(train_df)} rows, {train_games} games")
+print(f"Testing: {len(test_df)} rows, {test_games} games")
 print()
 
 # ====================================================================
@@ -86,8 +99,8 @@ features_pipeline = FeatureGeneratorPipeline(
 )
 
 # Generate features
-train_df = features_pipeline.fit_transform(train_df)
-test_df = features_pipeline.future_transform(test_df)
+train_df = features_pipeline.fit_transform(train_df).to_pandas()
+test_df = features_pipeline.future_transform(test_df).to_pandas()
 
 print(f"Generated {len(features_pipeline.features_out)} baseline features")
 print()
@@ -121,7 +134,7 @@ player_points_pipeline = AutoPipeline(
     estimator=LGBMRegressor(verbose=-100, n_estimators=50),
     # Features for the final estimator (only pre-game information)
     # Note: points_estimate_raw will be added by the transformer
-    feature_names=features_pipeline.features_out,
+    estimator_features=features_pipeline.features_out,
     # The predictor_transformers parameter chains the estimators
     predictor_transformers=[points_estimate_transformer],  # Stage 1 executes first
 )
@@ -150,7 +163,7 @@ print()
 
 # Fit the pipeline
 # The y target here is for the FINAL estimator (player points)
-# Each predictor_transformer has its own target_column specified
+# Predictor_transformers are trained on the same target during fit()
 player_points_pipeline.fit(X=train_df, y=train_df["points"])
 
 print("Training complete!")
@@ -188,7 +201,7 @@ print()
 
 single_stage_pipeline = AutoPipeline(
     estimator=LGBMRegressor(verbose=-100, n_estimators=50),
-    feature_names=features_pipeline.features_out,
+    estimator_features=features_pipeline.features_out,
 )
 
 print("Training single-stage baseline for comparison...")

spforge/hyperparameter_tuning/_default_search_spaces.py

@@ -127,7 +127,7 @@ def get_default_player_rating_search_space() -> dict[str, ParamSpec]:
     """
     Default search space for PlayerRatingGenerator.
 
-    Focuses on 5-8 core parameters that have the most impact on performance.
+    Focuses on core parameters that have the most impact on performance.
 
     Returns:
         Dictionary mapping parameter names to ParamSpec objects
@@ -167,6 +167,31 @@ def get_default_player_rating_search_space() -> dict[str, ParamSpec]:
             param_type="categorical",
             choices=["difference", "mean", "ignore_opponent"],
         ),
+        "start_league_quantile": ParamSpec(
+            param_type="float",
+            low=0.05,
+            high=0.5,
+        ),
+        "start_min_count_for_percentiles": ParamSpec(
+            param_type="int",
+            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,
+        ),
     }
 
 

spforge/ratings/__init__.py

@@ -6,3 +6,7 @@ from .enums import (
     RatingUnknownFeatures as RatingUnknownFeatures,
 )
 from .league_identifier import LeagueIdentifier as LeagueIdentifier
+from .league_start_rating_optimizer import (
+    LeagueStartRatingOptimizationResult as LeagueStartRatingOptimizationResult,
+    LeagueStartRatingOptimizer as LeagueStartRatingOptimizer,
+)

spforge/ratings/_player_rating.py

@@ -129,6 +129,9 @@ class PlayerRatingGenerator(RatingGenerator):
             str(RatingKnownFeatures.PLAYER_RATING_DIFFERENCE_PROJECTED)
         )
         self.MEAN_PROJ_COL = self._suffix(str(RatingKnownFeatures.RATING_MEAN_PROJECTED))
+        self.PLAYER_DIFF_FROM_TEAM_PROJ_COL = self._suffix(
+            str(RatingKnownFeatures.PLAYER_RATING_DIFFERENCE_FROM_TEAM_PROJECTED)
+        )
 
         self.TEAM_OFF_RATING_PROJ_COL = self._suffix(
             str(RatingKnownFeatures.TEAM_OFF_RATING_PROJECTED)
@@ -618,6 +621,7 @@ class PlayerRatingGenerator(RatingGenerator):
             or self.OPP_RATING_PROJ_COL in cols_to_add
             or self.DIFF_PROJ_COL in cols_to_add
             or self.MEAN_PROJ_COL in cols_to_add
+            or self.PLAYER_DIFF_FROM_TEAM_PROJ_COL in cols_to_add
         ):
             df = add_team_rating_projected(
                 df=df,
@@ -673,6 +677,13 @@ class PlayerRatingGenerator(RatingGenerator):
                 )
             )
 
+        if self.PLAYER_DIFF_FROM_TEAM_PROJ_COL in cols_to_add:
+            df = df.with_columns(
+                (pl.col(self.PLAYER_OFF_RATING_COL) - pl.col(self.TEAM_OFF_RATING_PROJ_COL)).alias(
+                    self.PLAYER_DIFF_FROM_TEAM_PROJ_COL
+                )
+            )
+
         if (
             self.TEAM_RATING_COL in cols_to_add
             or self.OPP_RATING_COL in cols_to_add

spforge/ratings/league_start_rating_optimizer.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass
+
+import narwhals.stable.v2 as nw
+import polars as pl
+from narwhals.stable.v2.typing import IntoFrameT
+
+
+DEFAULT_START_RATING = 1000.0
+
+
+@dataclass
+class LeagueStartRatingOptimizationResult:
+    league_ratings: dict[str, float]
+    iteration_errors: list[dict[str, float]]
+
+
+class LeagueStartRatingOptimizer:
+    def __init__(
+        self,
+        rating_generator: object,
+        n_iterations: int = 3,
+        learning_rate: float = 0.2,
+        min_cross_region_rows: int = 10,
+        rating_scale: float | None = None,
+    ):
+        self.rating_generator = rating_generator
+        self.n_iterations = int(n_iterations)
+        self.learning_rate = float(learning_rate)
+        self.min_cross_region_rows = int(min_cross_region_rows)
+        self.rating_scale = rating_scale
+
+    @nw.narwhalify
+    def optimize(self, df: IntoFrameT) -> LeagueStartRatingOptimizationResult:
+        pl_df = df.to_native() if df.implementation.is_polars() else df.to_polars()
+        league_ratings = self._get_league_ratings(self.rating_generator)
+        iteration_errors: list[dict[str, float]] = []
+
+        for _ in range(self.n_iterations):
+            gen = copy.deepcopy(self.rating_generator)
+            self._set_league_ratings(gen, league_ratings)
+            self._ensure_prediction_columns(gen)
+
+            pred_df = gen.fit_transform(pl_df)
+            error_df = self._cross_region_error_df(pl_df, pred_df, gen)
+            if error_df.is_empty():
+                break
+
+            error_summary = (
+                error_df.group_by(self._league_column_name(gen))
+                .agg(
+                    pl.col("error").mean().alias("mean_error"),
+                    pl.len().alias("row_count"),
+                )
+                .to_dicts()
+            )
+            league_key = self._league_column_name(gen)
+            iteration_errors.append({r[league_key]: r["mean_error"] for r in error_summary})
+            league_ratings = self._apply_error_updates(
+                gen, league_ratings, error_summary, league_key
+            )
+
+        self._set_league_ratings(self.rating_generator, league_ratings)
+        return LeagueStartRatingOptimizationResult(
+            league_ratings=league_ratings, iteration_errors=iteration_errors
+        )
+
+    def _cross_region_error_df(
+        self,
+        df: pl.DataFrame,
+        pred_df: pl.DataFrame,
+        rating_generator: object,
+    ) -> pl.DataFrame:
+        column_names = getattr(rating_generator, "column_names", None)
+        if column_names is None:
+            raise ValueError("rating_generator must define column_names")
+
+        match_id = getattr(column_names, "match_id", None)
+        team_id = getattr(column_names, "team_id", None)
+        league_col = getattr(column_names, "league", None)
+        if not match_id or not team_id or not league_col:
+            raise ValueError("column_names must include match_id, team_id, and league")
+
+        pred_col, entity_cols, perf_col = self._prediction_spec(rating_generator)
+        base_cols = [match_id, team_id, league_col, perf_col]
+        for col in base_cols + entity_cols:
+            if col not in df.columns:
+                raise ValueError(f"{col} missing from input dataframe")
+
+        join_cols = [match_id, team_id] + entity_cols
+        joined = df.select(base_cols + entity_cols).join(
+            pred_df.select(join_cols + [pred_col]),
+            on=join_cols,
+            how="inner",
+        )
+        opp_league = self._opponent_mode_league(joined, match_id, team_id, league_col)
+        enriched = joined.join(opp_league, on=[match_id, team_id], how="left").with_columns(
+            (pl.col(perf_col) - pl.col(pred_col)).alias("error")
+        )
+        return enriched.filter(pl.col("opp_mode_league").is_not_null()).filter(
+            pl.col(league_col) != pl.col("opp_mode_league")
+        )
+
+    def _opponent_mode_league(
+        self, df: pl.DataFrame, match_id: str, team_id: str, league_col: str
+    ) -> pl.DataFrame:
+        team_mode = (
+            df.group_by([match_id, team_id, league_col])
+            .agg(pl.len().alias("__count"))
+            .sort(["__count"], descending=True)
+            .unique([match_id, team_id])
+            .select([match_id, team_id, league_col])
+            .rename({league_col: "team_mode_league"})
+        )
+        opponents = (
+            team_mode.join(team_mode, on=match_id, suffix="_opp")
+            .filter(pl.col(team_id) != pl.col(f"{team_id}_opp"))
+            .group_by([match_id, team_id, "team_mode_league_opp"])
+            .agg(pl.len().alias("__count"))
+            .sort(["__count"], descending=True)
+            .unique([match_id, team_id])
+            .select([match_id, team_id, "team_mode_league_opp"])
+            .rename({"team_mode_league_opp": "opp_mode_league"})
+        )
+        return opponents
+
+    def _prediction_spec(self, rating_generator: object) -> tuple[str, list[str], str]:
+        perf_col = getattr(rating_generator, "performance_column", None)
+        if not perf_col:
+            raise ValueError("rating_generator must define performance_column")
+        if hasattr(rating_generator, "PLAYER_PRED_PERF_COL"):
+            pred_col = rating_generator.PLAYER_PRED_PERF_COL
+            column_names = rating_generator.column_names
+            player_id = getattr(column_names, "player_id", None)
+            if not player_id:
+                raise ValueError("column_names must include player_id for player ratings")
+            return pred_col, [player_id], perf_col
+        if hasattr(rating_generator, "TEAM_PRED_OFF_PERF_COL"):
+            pred_col = rating_generator.TEAM_PRED_OFF_PERF_COL
+            return pred_col, [], perf_col
+        raise ValueError("rating_generator must expose a predicted performance column")
+
+    def _ensure_prediction_columns(self, rating_generator: object) -> None:
+        pred_cols: list[str] = []
+        if hasattr(rating_generator, "PLAYER_PRED_PERF_COL"):
+            pred_cols.append(rating_generator.PLAYER_PRED_PERF_COL)
+        elif hasattr(rating_generator, "TEAM_PRED_OFF_PERF_COL"):
+            pred_cols.append(rating_generator.TEAM_PRED_OFF_PERF_COL)
+
+        if not pred_cols:
+            return
+
+        existing = list(getattr(rating_generator, "non_predictor_features_out", []) or [])
+        for col in pred_cols:
+            if col not in existing:
+                existing.append(col)
+        rating_generator.non_predictor_features_out = existing
+
+    def _apply_error_updates(
+        self,
+        rating_generator: object,
+        league_ratings: dict[str, float],
+        error_summary: list[dict[str, float]],
+        league_key: str,
+    ) -> dict[str, float]:
+        scale = self.rating_scale
+        if scale is None:
+            scale = getattr(rating_generator, "rating_change_multiplier_offense", 1.0)
+
+        updated = dict(league_ratings)
+        for row in error_summary:
+            if row["row_count"] < self.min_cross_region_rows:
+                continue
+            league = row[league_key]
+            mean_error = row["mean_error"]
+            base_rating = updated.get(league, DEFAULT_START_RATING)
+            updated[league] = base_rating + self.learning_rate * mean_error * scale
+        return updated
+
+    def _league_column_name(self, rating_generator: object) -> str:
+        column_names = getattr(rating_generator, "column_names", None)
+        league_col = getattr(column_names, "league", None)
+        if not league_col:
+            raise ValueError("column_names must include league for league adjustments")
+        return league_col
+
+    def _get_league_ratings(self, rating_generator: object) -> dict[str, float]:
+        start_gen = getattr(rating_generator, "start_rating_generator", None)
+        if start_gen is None or not hasattr(start_gen, "league_ratings"):
+            raise ValueError("rating_generator must define start_rating_generator.league_ratings")
+        return dict(start_gen.league_ratings)
+
+    def _set_league_ratings(self, rating_generator: object, league_ratings: dict[str, float]) -> None:
+        start_gen = getattr(rating_generator, "start_rating_generator", None)
+        if start_gen is None or not hasattr(start_gen, "league_ratings"):
+            raise ValueError("rating_generator must define start_rating_generator.league_ratings")
+        start_gen.league_ratings = dict(league_ratings)
+        if hasattr(rating_generator, "start_league_ratings"):
+            rating_generator.start_league_ratings = dict(league_ratings)

{spforge-0.8.5.dist-info → spforge-0.8.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spforge
-Version: 0.8.5
+Version: 0.8.7
 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
@@ -85,12 +85,12 @@ This example demonstrates predicting NBA game winners using player-level ratings
 import pandas as pd
 from sklearn.linear_model import LogisticRegression
 
+from examples import get_sub_sample_nba_data
 from spforge.autopipeline import AutoPipeline
 from spforge.data_structures import ColumnNames
-from spforge.ratings import RatingKnownFeatures
-from spforge.ratings._player_rating import PlayerRatingGenerator
+from spforge.ratings import PlayerRatingGenerator, RatingKnownFeatures
 
-df = pd.read_parquet("data/game_player_subsample.parquet")
+df = get_sub_sample_nba_data(as_pandas=True, as_polars=False)
 
 # Step 1: Define column mappings for your dataset
 column_names = ColumnNames(
@@ -144,7 +144,7 @@ historical_df = rating_generator.fit_transform(historical_df)
 pipeline = AutoPipeline(
     estimator=LogisticRegression(),
     granularity=["game_id", "team_id"],  # Aggregate players → teams
-    feature_names=rating_generator.features_out + ["location"],  # Rating + home/away
+    estimator_features=rating_generator.features_out + ["location"],  # Rating + home/away
 )
 
 # Train on historical data
@@ -302,8 +302,8 @@ cross_validator = MatchKFoldCrossValidator(
     prediction_column_name="points_pred",
     target_column="points",
     n_splits=3,  # Number of temporal folds
-    # Must include both feature_names AND context_feature_names
-    features=pipeline.feature_names + pipeline.context_feature_names,
+    # Must include both estimator features and context features
+    features=pipeline.required_features,
 )
 
 # Generate validation predictions
@@ -330,7 +330,7 @@ print(f"Validation MAE: {mae:.2f}")
   - `is_validation=1` marks validation rows, `is_validation=0` marks training rows
   - Use `validation_column` in scorer to score only validation rows
 - Training data always comes BEFORE validation data chronologically
-- Must pass both `feature_names` + `context_feature_names` to `features` parameter
+- Must pass all required features (use `pipeline.required_features`)
 - Scorers can filter rows (e.g., only score players who played minutes > 0)
 
 See [examples/nba/cross_validation_example.py](examples/nba/cross_validation_example.py) for a complete example.
@@ -371,7 +371,7 @@ from lightgbm import LGBMClassifier, LGBMRegressor
 # Approach 1: LGBMClassifier (direct probability prediction)
 pipeline_classifier = AutoPipeline(
     estimator=LGBMClassifier(verbose=-100, random_state=42),
-    feature_names=features_pipeline.features_out,
+    estimator_features=features_pipeline.features_out,
 )
 
 # Approach 2: LGBMRegressor + NegativeBinomialEstimator
@@ -385,13 +385,7 @@ distribution_estimator = NegativeBinomialEstimator(
 
 pipeline_negbin = AutoPipeline(
     estimator=distribution_estimator,
-    feature_names=features_pipeline.features_out,
-    context_feature_names=[
-        column_names.player_id,
-        column_names.start_date,
-        column_names.team_id,
-        column_names.match_id,
-    ],
+    estimator_features=features_pipeline.features_out,
     predictor_transformers=[
         EstimatorTransformer(
             prediction_column_name="points_estimate",
@@ -439,7 +433,7 @@ points_estimate_transformer = EstimatorTransformer(
 # Stage 2: Refine estimate using Stage 1 output
 player_points_pipeline = AutoPipeline(
     estimator=LGBMRegressor(verbose=-100, n_estimators=50),
-    feature_names=features_pipeline.features_out,  # Original features
+    estimator_features=features_pipeline.features_out,  # Original features
     # predictor_transformers execute first, adding their predictions
     predictor_transformers=[points_estimate_transformer],
 )
@@ -474,4 +468,3 @@ For complete, runnable examples with detailed explanations:
 - **[examples/nba/cross_validation_example.py](examples/nba/cross_validation_example.py)** - Time-series CV, distributions, and scoring
 - **[examples/nba/predictor_transformers_example.py](examples/nba/predictor_transformers_example.py)** - Multi-stage hierarchical modeling
 - **[examples/nba/game_winner_example.py](examples/nba/game_winner_example.py)** - Basic workflow for game winner prediction
-

{spforge-0.8.5.dist-info → spforge-0.8.7.dist-info}/RECORD

@@ -1,15 +1,15 @@
 examples/__init__.py,sha256=qGLpphvrjQj0-zS9vP0Q07L-anDnmw7gFZJUEBgYG3U,158
 examples/game_level_example.py,sha256=EOr-H0K79O3Zah4wWuqa5DLmT2iZGbfgxD-xSU2-dfI,2244
 examples/lol/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-examples/lol/pipeline_transformer_example.py,sha256=HousFjE2dbJgdONur4PxwhW2SGQIJGI8aZUIb4TEvIo,4317
+examples/lol/pipeline_transformer_example.py,sha256=XVmm6Xya5z7JyOA0s-DISOlR2I1wpUthCyhRSt9n6qE,3402
 examples/lol/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 examples/lol/data/subsample_lol_data.parquet,sha256=tl04XDslylECJUV1e0DGeqMb6D0Uh6_48NO6TykdgQI,343549
 examples/lol/data/utils.py,sha256=Lt3XNNa5cavvFXHaTQ-GOPxSuWmPEfEO0CVXQEyF_s0,486
 examples/nba/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-examples/nba/cross_validation_example.py,sha256=WD_52vO9m1rILVfXXf8uIb_odpaK-TZ4iOewHU19lTg,5281
-examples/nba/feature_engineering_example.py,sha256=0OHJ2w6vkHvFB2bYwIQQb8HjFA5bfXc7tLmngnahG74,7708
-examples/nba/game_winner_example.py,sha256=RNKYSwpArr08yDWOtkxjx7eAldf97WYDBBfb3tsVSZc,2975
-examples/nba/predictor_transformers_example.py,sha256=mPXRVPx4J5VZtxYH89k7pwh7_EGZ0CXoNHeh2s0AOp8,8499
+examples/nba/cross_validation_example.py,sha256=XVnQJ5mqMou9z83ML5J0wS3gk-pa56sdvahJYQgZ8os,5056
+examples/nba/feature_engineering_example.py,sha256=BDd5594Yi_56lGDqz3SYQkwT8NVZyFkgv3gKPCsAjz4,8197
+examples/nba/game_winner_example.py,sha256=7VVHxGyU2uPjT9q6lDMHJ5KpkWp9gU8brxr_UZfuSHg,3189
+examples/nba/predictor_transformers_example.py,sha256=Fl4BY_hVW0iYERolN6s-ZB2xv-UxOK547L6iI5t0r0Y,8807
 examples/nba/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 examples/nba/data/game_player_subsample.parquet,sha256=ODJxHC-mUYbJ7r-ScUFtPU7hrFuxLUbbDSobmpCkw0w,279161
 examples/nba/data/utils.py,sha256=41hxLQ1d6ZgBEcHa5MI0-fG5KbsRi07cclMPQZM95ek,509
@@ -44,17 +44,18 @@ spforge/feature_generator/_rolling_mean_days.py,sha256=EZQmFmYVQB-JjZV5k8bOWnaTx
 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=entdE7gtj8JM5C47-lLd93CoEsXjw8YfcWeWS8d0AZk,6882
+spforge/hyperparameter_tuning/_default_search_spaces.py,sha256=Sm5IrHAW0-vRC8jqCPX0pDi_C-W3L_MoEKGA8bx1Zbc,7546
 spforge/hyperparameter_tuning/_tuner.py,sha256=uovhGqhe8-fdhi79aErUmE2h5NCycFQEIRv5WCjpC7E,16732
 spforge/performance_transformers/__init__.py,sha256=U6d7_kltbUMLYCGBk4QAFVPJTxXD3etD9qUftV-O3q4,422
 spforge/performance_transformers/_performance_manager.py,sha256=KwAga6dGhNkXi-MDW6LPjwk6VZwCcjo5L--jnk9aio8,9706
 spforge/performance_transformers/_performances_transformers.py,sha256=0lxuWjAfWBRXRgQsNJHjw3P-nlTtHBu4_bOVdoy7hq4,15536
-spforge/ratings/__init__.py,sha256=jAa_xF2e-96FoyD57EYFKE-mO6OnK23siJOB4tzbyek,387
+spforge/ratings/__init__.py,sha256=OZVH2Lo6END3n1X8qi4QcyAPlThIwAYwVKCiIuOQSQU,576
 spforge/ratings/_base.py,sha256=dRMkIGj5-2zKddygaEA4g16WCyXon7v8Xa1ymm7IuoM,14335
-spforge/ratings/_player_rating.py,sha256=05CuiSa2_uM0xtYpxT00OOxU_TmW4qt6dsXvn7seFss,50861
+spforge/ratings/_player_rating.py,sha256=MyqsyLSY6d7_bxDSnF8eWOyXpSCADWGdepdFSGM4cHw,51365
 spforge/ratings/_team_rating.py,sha256=T0kFiv3ykYSrVGGsVRa8ZxLB0WMnagxqdFDzl9yZ_9g,24813
 spforge/ratings/enums.py,sha256=s7z_RcZS6Nlgfa_6tasO8_IABZJwywexe7sep9DJBgo,1739
 spforge/ratings/league_identifier.py,sha256=_KDUKOwoNU6RNFKE5jju4eYFGVNGBdJsv5mhNvMakfc,6019
+spforge/ratings/league_start_rating_optimizer.py,sha256=Q4Vo3QT-r55qP4aD9WftsTB00UOSRvxM1khlyuAGWNM,8582
 spforge/ratings/player_performance_predictor.py,sha256=cMxzQuk0nF1MsT_M32g-3mxVdAEbZ-S7TUjEPYdo3Yg,8361
 spforge/ratings/start_rating_generator.py,sha256=_7hIJ9KRVCwsCoY1GIzY8cuOdHR8RH_BCMeMwQG3E04,6776
 spforge/ratings/team_performance_predictor.py,sha256=ThQOmYQUqKBB46ONYHOMM2arXFH8AkyKpAZzs80SjHA,7217
@@ -70,16 +71,17 @@ spforge/transformers/_other_transformer.py,sha256=xLfaFIhkFsigAoitB4x3F8An2j9ymd
 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.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+spforge-0.8.7.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
 tests/test_autopipeline.py,sha256=WXHeqBdjQD6xaXVkzvS8ocz0WVP9R7lN0PiHJ2iD8nA,16911
 tests/test_autopipeline_context.py,sha256=IuRUY4IA6uMObvbl2pXSaXO2_tl3qX6wEbTZY0dkTMI,1240
 tests/test_feature_generator_pipeline.py,sha256=CAgBknWqawqYi5_hxcPmpxrLVa5elMHVv1VrSVRKXEA,17705
 tests/cross_validator/test_cross_validator.py,sha256=itCGhNY8-NbDbKbhxHW20wiLuRst7-Rixpmi3FSKQtA,17474
 tests/distributions/test_distribution.py,sha256=aU8hfCgliM80TES4WGjs9KFXpV8XghBGF7Hu9sqEVSE,10982
 tests/end_to_end/test_estimator_hyperparameter_tuning.py,sha256=fZCJ9rrED2vT68B9ovmVA1cIG2pHRTjy9xzZLxxpEBo,2513
+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=eOsTSVWv16bc0l_nCxH4x8jF-gsmn4Ttfv92mHqSXzc,6303
+tests/end_to_end/test_nba_player_ratings_hyperparameter_tuning.py,sha256=LXRkI_6Ho2kzJVbNAM17QFhx_MP9WdDJXCO9dWgJGNA,6491
 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
@@ -92,10 +94,10 @@ tests/hyperparameter_tuning/test_estimator_tuner.py,sha256=iewME41d6LR2aQ0OtohGF
 tests/hyperparameter_tuning/test_rating_tuner.py,sha256=PyCFP3KPc4Iy9E_X9stCVxra14uMgC1tuRwuQ30rO_o,13195
 tests/performance_transformers/test_performance_manager.py,sha256=bfC5GiBuzHw-mLmKeEzBUUPuKm0ayax2bsF1j88W8L0,10120
 tests/performance_transformers/test_performances_transformers.py,sha256=A-tGiCx7kXrj1cVj03Bc7prOeZ1_Ryz8YFx9uj3eK6w,11064
-tests/ratings/test_player_rating_generator.py,sha256=3mjqlX159QqOlBoY3r_TFkvLwpE4zlLE0fiqpbfk3ps,58547
+tests/ratings/test_player_rating_generator.py,sha256=FGH3Tq0uFoSlkS_XMldsUKhsovBRBvzH9EbqjKvg2O0,59601
 tests/ratings/test_ratings_property.py,sha256=ckyfGILXa4tfQvsgyXEzBDNr2DUmHwFRV13N60w66iE,6561
 tests/ratings/test_team_rating_generator.py,sha256=cDnf1zHiYC7pkgydE3MYr8wSTJIq-bPfSqhIRI_4Tic,95357
-tests/scorer/test_score.py,sha256=KTrGJypQEpU8tmgJ6LU8wK1SRC3PLUXFzZIyiA-UY7U,71749
+tests/scorer/test_score.py,sha256=_Vd6tKpy_1GeOxU7Omxci4CFf7PvRGMefEI0gv2gV6A,74688
 tests/scorer/test_score_aggregation_granularity.py,sha256=h-hyFOLzwp-92hYVU7CwvlRJ8jhB4DzXCtqgI-zcoqM,13677
 tests/transformers/test_estimator_transformer_context.py,sha256=5GOHbuWCWBMFwwOTJOuD4oNDsv-qDR0OxNZYGGuMdag,1819
 tests/transformers/test_net_over_predicted.py,sha256=vh7O1iRRPf4vcW9aLhOMAOyatfM5ZnLsQBKNAYsR3SU,3363
@@ -103,7 +105,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.5.dist-info/METADATA,sha256=bqArRdOKZYvSc47sa9cJsOhsDxh0q4T6GoF_xIBkjpA,20226
-spforge-0.8.5.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-spforge-0.8.5.dist-info/top_level.txt,sha256=6UW2M5a7WKOeaAi900qQmRKNj5-HZzE8-eUD9Y9LTq0,23
-spforge-0.8.5.dist-info/RECORD,,
+spforge-0.8.7.dist-info/METADATA,sha256=7vwprmmFvSpEL3lC0HqFZPbzxMi8mRzI0yOsa7pUlNQ,20047
+spforge-0.8.7.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+spforge-0.8.7.dist-info/top_level.txt,sha256=6UW2M5a7WKOeaAi900qQmRKNj5-HZzE8-eUD9Y9LTq0,23
+spforge-0.8.7.dist-info/RECORD,,

tests/end_to_end/test_league_start_rating_optimizer.py

@@ -0,0 +1,117 @@
+import pandas as pd
+import polars as pl
+import pytest
+
+from spforge import ColumnNames
+from spforge.ratings import (
+    LeagueStartRatingOptimizer,
+    PlayerRatingGenerator,
+    TeamRatingGenerator,
+)
+
+
+def _player_df():
+    dates = pd.date_range("2024-01-01", periods=3, freq="D")
+    rows = []
+    for i, date in enumerate(dates):
+        mid = f"M{i}"
+        for player_idx in range(2):
+            rows.append(
+                {
+                    "pid": f"A{player_idx}",
+                    "tid": "TA",
+                    "mid": mid,
+                    "date": date,
+                    "league": "LCK",
+                    "perf": 0.4,
+                }
+            )
+        for player_idx in range(2):
+            rows.append(
+                {
+                    "pid": f"B{player_idx}",
+                    "tid": "TB",
+                    "mid": mid,
+                    "date": date,
+                    "league": "LEC",
+                    "perf": 0.6,
+                }
+            )
+    return pd.DataFrame(rows)
+
+
+def _team_df():
+    dates = pd.date_range("2024-01-01", periods=3, freq="D")
+    rows = []
+    for i, date in enumerate(dates):
+        mid = f"M{i}"
+        rows.extend(
+            [
+                {
+                    "tid": "TA",
+                    "mid": mid,
+                    "date": date,
+                    "league": "LCK",
+                    "perf": 0.4,
+                },
+                {
+                    "tid": "TB",
+                    "mid": mid,
+                    "date": date,
+                    "league": "LEC",
+                    "perf": 0.6,
+                },
+            ]
+        )
+    return pd.DataFrame(rows)
+
+
+@pytest.mark.parametrize("use_polars", [False, True])
+def test_league_start_rating_optimizer__adjusts_player_leagues(use_polars):
+    cn = ColumnNames(
+        player_id="pid",
+        team_id="tid",
+        match_id="mid",
+        start_date="date",
+        league="league",
+    )
+    df = _player_df()
+    if use_polars:
+        df = pl.from_pandas(df)
+    generator = PlayerRatingGenerator(performance_column="perf", column_names=cn)
+    optimizer = LeagueStartRatingOptimizer(
+        rating_generator=generator,
+        n_iterations=1,
+        learning_rate=0.5,
+        min_cross_region_rows=1,
+    )
+
+    result = optimizer.optimize(df)
+
+    assert result.league_ratings["LCK"] < 1000
+    assert result.league_ratings["LEC"] > 1000
+
+
+@pytest.mark.parametrize("use_polars", [False, True])
+def test_league_start_rating_optimizer__adjusts_team_leagues(use_polars):
+    cn = ColumnNames(
+        team_id="tid",
+        match_id="mid",
+        start_date="date",
+        league="league",
+    )
+    df = _team_df()
+    if use_polars:
+        df = pl.from_pandas(df)
+    generator = TeamRatingGenerator(performance_column="perf", column_names=cn)
+    optimizer = LeagueStartRatingOptimizer(
+        rating_generator=generator,
+        n_iterations=1,
+        learning_rate=0.5,
+        min_cross_region_rows=1,
+    )
+
+    result = optimizer.optimize(df)
+
+    assert result.league_ratings["LCK"] < 1000
+    assert result.league_ratings["LEC"] > 1000

tests/end_to_end/test_nba_player_ratings_hyperparameter_tuning.py

@@ -97,6 +97,11 @@ def test_nba_player_ratings_hyperparameter_tuning__workflow_completes(
         "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/ratings/test_player_rating_generator.py

@@ -1662,3 +1662,30 @@ 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)

tests/scorer/test_score.py

@@ -2048,3 +2048,93 @@ def test_all_scorers_handle_all_nan_targets(df_type):
         assert np.isnan(score) or score == 0.0
     except (ValueError, IndexError):
         pass
+SCORER_VALIDATION_CASES = [
+    pytest.param(
+        lambda: MeanBiasScorer(pred_column="pred", target="target", validation_column="is_validation"),
+        lambda: pd.DataFrame(
+            {
+                "pred": [2.0, 0.0],
+                "target": [1.0, 2.0],
+                "is_validation": [1, 0],
+            }
+        ),
+        id="mean_bias",
+    ),
+    pytest.param(
+        lambda: PWMSE(pred_column="pred", target="target", labels=[0, 1], validation_column="is_validation"),
+        lambda: pd.DataFrame(
+            {
+                "pred": [[0.7, 0.3], [0.4, 0.6]],
+                "target": [0, 1],
+                "is_validation": [1, 0],
+            }
+        ),
+        id="pwmse",
+    ),
+    pytest.param(
+        lambda: SklearnScorer(
+            scorer_function=mean_absolute_error, pred_column="pred", target="target", validation_column="is_validation"
+        ),
+        lambda: pd.DataFrame(
+            {
+                "pred": [1.0, 0.0],
+                "target": [1.0, 0.0],
+                "is_validation": [1, 0],
+            }
+        ),
+        id="sklearn",
+    ),
+    pytest.param(
+        lambda: ProbabilisticMeanBias(
+            pred_column="pred", target="target", class_column_name="classes", validation_column="is_validation"
+        ),
+        lambda: pd.DataFrame(
+            {
+                "pred": [[0.2, 0.8], [0.6, 0.4]],
+                "target": [1, 0],
+                "classes": [[0, 1], [0, 1]],
+                "is_validation": [1, 0],
+            }
+        ),
+        id="probabilistic_mean_bias",
+    ),
+    pytest.param(
+        lambda: OrdinalLossScorer(pred_column="pred", target="target", classes=[0, 1], validation_column="is_validation"),
+        lambda: pd.DataFrame(
+            {
+                "pred": [[0.2, 0.8], [0.6, 0.4]],
+                "target": [1, 0],
+                "is_validation": [1, 0],
+            }
+        ),
+        id="ordinal_loss",
+    ),
+    pytest.param(
+        lambda: ThresholdEventScorer(
+            dist_column="dist",
+            threshold_column="threshold",
+            outcome_column="outcome",
+            comparator=Operator.GREATER_THAN_OR_EQUALS,
+            validation_column="is_validation",
+        ),
+        lambda: pd.DataFrame(
+            {
+                "dist": [[0.2, 0.8], [0.6, 0.4], [0.3, 0.7]],
+                "threshold": [0.5, 0.2, 0.3],
+                "outcome": [1, 0, 1],
+                "is_validation": [1, 1, 0],
+            }
+        ),
+        id="threshold_event",
+    ),
+]
+
+
+@pytest.mark.parametrize("scorer_factory, df_factory", SCORER_VALIDATION_CASES)
+def test_scorers_respect_validation_column(scorer_factory, df_factory):
+    """Scorers should filter on validation_column when specified."""
+    df = df_factory()
+    df_valid = df[df["is_validation"] == 1]
+    score_all = scorer_factory().score(df)
+    score_valid = scorer_factory().score(df_valid)
+    assert score_all == score_valid