spforge 0.8.33__py3-none-any.whl → 0.8.35__py3-none-any.whl

spforge/performance_transformers/__init__.py

@@ -6,5 +6,6 @@ from ._performances_transformers import (
     DiminishingValueTransformer as DiminishingValueTransformer,
     MinMaxTransformer as MinMaxTransformer,
     PartialStandardScaler as PartialStandardScaler,
+    QuantilePerformanceScaler as QuantilePerformanceScaler,
     SymmetricDistributionTransformer as SymmetricDistributionTransformer,
 )

spforge/performance_transformers/_performance_manager.py

@@ -4,6 +4,7 @@ from dataclasses import dataclass
 from typing import Literal
 
 import narwhals.stable.v2 as nw
+import numpy as np
 from narwhals.typing import IntoFrameT
 from sklearn.base import BaseEstimator, TransformerMixin
 
@@ -11,6 +12,7 @@ from spforge.performance_transformers._performances_transformers import (
     MinMaxTransformer,
     NarwhalsFeatureTransformer,
     PartialStandardScaler,
+    QuantilePerformanceScaler,
     SymmetricDistributionTransformer,
 )
 
@@ -86,9 +88,12 @@ class PerformanceManager(BaseEstimator, TransformerMixin):
         prefix: str = "performance__",
         min_value: float = -0.02,
         max_value: float = 1.02,
+        zero_inflation_threshold: float = 0.15,
     ):
         self.features = features
         self.prefix = prefix
+        # Store whether user explicitly disabled transformers (passed empty list)
+        self._user_disabled_transformers = transformer_names is not None and len(transformer_names) == 0
         self.transformer_names = transformer_names or [
             "symmetric",
             "partial_standard_scaler",
@@ -100,6 +105,7 @@ class PerformanceManager(BaseEstimator, TransformerMixin):
         self.performance_column = self.prefix + performance_column
         self.min_value = min_value
         self.max_value = max_value
+        self.zero_inflation_threshold = zero_inflation_threshold
 
         self.transformers = create_performance_scalers_transformers(
             transformer_names=self.transformer_names,
@@ -107,9 +113,47 @@ class PerformanceManager(BaseEstimator, TransformerMixin):
             features=self.features,
             prefix=self.prefix,
         )
+        self._using_quantile_scaler = False
 
     @nw.narwhalify
     def fit(self, df: IntoFrameT, y=None):
+        # Check for zero-inflated distributions and swap to quantile scaler if needed
+        # Only apply when user hasn't explicitly disabled transformers (passed empty list)
+        if self.zero_inflation_threshold > 0 and not self._user_disabled_transformers:
+            df = self._ensure_inputs_exist(df, self.transformers[0])
+            prefixed_features = [self.prefix + f for f in self.features]
+
+            for feature in prefixed_features:
+                if feature in df.columns:
+                    values = df[feature].to_numpy()
+                    values = values[np.isfinite(values)]
+
+                    # Skip if binary/categorical data (few unique values)
+                    # Quantile scaler is for continuous zero-inflated data, not binary outcomes
+                    n_unique = len(np.unique(values))
+                    if n_unique <= 3:
+                        continue
+
+                    zero_proportion = np.mean(np.abs(values) < 1e-10)
+
+                    if zero_proportion > self.zero_inflation_threshold:
+                        logging.info(
+                            f"Detected zero-inflated distribution for {feature} "
+                            f"({zero_proportion:.1%} zeros). Using QuantilePerformanceScaler."
+                        )
+                        self._using_quantile_scaler = True
+                        # Use original_transformers (deepcopy made before standard transformers
+                        # were appended to custom_transformers)
+                        self.transformers = [
+                            copy.deepcopy(t) for t in self.original_transformers
+                        ] + [
+                            QuantilePerformanceScaler(
+                                features=prefixed_features,
+                                prefix="",
+                            )
+                        ]
+                        break
+
         for t in self.transformers:
             df = self._ensure_inputs_exist(df, t)
             t.fit(df)
@@ -169,6 +213,7 @@ class PerformanceWeightsManager(PerformanceManager):
         min_value: float = -0.02,
         prefix: str = "performance__",
         return_all_features: bool = False,
+        zero_inflation_threshold: float = 0.15,
     ):
         self.weights = weights
         self.return_all_features = return_all_features
@@ -181,6 +226,7 @@ class PerformanceWeightsManager(PerformanceManager):
             max_value=max_value,
             min_value=min_value,
             performance_column=performance_column,
+            zero_inflation_threshold=zero_inflation_threshold,
         )
 
     @nw.narwhalify

spforge/performance_transformers/_performances_transformers.py

@@ -3,6 +3,7 @@ from typing import Literal, Protocol
 
 import narwhals
 import narwhals.stable.v2 as nw
+import numpy as np
 from lightgbm import LGBMRegressor
 from narwhals.typing import IntoFrameT
 from sklearn.base import BaseEstimator, TransformerMixin
@@ -420,3 +421,82 @@ class GroupByTransformer(BaseEstimator, TransformerMixin):
     @nw.narwhalify
     def transform(self, df: IntoFrameT) -> IntoFrameT:
         return df.join(self._grouped, on=self.granularity, how="left").to_native()
+
+
+class QuantilePerformanceScaler(BaseEstimator, TransformerMixin):
+    """
+    Quantile-based scaling for zero-inflated distributions.
+
+    Uses probability integral transform:
+    - Zeros → π/2 (midpoint of zero probability mass)
+    - Non-zeros → uniform on (π, 1) via empirical CDF
+
+    Fast: O(n log n) for fit, O(n) for transform.
+    """
+
+    def __init__(
+        self,
+        features: list[str],
+        zero_threshold: float = 1e-10,
+        n_quantiles: int = 1000,
+        prefix: str = "",
+    ):
+        self.features = features
+        self.zero_threshold = zero_threshold
+        self.n_quantiles = n_quantiles
+        self.prefix = prefix
+        self.features_out = [self.prefix + f for f in self.features]
+
+        self._zero_proportion: dict[str, float] = {}
+        self._nonzero_quantiles: dict[str, np.ndarray | None] = {}
+
+    @nw.narwhalify
+    def fit(self, df: IntoFrameT, y=None):
+        for feature in self.features:
+            values = df[feature].to_numpy()
+            values = values[np.isfinite(values)]
+
+            is_zero = np.abs(values) < self.zero_threshold
+            self._zero_proportion[feature] = np.mean(is_zero)
+
+            nonzero_values = values[~is_zero]
+            if len(nonzero_values) > 0:
+                percentiles = np.linspace(0, 100, self.n_quantiles + 1)
+                self._nonzero_quantiles[feature] = np.percentile(nonzero_values, percentiles)
+            else:
+                self._nonzero_quantiles[feature] = None
+        return self
+
+    @nw.narwhalify
+    def transform(self, df: IntoFrameT) -> IntoFrameT:
+        for feature in self.features:
+            out_feature = self.prefix + feature
+            values = df[feature].to_numpy()
+            result = np.full_like(values, np.nan, dtype=float)
+
+            # Handle NaN explicitly - preserve NaN in output
+            is_finite = np.isfinite(values)
+            is_zero = is_finite & (np.abs(values) < self.zero_threshold)
+            is_nonzero = is_finite & ~is_zero
+
+            pi = self._zero_proportion[feature]
+
+            # Zeros → midpoint of zero mass
+            result[is_zero] = pi / 2
+
+            # Non-zeros → interpolate to (π, 1)
+            nonzero_quantiles = self._nonzero_quantiles[feature]
+            if nonzero_quantiles is not None and np.any(is_nonzero):
+                nonzero_values = np.clip(
+                    values[is_nonzero], nonzero_quantiles[0], nonzero_quantiles[-1]
+                )
+                ranks = np.interp(
+                    nonzero_values,
+                    nonzero_quantiles,
+                    np.linspace(0, 1, len(nonzero_quantiles)),
+                )
+                result[is_nonzero] = pi + (1 - pi) * ranks
+
+            df = df.with_columns(**{out_feature: result})
+
+        return df.to_native()

spforge/ratings/_player_rating.py

@@ -29,6 +29,7 @@ from spforge.ratings._base import RatingGenerator, RatingKnownFeatures, RatingUn
 from spforge.ratings.start_rating_generator import StartRatingGenerator
 from spforge.ratings.utils import (
     add_opp_team_rating,
+    add_player_opponent_mean_projected,
     add_rating_difference_projected,
     add_rating_mean_projected,
     add_team_rating,
@@ -141,6 +142,9 @@ class PlayerRatingGenerator(RatingGenerator):
         self.PLAYER_DIFF_FROM_TEAM_PROJ_COL = self._suffix(
             str(RatingKnownFeatures.PLAYER_RATING_DIFFERENCE_FROM_TEAM_PROJECTED)
         )
+        self.PLAYER_OPP_MEAN_PROJ_COL = self._suffix(
+            str(RatingKnownFeatures.PLAYER_OPPONENT_MEAN_PROJECTED)
+        )
 
         self.TEAM_OFF_RATING_PROJ_COL = self._suffix(
             str(RatingKnownFeatures.TEAM_OFF_RATING_PROJECTED)
@@ -844,6 +848,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.PLAYER_DIFF_PROJ_COL in cols_to_add
+            or self.PLAYER_OPP_MEAN_PROJ_COL in cols_to_add
         ):
             df = add_team_rating_projected(
                 df=df,
@@ -865,6 +870,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.PLAYER_DIFF_PROJ_COL in cols_to_add
+            or self.PLAYER_OPP_MEAN_PROJ_COL in cols_to_add
         ):
             df = add_opp_team_rating(
                 df=df,
@@ -925,6 +931,15 @@ class PlayerRatingGenerator(RatingGenerator):
                 rating_mean_out=self.MEAN_PROJ_COL,
             )
 
+        if self.PLAYER_OPP_MEAN_PROJ_COL in cols_to_add:
+            df = add_player_opponent_mean_projected(
+                df=df,
+                column_names=cn,
+                player_rating_col=self.PLAYER_RATING_COL,
+                opp_team_rating_col=self.OPP_RATING_PROJ_COL,
+                out_col=self.PLAYER_OPP_MEAN_PROJ_COL,
+            )
+
         if self.DIFF_COL in cols_to_add and self.DIFF_COL not in df.columns:
             if self.TEAM_RATING_COL not in df.columns:
                 df = add_team_rating(

spforge/ratings/enums.py

@@ -17,6 +17,7 @@ class RatingKnownFeatures(StrEnum):
     PLAYER_RATING_DIFFERENCE_PROJECTED = "player_rating_difference_projected"
     TEAM_RATING_DIFFERENCE_PROJECTED = "team_rating_difference_projected"
     RATING_MEAN_PROJECTED = "rating_mean_projected"
+    PLAYER_OPPONENT_MEAN_PROJECTED = "player_opponent_mean_projected"
     TEAM_LEAGUE = "team_league"
     PLAYER_LEAGUE = "player_league"
     OPPONENT_LEAGUE = "opponent_league"

spforge/ratings/utils.py

@@ -137,3 +137,16 @@ def add_rating_mean_projected(
         )
 
     return df.with_columns(pl.col(player_rating_col).mean().over(mid).alias(rating_mean_out))
+
+
+def add_player_opponent_mean_projected(
+    df: pl.DataFrame,
+    column_names: ColumnNames,
+    player_rating_col: str,
+    opp_team_rating_col: str,
+    out_col: str,
+) -> pl.DataFrame:
+    """Mean of player rating and opponent team rating."""
+    return df.with_columns(
+        ((pl.col(player_rating_col) + pl.col(opp_team_rating_col)) / 2).alias(out_col)
+    )

{spforge-0.8.33.dist-info → spforge-0.8.35.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spforge
-Version: 0.8.33
+Version: 0.8.35
 Summary: A flexible framework for generating features, ratings, and building machine learning or other models for training and inference on sports data.
 Author-email: Mathias Holmstrøm <mathiasholmstom@gmail.com>
 License: See LICENSE file

{spforge-0.8.33.dist-info → spforge-0.8.35.dist-info}/RECORD

@@ -46,21 +46,21 @@ spforge/feature_generator/_utils.py,sha256=KDn33ia1OYJTK8THFpvc_uRiH_Bl3fImGqqbf
 spforge/hyperparameter_tuning/__init__.py,sha256=Vcl8rVlJ7M708iPgqe4XxpZWgJKGux0Y5HgMCymRsHg,1099
 spforge/hyperparameter_tuning/_default_search_spaces.py,sha256=SjwXLpvYIu_JY8uPRHeL5Kgp1aa0slWDz8qsKDaohWQ,8020
 spforge/hyperparameter_tuning/_tuner.py,sha256=M79q3saM6r0UZJsRUUgfdDr-3Qii-F2-wuSAZLFtZDo,19246
-spforge/performance_transformers/__init__.py,sha256=U6d7_kltbUMLYCGBk4QAFVPJTxXD3etD9qUftV-O3q4,422
-spforge/performance_transformers/_performance_manager.py,sha256=WmjmlMEnq7y75MiI_s9Y-9eMXIyhPTUKrwsXRtgYp0k,9620
-spforge/performance_transformers/_performances_transformers.py,sha256=0lxuWjAfWBRXRgQsNJHjw3P-nlTtHBu4_bOVdoy7hq4,15536
+spforge/performance_transformers/__init__.py,sha256=J-5olqi1M_BUj3sN1NqAz9s28XAbuKK9M9xHq7IGlQU,482
+spforge/performance_transformers/_performance_manager.py,sha256=tR_4laGoC_KFRaw3Gy0TMI-r5gnicDmvmxPEgAvl4E0,12031
+spforge/performance_transformers/_performances_transformers.py,sha256=ZjkFDXoEe5fURpN-dNkrgFXpHEg4aFCWdBDnPyLtgkM,18368
 spforge/ratings/__init__.py,sha256=OZVH2Lo6END3n1X8qi4QcyAPlThIwAYwVKCiIuOQSQU,576
 spforge/ratings/_base.py,sha256=ne4BRrYFPqMirdFPVnyDN44wjFQwOQgWoUXu_59xgWE,14687
-spforge/ratings/_player_rating.py,sha256=Ii1HNz0tC25dxZy9B2b_ULZVNwExNvdyIGw_1gRIeko,67163
+spforge/ratings/_player_rating.py,sha256=KkTmKtacx-1cMuncWVIkoO-3srfEOAjx8o5prEeaAWQ,67811
 spforge/ratings/_team_rating.py,sha256=3m90-R2zW0k5EHwjw-83Hacz91fGmxW1LQ8ZUGHlgt4,24970
-spforge/ratings/enums.py,sha256=s7z_RcZS6Nlgfa_6tasO8_IABZJwywexe7sep9DJBgo,1739
+spforge/ratings/enums.py,sha256=maG0X4WMQeMVAc2wbceq1an-U-z8moZGeG2BAgfICDA,1809
 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=GtPpYlALgbQk8YHeaiRbpRvJHxeAhKpRxsaVUc9zR5o,7963
 spforge/ratings/start_rating_generator.py,sha256=eSasa5Oe9n4IoTGjFCYyFQAGrJtzrBW-Qor97lmaYuM,6776
 spforge/ratings/team_performance_predictor.py,sha256=ThQOmYQUqKBB46ONYHOMM2arXFH8AkyKpAZzs80SjHA,7217
 spforge/ratings/team_start_rating_generator.py,sha256=vK-_m8KwcHopchch_lKNHSGLiiNm5q9Lenm0d1cP_po,5110
-spforge/ratings/utils.py,sha256=_zFemqz2jJkH8rn2EZpDt8N6FELUmYp9qCnPzRtOIGU,4497
+spforge/ratings/utils.py,sha256=WFxpiutHG9itJtjtagb26mjpHRjIhT7hopsiyetUgTg,4866
 spforge/scorer/__init__.py,sha256=wj8PCvYIl6742Xwmt86c3oy6iqE8Ss-OpwHud6kd9IY,256
 spforge/scorer/_score.py,sha256=DOl3wlHH0IlQelQA5CaNAfVtJhc544ZO5l-1mEno7nA,65276
 spforge/transformers/__init__.py,sha256=IPCsMcsgBqG52d0ttATLCY4HvFCQZddExlLt74U-zuI,390
@@ -71,7 +71,7 @@ spforge/transformers/_other_transformer.py,sha256=w2a7Wnki3vJe4GAkSa4kealw0GILIo
 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.33.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+spforge-0.8.35.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
 tests/test_autopipeline.py,sha256=7cNAn-nmGolfyfk3THh9IKcHZfRA-pLYC_xAyMg-No4,26863
 tests/test_autopipeline_context.py,sha256=IuRUY4IA6uMObvbl2pXSaXO2_tl3qX6wEbTZY0dkTMI,1240
 tests/test_feature_generator_pipeline.py,sha256=CK0zVL8PfTncy3RmG9i-YpgwjOIV7yJhV7Q44tbetI8,19020
@@ -92,9 +92,9 @@ tests/feature_generator/test_rolling_mean_days.py,sha256=EyOvdJDnmgPfe13uQBOkwo7
 tests/feature_generator/test_rolling_window.py,sha256=_o9oljcAIZ14iI7e8WFeAsfXxILnyqBffit21HOvII4,24378
 tests/hyperparameter_tuning/test_estimator_tuner.py,sha256=iewME41d6LR2aQ0OtohGFtN_ocJUwTeqvs6L0QDmfG4,4413
 tests/hyperparameter_tuning/test_rating_tuner.py,sha256=usjC2ioO_yWRjjNAlRTyMVYheOrCi0kKocmHQHdTmpM,18699
-tests/performance_transformers/test_performance_manager.py,sha256=gjuuV_hb27kCo_kUecPKG3Cbot2Gqis1W3kw2A4ovS4,10690
-tests/performance_transformers/test_performances_transformers.py,sha256=A-tGiCx7kXrj1cVj03Bc7prOeZ1_Ryz8YFx9uj3eK6w,11064
-tests/ratings/test_player_rating_generator.py,sha256=9iepzvjlAlye-CkrEX5GT6Pf4Bf4qi_uDwB6Wamo1JY,104641
+tests/performance_transformers/test_performance_manager.py,sha256=fVXxSujE3OKE7tIRJjN5dWCLj9pkeXbuL6Zf0WrM0ZA,15698
+tests/performance_transformers/test_performances_transformers.py,sha256=HnW7GKQ6B0ova6Zy0lKbEpA6peZGFE4oi9Th6r7RnG0,18949
+tests/ratings/test_player_rating_generator.py,sha256=lFqFmEfy_sSyyeCmY0aCNaW3wj73ySVU3sp1O_m1os4,105713
 tests/ratings/test_player_rating_no_mutation.py,sha256=GzO3Hl__5K68DS3uRLefwnbcTJOvBM7cZqww4M21UZM,8493
 tests/ratings/test_ratings_property.py,sha256=ckyfGILXa4tfQvsgyXEzBDNr2DUmHwFRV13N60w66iE,6561
 tests/ratings/test_team_rating_generator.py,sha256=SqQcfckNmJJc99feCdnmkNYDape-p69e92Dp8Vzpu2w,101156
@@ -108,7 +108,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.33.dist-info/METADATA,sha256=LH22MH7XYeFTROBWPYVVHWyYRSwMYGozGMCtaJdkLgg,20048
-spforge-0.8.33.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-spforge-0.8.33.dist-info/top_level.txt,sha256=6UW2M5a7WKOeaAi900qQmRKNj5-HZzE8-eUD9Y9LTq0,23
-spforge-0.8.33.dist-info/RECORD,,
+spforge-0.8.35.dist-info/METADATA,sha256=9ZQ0JmZkbQIGI48KUUlHw8jI8umvspKRztLv1E0EW60,20048
+spforge-0.8.35.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+spforge-0.8.35.dist-info/top_level.txt,sha256=6UW2M5a7WKOeaAi900qQmRKNj5-HZzE8-eUD9Y9LTq0,23
+spforge-0.8.35.dist-info/RECORD,,

tests/performance_transformers/test_performance_manager.py

@@ -4,7 +4,7 @@ import pandas as pd
 import polars as pl
 import pytest
 
-from spforge.performance_transformers import PerformanceWeightsManager
+from spforge.performance_transformers import PerformanceWeightsManager, QuantilePerformanceScaler
 from spforge.performance_transformers._performance_manager import (
     ColumnWeight,
     PerformanceManager,
@@ -306,3 +306,131 @@ def test_factory_sets_transformer_features_to_prefixed_inputs_and_features_out_t
         if idx + 1 < len(ts):
             assert t.features_out == ts[idx + 1].features
         assert t.features == expected_in
+
+
+class TestZeroInflationHandling:
+    @pytest.fixture
+    def zero_inflated_data(self):
+        """Create zero-inflated data with ~37.7% zeros."""
+        np.random.seed(42)
+        n = 1000
+        zeros = np.zeros(377)
+        nonzeros = np.random.exponential(scale=2, size=n - 377)
+        raw = np.concatenate([zeros, nonzeros])
+        np.random.shuffle(raw)
+        return raw
+
+    @pytest.mark.parametrize("frame", ["pd", "pl"])
+    def test_performance_manager_detects_zero_inflation(self, frame, zero_inflated_data):
+        """Test that PerformanceManager auto-detects zero-inflated distributions."""
+        df = _make_native_df(frame, {"x": zero_inflated_data})
+
+        pm = PerformanceManager(
+            features=["x"],
+            transformer_names=["symmetric", "partial_standard_scaler", "min_max"],
+            prefix="performance__",
+            performance_column="perf",
+            zero_inflation_threshold=0.15,
+        )
+
+        pm.fit(df)
+
+        # Should have switched to quantile scaler
+        assert pm._using_quantile_scaler is True
+        assert isinstance(pm.transformers[-1], QuantilePerformanceScaler)
+
+    @pytest.mark.parametrize("frame", ["pd", "pl"])
+    def test_performance_manager_uses_standard_pipeline_for_normal_data(self, frame):
+        """Test that PerformanceManager uses standard pipeline for non-zero-inflated data."""
+        np.random.seed(42)
+        # Normal distribution - no zero inflation
+        data = np.random.normal(loc=0.5, scale=0.1, size=1000)
+        df = _make_native_df(frame, {"x": data})
+
+        pm = PerformanceManager(
+            features=["x"],
+            transformer_names=["symmetric", "partial_standard_scaler", "min_max"],
+            prefix="performance__",
+            performance_column="perf",
+            zero_inflation_threshold=0.15,
+        )
+
+        pm.fit(df)
+
+        # Should NOT have switched to quantile scaler
+        assert pm._using_quantile_scaler is False
+        assert isinstance(pm.transformers[-1], MinMaxTransformer)
+
+    @pytest.mark.parametrize("frame", ["pd", "pl"])
+    def test_zero_inflation_output_properties(self, frame, zero_inflated_data):
+        """Test that zero-inflated output has correct properties."""
+        df = _make_native_df(frame, {"x": zero_inflated_data})
+
+        pm = PerformanceManager(
+            features=["x"],
+            transformer_names=["symmetric", "partial_standard_scaler", "min_max"],
+            prefix="performance__",
+            performance_column="perf",
+            zero_inflation_threshold=0.15,
+        )
+
+        result = pm.fit_transform(df)
+        result_nw = nw.from_native(result)
+        scaled = result_nw["performance__perf"].to_numpy()
+
+        # 1. All zeros should have the same scaled value (the midpoint of zero mass)
+        is_zero = np.abs(zero_inflated_data) < 1e-10
+        zero_scaled_values = scaled[is_zero]
+        assert np.allclose(zero_scaled_values, zero_scaled_values[0], atol=1e-10)
+
+        # 2. Zeros should have lower values than non-zeros (on average)
+        is_nonzero = ~is_zero
+        assert np.mean(scaled[is_zero]) < np.mean(scaled[is_nonzero])
+
+        # 3. Mean should be approximately 0.5
+        assert abs(np.mean(scaled) - 0.5) < 0.02
+
+        # 4. Monotonicity preserved
+        order = np.argsort(zero_inflated_data)
+        sorted_scaled = scaled[order]
+        assert np.all(np.diff(sorted_scaled) >= -1e-10)
+
+        # 5. Bounded [0, 1] (with clipping tolerance)
+        assert np.all((scaled >= pm.min_value) & (scaled <= pm.max_value))
+
+    @pytest.mark.parametrize("frame", ["pd", "pl"])
+    def test_disable_zero_inflation_detection(self, frame, zero_inflated_data):
+        """Test that zero_inflation_threshold=0 disables detection."""
+        df = _make_native_df(frame, {"x": zero_inflated_data})
+
+        pm = PerformanceManager(
+            features=["x"],
+            transformer_names=["symmetric", "partial_standard_scaler", "min_max"],
+            prefix="performance__",
+            performance_column="perf",
+            zero_inflation_threshold=0,  # Disable detection
+        )
+
+        pm.fit(df)
+
+        # Should NOT have switched to quantile scaler
+        assert pm._using_quantile_scaler is False
+
+    @pytest.mark.parametrize("frame", ["pd", "pl"])
+    def test_performance_weights_manager_zero_inflation(self, frame, zero_inflated_data):
+        """Test that PerformanceWeightsManager also handles zero inflation."""
+        df = _make_native_df(frame, {"feat_a": zero_inflated_data})
+
+        weights = [ColumnWeight(name="feat_a", weight=1.0)]
+        manager = PerformanceWeightsManager(
+            weights=weights,
+            # Use default transformers (None) to enable zero inflation detection
+            transformer_names=None,
+            prefix="",
+            zero_inflation_threshold=0.15,
+        )
+
+        manager.fit(df)
+
+        # Should have switched to quantile scaler
+        assert manager._using_quantile_scaler is True

tests/performance_transformers/test_performances_transformers.py

@@ -1,3 +1,4 @@
+import numpy as np
 import pandas as pd
 import polars as pl
 import pytest
@@ -6,6 +7,7 @@ from sklearn.linear_model import LinearRegression
 
 from spforge.performance_transformers import (
     DiminishingValueTransformer,
+    QuantilePerformanceScaler,
     SymmetricDistributionTransformer,
 )
 from spforge.performance_transformers._performances_transformers import (
@@ -355,3 +357,197 @@ def test_symmetric_distribution_transformer_with_granularity_fit_transform():
         abs(transformed_df.loc[lambda x: x.position == "SG"]["performance"].skew())
         < transformer.skewness_allowed
     )
+
+
+class TestQuantilePerformanceScaler:
+    @pytest.fixture
+    def zero_inflated_data(self):
+        """Create zero-inflated data with ~37.7% zeros."""
+        np.random.seed(42)
+        n = 1000
+        # ~37.7% zeros
+        zeros = np.zeros(377)
+        # Non-zeros from exponential distribution
+        nonzeros = np.random.exponential(scale=2, size=n - 377)
+        raw = np.concatenate([zeros, nonzeros])
+        np.random.shuffle(raw)
+        return raw
+
+    @pytest.mark.parametrize("df_type", [pd.DataFrame, pl.DataFrame])
+    def test_zeros_map_to_midpoint(self, df_type, zero_inflated_data):
+        """Test that zeros map to π/2 (midpoint of zero probability mass)."""
+        df = df_type({"performance": zero_inflated_data})
+
+        scaler = QuantilePerformanceScaler(features=["performance"], prefix="")
+        transformed = scaler.fit_transform(df)
+
+        if isinstance(transformed, pd.DataFrame):
+            scaled = transformed["performance"].values
+        else:
+            scaled = transformed["performance"].to_numpy()
+
+        pi = scaler._zero_proportion["performance"]
+        is_zero = np.abs(zero_inflated_data) < 1e-10
+
+        # Zeros should map to π/2
+        assert np.allclose(scaled[is_zero], pi / 2, atol=1e-10)
+
+    @pytest.mark.parametrize("df_type", [pd.DataFrame, pl.DataFrame])
+    def test_mean_approximately_half(self, df_type, zero_inflated_data):
+        """Test that mean ≈ 0.5."""
+        df = df_type({"performance": zero_inflated_data})
+
+        scaler = QuantilePerformanceScaler(features=["performance"], prefix="")
+        transformed = scaler.fit_transform(df)
+
+        if isinstance(transformed, pd.DataFrame):
+            scaled = transformed["performance"].values
+        else:
+            scaled = transformed["performance"].to_numpy()
+
+        # Mean should be approximately 0.5
+        assert abs(np.mean(scaled) - 0.5) < 0.02
+
+    @pytest.mark.parametrize("df_type", [pd.DataFrame, pl.DataFrame])
+    def test_monotonicity_preserved(self, df_type, zero_inflated_data):
+        """Test that monotonicity is preserved (sorted input → sorted output)."""
+        df = df_type({"performance": zero_inflated_data})
+
+        scaler = QuantilePerformanceScaler(features=["performance"], prefix="")
+        transformed = scaler.fit_transform(df)
+
+        if isinstance(transformed, pd.DataFrame):
+            scaled = transformed["performance"].values
+        else:
+            scaled = transformed["performance"].to_numpy()
+
+        # Check monotonicity: if we sort the raw data, the scaled values should also be sorted
+        order = np.argsort(zero_inflated_data)
+        sorted_scaled = scaled[order]
+        # Allow for tiny numerical errors
+        assert np.all(np.diff(sorted_scaled) >= -1e-10)
+
+    @pytest.mark.parametrize("df_type", [pd.DataFrame, pl.DataFrame])
+    def test_bounded_zero_one(self, df_type, zero_inflated_data):
+        """Test that output is bounded [0, 1]."""
+        df = df_type({"performance": zero_inflated_data})
+
+        scaler = QuantilePerformanceScaler(features=["performance"], prefix="")
+        transformed = scaler.fit_transform(df)
+
+        if isinstance(transformed, pd.DataFrame):
+            scaled = transformed["performance"].values
+        else:
+            scaled = transformed["performance"].to_numpy()
+
+        assert np.all((scaled >= 0) & (scaled <= 1))
+
+    @pytest.mark.parametrize("df_type", [pd.DataFrame, pl.DataFrame])
+    def test_nonzeros_span_pi_to_one(self, df_type, zero_inflated_data):
+        """Test that non-zeros map to range (π, 1)."""
+        df = df_type({"performance": zero_inflated_data})
+
+        scaler = QuantilePerformanceScaler(features=["performance"], prefix="")
+        transformed = scaler.fit_transform(df)
+
+        if isinstance(transformed, pd.DataFrame):
+            scaled = transformed["performance"].values
+        else:
+            scaled = transformed["performance"].to_numpy()
+
+        pi = scaler._zero_proportion["performance"]
+        is_nonzero = np.abs(zero_inflated_data) >= 1e-10
+
+        # Non-zeros should be >= π
+        assert np.all(scaled[is_nonzero] >= pi - 1e-10)
+        # Non-zeros should be <= 1
+        assert np.all(scaled[is_nonzero] <= 1 + 1e-10)
+
+    def test_with_prefix(self):
+        """Test that prefix is applied correctly."""
+        np.random.seed(42)
+        raw = np.concatenate([np.zeros(50), np.random.exponential(2, 50)])
+        df = pd.DataFrame({"feat": raw})
+
+        scaler = QuantilePerformanceScaler(features=["feat"], prefix="scaled_")
+        transformed = scaler.fit_transform(df)
+
+        assert "scaled_feat" in transformed.columns
+        assert scaler.features_out == ["scaled_feat"]
+
+    def test_multiple_features(self):
+        """Test that multiple features are handled correctly."""
+        np.random.seed(42)
+        raw_a = np.concatenate([np.zeros(50), np.random.exponential(2, 50)])
+        raw_b = np.concatenate([np.zeros(30), np.random.exponential(3, 70)])
+        df = pd.DataFrame({"a": raw_a, "b": raw_b})
+
+        scaler = QuantilePerformanceScaler(features=["a", "b"], prefix="")
+        transformed = scaler.fit_transform(df)
+
+        assert "a" in transformed.columns
+        assert "b" in transformed.columns
+
+        # Both should have mean ≈ 0.5
+        assert abs(transformed["a"].mean() - 0.5) < 0.05
+        assert abs(transformed["b"].mean() - 0.5) < 0.05
+
+    def test_all_zeros(self):
+        """Test edge case: all values are zero (π=1)."""
+        df = pd.DataFrame({"x": [0.0, 0.0, 0.0, 0.0, 0.0]})
+
+        scaler = QuantilePerformanceScaler(features=["x"], prefix="")
+        transformed = scaler.fit_transform(df)
+
+        # π=1, so all values should map to π/2 = 0.5
+        assert np.allclose(transformed["x"].values, 0.5)
+        assert scaler._zero_proportion["x"] == 1.0
+
+    def test_no_zeros(self):
+        """Test edge case: no zeros (π=0)."""
+        np.random.seed(42)
+        df = pd.DataFrame({"x": np.random.exponential(2, 100) + 0.1})  # All positive
+
+        scaler = QuantilePerformanceScaler(features=["x"], prefix="")
+        transformed = scaler.fit_transform(df)
+
+        # π=0, so values should span (0, 1) via quantiles
+        assert scaler._zero_proportion["x"] == 0.0
+        assert transformed["x"].min() >= 0
+        assert transformed["x"].max() <= 1
+        # Mean should still be ~0.5
+        assert abs(transformed["x"].mean() - 0.5) < 0.05
+
+    def test_nan_handling(self):
+        """Test that NaN values are preserved in output."""
+        df = pd.DataFrame({"x": [0.0, 1.0, np.nan, 2.0, 0.0, np.nan, 3.0]})
+
+        scaler = QuantilePerformanceScaler(features=["x"], prefix="")
+        transformed = scaler.fit_transform(df)
+
+        # NaN positions should remain NaN
+        assert np.isnan(transformed["x"].iloc[2])
+        assert np.isnan(transformed["x"].iloc[5])
+
+        # Non-NaN values should be valid
+        non_nan_mask = ~np.isnan(transformed["x"].values)
+        assert np.all((transformed["x"].values[non_nan_mask] >= 0) &
+                      (transformed["x"].values[non_nan_mask] <= 1))
+
+    def test_single_unique_nonzero(self):
+        """Test edge case: single unique non-zero value."""
+        df = pd.DataFrame({"x": [0.0, 0.0, 5.0, 5.0, 0.0, 5.0]})
+
+        scaler = QuantilePerformanceScaler(features=["x"], prefix="")
+        transformed = scaler.fit_transform(df)
+
+        # Should still work - zeros map to π/2, non-zeros to (π, 1)
+        pi = scaler._zero_proportion["x"]
+        is_zero = df["x"] == 0
+
+        # Zeros should map to π/2
+        assert np.allclose(transformed["x"].values[is_zero.values], pi / 2)
+
+        # Non-zeros should all map to same value (since they're all equal)
+        nonzero_values = transformed["x"].values[~is_zero.values]
+        assert np.allclose(nonzero_values, nonzero_values[0])

tests/ratings/test_player_rating_generator.py

@@ -1951,9 +1951,11 @@ def test_fit_transform__player_rating_difference_from_team_projected_feature(bas
     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)
+    # Verify diff = player - team (vectorized)
+    max_diff = result.select(
+        (pl.col(diff_col) - (pl.col(player_col) - pl.col(team_col))).abs().max()
+    ).item()
+    assert max_diff < 1e-9
 
 
 def test_fit_transform__start_league_quantile_uses_existing_player_ratings(base_cn):
@@ -2909,3 +2911,30 @@ def test_fit_transform_null_perf_with_use_off_def_split_false__no_crash(base_cn)
     # TypeError: float() argument must be a string or a number, not 'NoneType'
     result = gen.fit_transform(df)
     assert result is not None
+
+
+def test_player_opponent_mean_projected_feature(base_cn, sample_df):
+    """Test that PLAYER_OPPONENT_MEAN_PROJECTED outputs mean of player and opponent team ratings."""
+    gen = PlayerRatingGenerator(
+        performance_column="perf",
+        column_names=base_cn,
+        auto_scale_performance=True,
+        features_out=[
+            RatingKnownFeatures.PLAYER_RATING,
+            RatingKnownFeatures.OPPONENT_RATING_PROJECTED,
+            RatingKnownFeatures.PLAYER_OPPONENT_MEAN_PROJECTED,
+        ],
+    )
+    result = gen.fit_transform(sample_df)
+
+    # Verify column exists
+    assert "player_opponent_mean_projected_perf" in result.columns
+
+    # Verify it's the mean of player_rating and opponent_rating_projected (vectorized)
+    expected = (
+        pl.col("player_rating_perf") + pl.col("opponent_rating_projected_perf")
+    ) / 2
+    diff = result.select(
+        (pl.col("player_opponent_mean_projected_perf") - expected).abs().max()
+    ).item()
+    assert diff < 1e-6, f"Max difference from expected mean: {diff}"