spforge 0.8.11__tar.gz → 0.8.14__tar.gz

{spforge-0.8.11/spforge.egg-info → spforge-0.8.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spforge
-Version: 0.8.11
+Version: 0.8.14
 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.11 → spforge-0.8.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spforge"
-version = "0.8.11"
+version = "0.8.14"
 description = "A flexible framework for generating features, ratings, and building machine learning or other models for training and inference on sports data."
 readme = "README.md"
 requires-python = ">=3.11"

{spforge-0.8.11 → spforge-0.8.14}/spforge/autopipeline.py

@@ -195,6 +195,40 @@ def lgbm_in_root(root) -> bool:
     return any(_is_lightgbm_estimator(obj) for obj in _walk_objects(root))
 
 
+def _get_importance_estimator(estimator) -> tuple[Any, str] | None:
+    """Recursively find innermost estimator with feature_importances_ or coef_."""
+    if hasattr(estimator, "feature_importances_"):
+        inner = _get_importance_estimator_inner(estimator)
+        if inner is not None:
+            return inner
+        return (estimator, "feature_importances_")
+
+    if hasattr(estimator, "coef_"):
+        inner = _get_importance_estimator_inner(estimator)
+        if inner is not None:
+            return inner
+        return (estimator, "coef_")
+
+    return _get_importance_estimator_inner(estimator)
+
+
+def _get_importance_estimator_inner(estimator) -> tuple[Any, str] | None:
+    """Check wrapped estimators for importance attributes."""
+    # Check estimator_ (sklearn fitted wrapper convention)
+    if hasattr(estimator, "estimator_") and estimator.estimator_ is not None:
+        result = _get_importance_estimator(estimator.estimator_)
+        if result is not None:
+            return result
+
+    # Check _est (GroupByEstimator convention)
+    if hasattr(estimator, "_est") and estimator._est is not None:
+        result = _get_importance_estimator(estimator._est)
+        if result is not None:
+            return result
+
+    return None
+
+
 class AutoPipeline(BaseEstimator):
     def __init__(
         self,
@@ -627,3 +661,107 @@ class AutoPipeline(BaseEstimator):
                 all_features.append(ctx)
 
         return all_features
+
+    def _get_estimator_feature_names(self) -> list[str]:
+        """Get feature names as seen by the final estimator after all transformations."""
+        pre_out = list(self.sklearn_pipeline.named_steps["pre"].get_feature_names_out())
+
+        # Remove context columns dropped by "final" step
+        final_step = self.sklearn_pipeline.named_steps["final"]
+        drop_cols = final_step.kw_args.get("drop_cols", set()) if final_step.kw_args else set()
+        features = [f for f in pre_out if f not in drop_cols]
+
+        # Remove granularity columns (dropped by GroupByEstimator)
+        granularity_set = set(self.granularity)
+        features = [f for f in features if f not in granularity_set]
+
+        # Remove context features (used by wrapper estimators, not inner model)
+        context_set = set(self.context_feature_names)
+        features = [f for f in features if f not in context_set]
+
+        return features
+
+    def _resolve_importance_feature_names(self, estimator, n_features: int) -> list[str]:
+        names = None
+        if hasattr(estimator, "feature_names_in_") and estimator.feature_names_in_ is not None:
+            names = list(estimator.feature_names_in_)
+        elif hasattr(estimator, "feature_name_") and estimator.feature_name_ is not None:
+            names = list(estimator.feature_name_)
+        elif hasattr(estimator, "feature_names_") and estimator.feature_names_ is not None:
+            names = list(estimator.feature_names_)
+        if names is None:
+            names = self._get_estimator_feature_names()
+        if len(names) != n_features:
+            raise ValueError(
+                f"Feature names length ({len(names)}) does not match importances length ({n_features})."
+            )
+        return names
+
+    @property
+    def feature_importances_(self) -> pd.DataFrame:
+        """Get feature importances from the fitted estimator.
+
+        Returns a DataFrame with columns ["feature", "importance"] sorted by
+        absolute importance descending. Works with tree-based models
+        (feature_importances_) and linear models (coef_).
+        """
+        if self.sklearn_pipeline is None:
+            raise RuntimeError("Pipeline not fitted. Call fit() first.")
+
+        est = self.sklearn_pipeline.named_steps["est"]
+        result = _get_importance_estimator(est)
+
+        if result is None:
+            raise RuntimeError(
+                "Estimator does not support feature importances. "
+                "Requires feature_importances_ or coef_ attribute."
+            )
+
+        inner_est, attr_name = result
+        raw = getattr(inner_est, attr_name)
+
+        if attr_name == "coef_":
+            # Linear models: use absolute value of coefficients
+            if raw.ndim == 2:
+                # Multi-class: average absolute values across classes
+                importances = np.abs(raw).mean(axis=0)
+            else:
+                importances = np.abs(raw)
+        else:
+            importances = raw
+
+        feature_names = self._get_estimator_feature_names()
+
+        df = pd.DataFrame({"feature": feature_names, "importance": importances})
+        df = df.sort_values("importance", ascending=False, key=abs).reset_index(drop=True)
+        return df
+
+    @property
+    def feature_importance_names(self) -> dict[str, float]:
+        """Map deepest estimator feature names to importances."""
+        if self.sklearn_pipeline is None:
+            raise RuntimeError("Pipeline not fitted. Call fit() first.")
+
+        est = self.sklearn_pipeline.named_steps["est"]
+        result = _get_importance_estimator(est)
+
+        if result is None:
+            raise RuntimeError(
+                "Estimator does not support feature importances. "
+                "Requires feature_importances_ or coef_ attribute."
+            )
+
+        inner_est, attr_name = result
+        raw = getattr(inner_est, attr_name)
+
+        if attr_name == "coef_":
+            if raw.ndim == 2:
+                importances = np.abs(raw).mean(axis=0)
+            else:
+                importances = np.abs(raw)
+        else:
+            importances = raw
+
+        importances = np.asarray(importances)
+        feature_names = self._resolve_importance_feature_names(inner_est, len(importances))
+        return dict(zip(feature_names, importances.tolist()))

{spforge-0.8.11 → spforge-0.8.14/spforge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spforge
-Version: 0.8.11
+Version: 0.8.14
 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.11 → spforge-0.8.14}/tests/test_autopipeline.py

@@ -551,3 +551,175 @@ def test_autopipeline_is_picklable_after_fit():
     model.fit(df, y)
 
     pickle.dumps(model)
+
+
+# --- Feature Importances Tests ---
+
+
+def test_feature_importances__tree_model():
+    from sklearn.ensemble import RandomForestRegressor
+
+    df = pd.DataFrame(
+        {
+            "num1": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
+            "num2": [10.0, 20.0, 30.0, 40.0, 50.0, 60.0],
+            "cat1": ["a", "b", "a", "b", "a", "b"],
+        }
+    )
+    y = pd.Series([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], name="y")
+
+    model = AutoPipeline(
+        estimator=RandomForestRegressor(n_estimators=5, random_state=42),
+        estimator_features=["num1", "num2", "cat1"],
+        categorical_handling="ordinal",
+    )
+    model.fit(df, y)
+
+    importances = model.feature_importances_
+
+    assert isinstance(importances, pd.DataFrame)
+    assert list(importances.columns) == ["feature", "importance"]
+    assert len(importances) == 3
+    assert set(importances["feature"].tolist()) == {"num1", "num2", "cat1"}
+    assert all(importances["importance"] >= 0)
+
+
+def test_feature_importances__linear_model():
+    df = pd.DataFrame(
+        {
+            "num1": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0],
+            "num2": [10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0],
+        }
+    )
+    y = pd.Series([0, 1, 0, 1, 0, 1, 0, 1], name="y")
+
+    model = AutoPipeline(
+        estimator=LogisticRegression(max_iter=1000),
+        estimator_features=["num1", "num2"],
+        scale_features=True,
+    )
+    model.fit(df, y)
+
+    importances = model.feature_importances_
+
+    assert isinstance(importances, pd.DataFrame)
+    assert list(importances.columns) == ["feature", "importance"]
+    assert len(importances) == 2
+    assert set(importances["feature"].tolist()) == {"num1", "num2"}
+    assert all(importances["importance"] >= 0)
+
+
+def test_feature_importances__not_fitted_raises():
+    model = AutoPipeline(
+        estimator=LinearRegression(),
+        estimator_features=["x"],
+    )
+
+    with pytest.raises(RuntimeError, match="Pipeline not fitted"):
+        _ = model.feature_importances_
+
+
+def test_feature_importances__unsupported_estimator_raises():
+    df = pd.DataFrame({"x": [1.0, 2.0, 3.0, 4.0]})
+    y = pd.Series([1.0, 2.0, 3.0, 4.0], name="y")
+
+    model = AutoPipeline(
+        estimator=DummyRegressor(),
+        estimator_features=["x"],
+    )
+    model.fit(df, y)
+
+    with pytest.raises(RuntimeError, match="does not support feature importances"):
+        _ = model.feature_importances_
+
+
+def test_feature_importances__with_sklearn_enhancer():
+    from sklearn.ensemble import RandomForestRegressor
+
+    df = pd.DataFrame(
+        {
+            "num1": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
+            "num2": [10.0, 20.0, 30.0, 40.0, 50.0, 60.0],
+            "start_date": ["2022-01-01", "2022-01-02", "2022-01-03", "2022-01-04", "2022-01-05", "2022-01-06"],
+        }
+    )
+    y = pd.Series([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], name="y")
+
+    inner = RandomForestRegressor(n_estimators=5, random_state=42)
+    enhancer = SkLearnEnhancerEstimator(
+        estimator=inner,
+        date_column="start_date",
+        day_weight_epsilon=0.1,
+    )
+
+    model = AutoPipeline(
+        estimator=enhancer,
+        estimator_features=["num1", "num2"],
+    )
+    model.fit(df, y)
+
+    importances = model.feature_importances_
+
+    assert isinstance(importances, pd.DataFrame)
+    assert list(importances.columns) == ["feature", "importance"]
+    assert len(importances) == 2
+    assert set(importances["feature"].tolist()) == {"num1", "num2"}
+
+
+def test_feature_importances__onehot_features():
+    from sklearn.ensemble import RandomForestRegressor
+
+    df = pd.DataFrame(
+        {
+            "num1": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
+            "cat1": ["a", "b", "c", "a", "b", "c"],
+        }
+    )
+    y = pd.Series([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], name="y")
+
+    model = AutoPipeline(
+        estimator=RandomForestRegressor(n_estimators=5, random_state=42),
+        estimator_features=["num1", "cat1"],
+        categorical_handling="onehot",
+    )
+    model.fit(df, y)
+
+    importances = model.feature_importances_
+
+    assert isinstance(importances, pd.DataFrame)
+    assert list(importances.columns) == ["feature", "importance"]
+    # Should have expanded features: num1 + cat1_a, cat1_b, cat1_c
+    assert len(importances) == 4
+    assert "num1" in importances["feature"].tolist()
+    assert any("cat1_" in f for f in importances["feature"].tolist())
+
+
+def test_feature_importance_names__granularity_uses_deep_feature_names():
+    from sklearn.ensemble import RandomForestRegressor
+
+    df = pd.DataFrame(
+        {
+            "gameid": ["g1", "g1", "g2", "g2"],
+            "num1": [1.0, 2.0, 3.0, 4.0],
+            "num2": [10.0, 20.0, 30.0, 40.0],
+        }
+    )
+    y = pd.Series([1.0, 2.0, 3.0, 4.0], name="y")
+
+    model = AutoPipeline(
+        estimator=RandomForestRegressor(n_estimators=5, random_state=42),
+        estimator_features=["gameid", "num1", "num2"],
+        predictor_transformers=[AddConstantPredictionTransformer(col_name="const_pred")],
+        granularity=["gameid"],
+        categorical_features=["gameid"],
+        categorical_handling="ordinal",
+        remainder="drop",
+    )
+    model.fit(df, y)
+
+    names = model.feature_importance_names
+
+    inner = _inner_estimator(model)
+    assert list(names.keys()) == list(inner.feature_names_in_)
+    assert "gameid" not in names
+    assert "const_pred" in names