p2predict 0.9.0__py3-none-any.whl

p2predict/model_evals.py

@@ -0,0 +1,36 @@
+import numpy as np
+from sklearn.inspection import permutation_importance
+from sklearn.metrics import mean_absolute_error, r2_score
+
+
+def evaluate_model(X_test, y_test, model):
+    predictions = model.predict(X_test)
+    mae = mean_absolute_error(y_test, predictions)
+    r2 = r2_score(y_test, predictions)
+
+    # Replace the prior (and incorrect) two-sample t-test with a
+    # residual-mean test: under a well-calibrated model, residuals should be
+    # centered on zero. Reject => systematic bias.
+    residuals = np.asarray(y_test) - np.asarray(predictions)
+    rmse = float(np.sqrt(np.mean(residuals ** 2)))
+    n = len(residuals)
+    if n > 1 and residuals.std(ddof=1) > 0:
+        from scipy import stats
+        _, p_value = stats.ttest_1samp(residuals, 0.0)
+    else:
+        p_value = 1.0
+
+    return mae, r2, p_value, rmse
+
+
+def get_column_statistics(data, feature_columns):
+    return {
+        col: {"skewness": data[col].skew(), "kurtosis": data[col].kurt()}
+        for col in feature_columns
+    }
+
+
+def calculate_feature_importance(X, y, model):
+    result = permutation_importance(model, X, y, n_repeats=10, random_state=0, n_jobs=-1)
+    total = sum(result.importances_mean) or 1.0
+    return result.importances_mean / total

p2predict/model_utils.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from sklearn.compose import TransformedTargetRegressor
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import OneHotEncoder, OrdinalEncoder, TargetEncoder
+
+from p2predict.explain import Explanation
+from p2predict.whatif import WhatIfResult, interaction_is_material
+
+
+def inner_pipeline(model):
+    """Unwrap a TransformedTargetRegressor to get the inner Pipeline."""
+    return model.regressor_ if isinstance(model, TransformedTargetRegressor) else model
+
+
+def extract_feature_info(pipeline):
+    """Return (feature_types, all_categories) from a fitted preprocessor.
+
+    Works with OneHotEncoder, OrdinalEncoder, and TargetEncoder pipelines.
+    """
+    preprocessor = pipeline.named_steps["preprocessor"]
+    feature_types: dict[str, str] = {}
+    all_categories: dict[str, list] = {}
+
+    for name, transformer, columns in preprocessor.transformers_:
+        if name == "num":
+            feature_types.update({col: "Numerical" for col in columns})
+        elif name == "cat":
+            feature_types.update({col: "Categorical" for col in columns})
+
+            encoder = transformer
+            if isinstance(transformer, Pipeline):
+                if "onehot" in transformer.named_steps:
+                    encoder = transformer.named_steps["onehot"]
+                elif "target" in transformer.named_steps:
+                    encoder = transformer.named_steps["target"]
+
+            if isinstance(encoder, (OneHotEncoder, OrdinalEncoder, TargetEncoder)) and hasattr(
+                encoder, "categories_"
+            ):
+                all_categories = {
+                    col: cat.tolist()
+                    for col, cat in zip(columns, encoder.categories_)
+                }
+
+    return feature_types, all_categories
+
+
+def coerce_features(features_df, feature_types):
+    """Coerce numerical columns to numeric dtype."""
+    for col, kind in feature_types.items():
+        if col in features_df.columns and kind == "Numerical":
+            features_df[col] = pd.to_numeric(features_df[col], errors="coerce")
+    return features_df
+
+
+def interval_to_dicts(intervals) -> list[dict]:
+    """Serialize a list of IntervalResult to JSON-ready dicts.
+
+    Each dict carries the raw bounds AND a per-part trust read the agent can
+    quote: ``reliability`` ('trust' | 'caution' | 'quote') and a plain
+    ``say_to_user`` sentence derived from how wide the band is relative to the
+    prediction. Lead with ``say_to_user``; don't make the user infer trust from
+    the bare low/high numbers.
+    """
+    from p2predict.quality import interval_reliability, interval_say_to_user
+
+    out = []
+    for ir in intervals:
+        low, pred, high = float(ir.low), float(ir.prediction), float(ir.high)
+        out.append({
+            "low": low,
+            "prediction": pred,
+            "high": high,
+            "band": ir.band,
+            "reliability": interval_reliability(low, pred, high),
+            "say_to_user": interval_say_to_user(low, pred, high),
+        })
+    return out
+
+
+def explanation_to_dict(explanation: Explanation) -> dict:
+    """Serialize an Explanation to a JSON-ready dict.
+
+    The dict carries TWO views of the same attribution:
+
+      - A business view the agent can quote to a category manager verbatim:
+        ``starting_point`` (the baseline price every part starts from) and
+        ``price_drivers`` (each spec/supplier's effect in dollars AND percent,
+        biggest mover first). This is the view to lead with.
+      - The technical view (``baseline``, ``contributions``,
+        ``multiplicative_factors``, ``dollar_attribution``, ``residual``) for
+        callers that need the raw SHAP numbers. Do NOT surface these key names
+        to a procurement user.
+    """
+    out = {
+        "baseline": float(explanation.baseline),
+        "prediction": float(explanation.prediction),
+        "log_target": bool(explanation.log_target),
+        "contributions": [
+            {"feature": k, "value": float(v)}
+            for k, v in sorted(
+                explanation.contributions.items(), key=lambda kv: abs(kv[1]), reverse=True
+            )
+        ],
+        "residual": float(explanation.residual),
+    }
+    if explanation.log_target and explanation.multiplicative_factors is not None:
+        out["multiplicative_factors"] = [
+            {"feature": k, "factor": float(v)}
+            for k, v in sorted(
+                explanation.multiplicative_factors.items(),
+                key=lambda kv: abs(np.log(kv[1])) if kv[1] > 0 else 0.0,
+                reverse=True,
+            )
+        ]
+        out["dollar_attribution"] = (
+            [
+                {"feature": k, "value": float(v)}
+                for k, v in sorted(
+                    explanation.dollar_attribution.items(),
+                    key=lambda kv: abs(kv[1]),
+                    reverse=True,
+                )
+            ]
+            if explanation.dollar_attribution is not None
+            else None
+        )
+    else:
+        out["multiplicative_factors"] = None
+        out["dollar_attribution"] = None
+
+    out["starting_point"] = _business_starting_point(explanation)
+    out["price_drivers"] = _business_price_drivers(explanation)
+    return out
+
+
+def _business_starting_point(explanation: Explanation) -> float:
+    """The baseline price every part 'starts from' before its specs apply, in
+    dollars (price space for log-target models)."""
+    if explanation.log_target and explanation.baseline_price is not None:
+        return float(explanation.baseline_price)
+    return float(explanation.baseline)
+
+
+def _business_price_drivers(explanation: Explanation) -> list[dict]:
+    """A single plain-language attribution list the agent can quote directly.
+
+    Each entry is one spec/supplier and its effect on the price, expressed in
+    BOTH dollars and percent, biggest absolute mover first:
+        {"driver": "Supplier ADI", "effect_dollars": 0.72, "effect_pct": 18.0}
+    Works for additive and log-target models alike, so the caller never has to
+    branch on the model's internal scale.
+    """
+    drivers: list[dict] = []
+    if explanation.log_target and explanation.multiplicative_factors is not None:
+        dollars = explanation.dollar_attribution or {}
+        for feature, factor in explanation.multiplicative_factors.items():
+            drivers.append({
+                "driver": feature,
+                "effect_dollars": (
+                    round(float(dollars[feature]), 4) if feature in dollars else None
+                ),
+                "effect_pct": round((float(factor) - 1.0) * 100.0, 1),
+            })
+    else:
+        # Additive model: contributions are already dollars; percent is the
+        # share of the baseline each driver moves the price by.
+        base = float(explanation.baseline) or 1.0
+        for feature, value in explanation.contributions.items():
+            drivers.append({
+                "driver": feature,
+                "effect_dollars": round(float(value), 4),
+                "effect_pct": round(float(value) / base * 100.0, 1),
+            })
+    drivers.sort(key=lambda d: abs(d["effect_dollars"] or 0.0), reverse=True)
+    return drivers
+
+
+def whatif_to_dict(result: WhatIfResult) -> dict:
+    """Serialize a WhatIfResult to a JSON-ready dict.
+
+    ``summary`` is the plain-language headline the agent can quote to a category
+    manager ("Switching to Microchip saves $0.41 per part, -12%"); the
+    remaining keys are the technical detail behind it. Lead with ``summary``.
+    """
+    delta = float(result.delta)
+    direction = "no change"
+    if delta > 0:
+        direction = "adds"
+    elif delta < 0:
+        direction = "saves"
+    return {
+        "summary": {
+            "direction": direction,  # "adds" | "saves" | "no change"
+            "effect_dollars": round(abs(delta), 4),
+            "effect_pct": round(abs(float(result.delta_pct)), 1),
+            "new_price": round(float(result.counterfactual_prediction), 4),
+            "old_price": round(float(result.base_prediction), 4),
+        },
+        "changes": {
+            col: {"from": base_val, "to": cf_val}
+            for col, (base_val, cf_val) in result.changes.items()
+        },
+        "base_prediction": float(result.base_prediction),
+        "counterfactual_prediction": float(result.counterfactual_prediction),
+        "delta": float(result.delta),
+        "delta_pct": float(result.delta_pct),
+        "log_target": bool(result.log_target),
+        "multiplicative_factor": (
+            float(result.multiplicative_factor)
+            if result.multiplicative_factor is not None
+            else None
+        ),
+        "changed_contributions": [
+            {"feature": k, "value": float(v)}
+            for k, v in sorted(
+                result.changed_contributions.items(), key=lambda kv: abs(kv[1]), reverse=True
+            )
+        ],
+        "interaction_contribution": float(result.interaction_contribution),
+        "interaction_is_material": bool(interaction_is_material(result)),
+        "base_interval": (
+            {"low": float(result.base_interval.low), "high": float(result.base_interval.high)}
+            if result.base_interval is not None
+            else None
+        ),
+        "cf_interval": (
+            {"low": float(result.cf_interval.low), "high": float(result.cf_interval.high)}
+            if result.cf_interval is not None
+            else None
+        ),
+    }

p2predict/outliers.py

@@ -0,0 +1,234 @@
+"""Outlier detection and handling for both the target and the feature columns.
+
+Procurement data routinely contains rush orders, one-off spot buys, and
+data-entry errors (a `Weight` of `100000` when someone meant `100`, a unit
+mix-up between kg and g). Both kinds quietly distort a learned cost model:
+target outliers warp R² and inflate intervals, feature outliers pull the
+model's response surface around the bad rows.
+
+This module flags both via the same Tukey IQR rule and applies one of four
+policies.
+
+Policies
+--------
+keep        Flag only, change nothing.
+warn        Flag and warn (default). Same as keep, but with a console
+            message so the user actually finds out.
+drop        Remove flagged rows before training.
+winsorize   Cap flagged values at the IQR bounds (preserves row count).
+
+Two surfaces
+------------
+1. ``apply_outlier_policy(data, target_column, policy, multiplier)``
+   Target-side. Inspects ``data[target_column]`` only. Has been around
+   since v0.3.
+
+2. ``apply_feature_outlier_policy(data, feature_columns, policy, multiplier)``
+   Feature-side. Inspects every *numerical* column in ``feature_columns``
+   independently. ``drop`` removes any row that has an outlier in any
+   feature column; ``winsorize`` caps each column at its own IQR bounds
+   independently. Categorical columns are silently ignored — "outlier"
+   doesn't have a clean meaning there (a rare category isn't necessarily
+   wrong, just rare). Added in v0.7.
+
+drop semantics for the feature-side path
+----------------------------------------
+We chose to drop the *whole row* when any one feature column flags an
+outlier, rather than null out the offending cell. Reasoning: in
+procurement data an outlier in one feature almost always signals
+data-entry corruption that correlates with quality issues elsewhere in
+the row (a transcription mistake, a unit confusion). Throwing the row
+is the conservative move. Users who want per-cell handling should
+pre-clean the CSV before feeding it in.
+
+Detection rule (both surfaces)
+------------------------------
+Standard Tukey IQR: a value is an outlier when it is below Q1 − 1.5·IQR
+or above Q3 + 1.5·IQR, where IQR = Q3 − Q1. The multiplier is exposed
+on the API but defaults to 1.5; raising it (e.g. 3.0) catches only
+extreme outliers, lowering it (e.g. 1.0) is more aggressive.
+"""
+
+import numpy as np
+import pandas as pd
+
+POLICIES = ("keep", "warn", "drop", "winsorize")
+IQR_MULTIPLIER = 1.5
+
+
+def detect_outliers(values, multiplier=IQR_MULTIPLIER):
+    """Return a ``(mask, lower, upper)`` tuple flagging Tukey-IQR outliers.
+
+    ``values`` may be any 1-D numeric iterable. Non-numeric / NaN entries
+    are treated as non-outliers (the mask is False for them) so callers
+    don't need to clean inputs first.
+    """
+    series = pd.Series(values).astype(float)
+    finite = series.dropna()
+    if finite.empty:
+        return pd.Series([False] * len(series), index=series.index), float("nan"), float("nan")
+
+    q1, q3 = finite.quantile([0.25, 0.75])
+    iqr = q3 - q1
+    if iqr == 0:
+        # Central 50% collapses to a single point. The Tukey rule
+        # degenerates and the old behaviour (mask all False) silently
+        # missed obvious outliers in near-constant columns — e.g. a
+        # Weight column of [10]*20 + [10_000] would slip through. Anything
+        # not equal to the central point is, by definition, outside the
+        # central 50%, so we flag it; bounds collapse to that point.
+        point = float(q1)
+        mask = (series != point).fillna(False)
+        return mask, point, point
+
+    lower = float(q1 - multiplier * iqr)
+    upper = float(q3 + multiplier * iqr)
+    mask = (series < lower) | (series > upper)
+    mask = mask.fillna(False)
+    return mask, lower, upper
+
+
+def apply_outlier_policy(data, target_column, policy="warn", multiplier=IQR_MULTIPLIER):
+    """Apply ``policy`` to outliers in ``data[target_column]``.
+
+    Returns ``(df, summary)``. The summary dict is suitable for
+    caller-side logging:
+        ``{n_outliers, n_total, lower, upper, policy, applied}``
+
+    ``applied`` is the action that actually changed the data (``drop``,
+    ``winsorize``, or ``none``).
+    """
+    if policy not in POLICIES:
+        raise ValueError(f"Unknown outlier policy: {policy}. Choose from {POLICIES}.")
+
+    mask, lower, upper = detect_outliers(data[target_column], multiplier=multiplier)
+    n_outliers = int(mask.sum())
+    summary = {
+        "n_outliers": n_outliers,
+        "n_total": len(data),
+        "lower": lower,
+        "upper": upper,
+        "policy": policy,
+        "applied": "none",
+    }
+
+    if n_outliers == 0:
+        return data, summary
+
+    if policy == "drop":
+        summary["applied"] = "drop"
+        return data.loc[~mask].reset_index(drop=True), summary
+
+    if policy == "winsorize":
+        summary["applied"] = "winsorize"
+        new_data = data.copy()
+        new_data[target_column] = new_data[target_column].clip(lower=lower, upper=upper)
+        return new_data, summary
+
+    # keep / warn: don't change the data
+    return data, summary
+
+
+def _is_numeric_series(series: pd.Series) -> bool:
+    """True iff the column is numeric. Categorical columns are silently
+    skipped by the feature-outlier path because "outlier" doesn't have a
+    clean meaning for a discrete code — a rare category isn't necessarily
+    wrong, just rare. Use ``find_high_variation_features`` instead for
+    that case."""
+    return pd.api.types.is_numeric_dtype(series) and not pd.api.types.is_bool_dtype(series)
+
+
+def apply_feature_outlier_policy(
+    data, feature_columns, policy="warn", multiplier=IQR_MULTIPLIER
+):
+    """Apply ``policy`` to outliers across one or more *feature* columns.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        Training data. Must contain every column in ``feature_columns``.
+    feature_columns : Iterable[str]
+        Columns to inspect. Non-numeric columns are silently skipped (see
+        module docstring for the rationale). Pass the model's feature
+        list — exclude the target and any time column upstream.
+    policy : str
+        One of POLICIES. ``drop`` removes rows that have an outlier in
+        *any* numeric feature column; ``winsorize`` caps each column at
+        its own IQR bounds independently; ``keep`` / ``warn`` change
+        nothing (warn surfaces a message at the caller).
+    multiplier : float
+        Tukey IQR multiplier. 1.5 is the textbook default.
+
+    Returns
+    -------
+    (df, summary) where summary has the shape::
+
+        {
+            "policy": policy,
+            "applied": "drop" | "winsorize" | "none",
+            "n_total": int,
+            "n_outliers_total": int,        # rows touched at all
+            "per_column": {
+                column_name: {
+                    "n_outliers": int,
+                    "lower": float,
+                    "upper": float,
+                },
+                ...
+            },
+        }
+
+    ``n_outliers_total`` counts rows containing at least one outlier
+    (the relevant figure for ``drop``); per-column counts can sum to
+    more than this when a row has outliers in multiple columns.
+    """
+    if policy not in POLICIES:
+        raise ValueError(f"Unknown outlier policy: {policy}. Choose from {POLICIES}.")
+
+    numeric_cols = [
+        c for c in feature_columns
+        if c in data.columns and _is_numeric_series(data[c])
+    ]
+
+    per_column = {}
+    any_outlier_mask = pd.Series(False, index=data.index)
+
+    for col in numeric_cols:
+        mask, lower, upper = detect_outliers(data[col], multiplier=multiplier)
+        n = int(mask.sum())
+        per_column[col] = {"n_outliers": n, "lower": lower, "upper": upper}
+        if n > 0:
+            # Align the column-specific mask onto the full-frame mask.
+            any_outlier_mask = any_outlier_mask | mask.reindex(data.index, fill_value=False)
+
+    n_outliers_total = int(any_outlier_mask.sum())
+    summary = {
+        "policy": policy,
+        "applied": "none",
+        "n_total": len(data),
+        "n_outliers_total": n_outliers_total,
+        "per_column": per_column,
+    }
+
+    if n_outliers_total == 0:
+        return data, summary
+
+    if policy == "drop":
+        summary["applied"] = "drop"
+        return data.loc[~any_outlier_mask].reset_index(drop=True), summary
+
+    if policy == "winsorize":
+        # Per-column winsorisation: each column is capped at its own
+        # IQR bounds independently. Row count preserved.
+        summary["applied"] = "winsorize"
+        new_data = data.copy()
+        for col, stats in per_column.items():
+            if stats["n_outliers"] == 0:
+                continue
+            new_data[col] = new_data[col].clip(
+                lower=stats["lower"], upper=stats["upper"]
+            )
+        return new_data, summary
+
+    # keep / warn: don't change the data.
+    return data, summary