py-flexplot 0.8.2__py3-none-any.whl

pyflexplot/ml.py

@@ -0,0 +1,175 @@
+"""
+ml: Random-forest (and sklearn-estimator) wrappers for py-flexplot.
+
+This module provides thin adapters that make scikit-learn estimators
+(``RandomForestRegressor``, ``RandomForestClassifier``, ``GradientBoosting*``,
+and any estimator with a ``.predict()`` method) usable with py-flexplot's
+visualization API: ``compare_fits()``, ``flexplot(overlay=...)``,
+``visualize()``, and ``estimates()``.
+
+It does NOT fit models. Its job is to wrap an already-trained estimator
+with the metadata required to make it a first-class citizen of
+py-flexplot's visualization API:
+
+* ``RFAdapter`` -- thin wrapper bundling an sklearn regressor/classifier
+  with column-name metadata so ``compare_fits()`` and friends can call
+  ``.predict()`` and get a properly-aligned ``pandas.Series``.
+
+Why an adapter?
+---------------
+scikit-learn estimators expose ``.predict(X)`` but not the predictor
+names; py-flexplot's visualization layer needs to know which columns
+the model used so it can build evaluation DataFrames without losing
+row alignment. ``RFAdapter`` carries that metadata alongside the
+fitted model.
+
+Usage example::
+
+    from sklearn.ensemble import RandomForestRegressor
+    from pyflexplot.ml import RFAdapter
+
+    rf = RandomForestRegressor(n_estimators=200, random_state=0).fit(X, y)
+    fit = RFAdapter(rf, response_var="y", predictor_names=list(X.columns))
+
+    # Now use it in compare_fits:
+    from pyflexplot import compare_fits
+    p = compare_fits("y ~ x1 + x2", data=df, model1=statsmodels_fit, model2=fit)
+
+This is intentionally a thin glue layer — R-flexplot's
+``flexplot::compare.fits()`` accepted any R model with a ``predict()``
+method, and that's the surface this module recreates in Python.
+
+Optional dependency
+-------------------
+scikit-learn is **not** a declared dependency of py-flexplot; the
+adapter raises a clear ``ImportError`` at import time if sklearn is
+missing, and py-flexplot's core surface works fine without it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, List, Optional, Sequence
+
+import numpy as np
+import pandas as pd
+
+try:
+    from sklearn.base import BaseEstimator  # noqa: F401
+    _SKLEARN_AVAILABLE = True
+except Exception:  # pragma: no cover -- environment without sklearn
+    _SKLEARN_AVAILABLE = False
+
+
+def _check_sklearn_available():
+    if not _SKLEARN_AVAILABLE:
+        raise ImportError(
+            "scikit-learn is required for pyflexplot.ml; install with "
+            "`pip install scikit-learn`."
+        )
+
+
+@dataclass
+class RFAdapter:
+    """Adapter that makes an sklearn estimator usable with py-flexplot.
+
+    Parameters
+    ----------
+    estimator : sklearn.base.BaseEstimator
+        A fitted scikit-learn estimator with a ``predict(X)`` method.
+        ``RandomForestRegressor`` / ``RandomForestClassifier`` are the
+        primary targets, but any regressor / classifier works.
+    response_var : str
+        Name of the response variable in the original DataFrame. Used by
+        py-flexplot to build evaluation DataFrames.
+    predictor_names : list of str
+        Column names of the predictors used during fitting. Order matters;
+        must match the column order in the X matrix passed to ``.fit()``.
+
+    Notes
+    -----
+    The adapter deliberately does not subclass any sklearn base class to
+    avoid surprising scikit-learn's ``check_is_fitted`` machinery. It is
+    a pure metadata wrapper.
+    """
+
+    estimator: Any
+    response_var: str
+    predictor_names: List[str]
+
+    def __post_init__(self):
+        _check_sklearn_available()
+        if not isinstance(self.predictor_names, (list, tuple)):
+            raise TypeError(
+                f"predictor_names must be a list/tuple of strings; "
+                f"got {type(self.predictor_names).__name__}."
+            )
+        if any(not isinstance(n, str) for n in self.predictor_names):
+            raise TypeError("predictor_names must all be strings.")
+        if not isinstance(self.response_var, str):
+            raise TypeError(
+                f"response_var must be a string; got {type(self.response_var).__name__}."
+            )
+
+    def predict(self, X):
+        """Predict on a DataFrame or 2-D array.
+
+        Accepts either a ``pandas.DataFrame`` (column-aligned by name when
+        possible) or a 2-D ``numpy.ndarray``. Returns a 1-D
+        ``numpy.ndarray``.
+        """
+        if isinstance(X, pd.DataFrame):
+            # Align by name when the columns match; otherwise fall back to
+            # positional access (the caller has positional data).
+            missing = [c for c in self.predictor_names if c not in X.columns]
+            if not missing:
+                X_arr = X[self.predictor_names].to_numpy()
+            else:
+                X_arr = X.to_numpy()
+        else:
+            X_arr = np.asarray(X)
+        return np.asarray(self.estimator.predict(X_arr))
+
+    def predict_df(self, data: pd.DataFrame) -> pd.DataFrame:
+        """Predict on a DataFrame and return a single-column DataFrame.
+
+        The returned column is named ``pred_<response_var>`` to match the
+        convention used by ``compare_fits(return_preds=True)``.
+        """
+        preds = self.predict(data)
+        return pd.DataFrame({f"pred_{self.response_var}": preds})
+
+
+def make_rf_adapter(
+    estimator: Any,
+    data: pd.DataFrame,
+    response_var: str,
+    predictor_names: Optional[Sequence[str]] = None,
+) -> RFAdapter:
+    """Convenience constructor that pulls predictor names from a DataFrame.
+
+    Parameters
+    ----------
+    estimator
+        A fitted sklearn estimator.
+    data : pd.DataFrame
+        The training DataFrame. Used to infer ``predictor_names`` if not
+        provided.
+    response_var
+        Name of the response column.
+    predictor_names
+        Explicit list of predictor column names. If ``None`` (default),
+        uses ``[c for c in data.columns if c != response_var]``.
+
+    Returns
+    -------
+    RFAdapter
+    """
+    _check_sklearn_available()
+    if predictor_names is None:
+        predictor_names = [c for c in data.columns if c != response_var]
+    return RFAdapter(
+        estimator=estimator,
+        response_var=response_var,
+        predictor_names=list(predictor_names),
+    )

pyflexplot/quality.py

@@ -0,0 +1,372 @@
+"""Auto data-quality diagnostics for regression-style formulas (C: power feature).
+
+Public surface:
+- :func:`diagnose`: run a diagnostic suite on a flexplot formula + data.
+- :func:`format_summary`: pretty-print a diagnosis dict as a one-paragraph
+  terminal/email/log-friendly summary.
+
+Design notes
+------------
+Diagnostics are designed to surface "why might my fit be off" rather than to
+gate-keep model usage. Every diagnostic returns raw test statistics and
+p-values alongside a plain-English interpretation; users can drill in
+themselves if they want.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, cast
+
+import numpy as np
+import pandas as pd
+
+
+# --- Internal helpers ---------------------------------------------------------
+
+
+def _safe_numeric(s: pd.Series) -> Optional[np.ndarray]:
+    """Return ``s`` as a float array, or None if conversion fails."""
+    try:
+        return s.to_numpy(dtype=float)
+    except (ValueError, TypeError):
+        return None
+
+
+def _missingness(data: pd.DataFrame, columns: List[str]) -> Dict[str, Any]:
+    """Per-column missing counts and overall pattern heuristic."""
+    per_col = {c: int(data[c].isna().sum()) for c in columns if c in data.columns}
+    total_rows = len(data)
+    any_missing = sum(per_col.values())
+    complete_cases = int(data[list(per_col.keys())].dropna().shape[0])
+
+    # Pattern heuristic: if missingness is concentrated in one column it's
+    # likely non-random; spread across all columns suggests MCAR.
+    if any_missing == 0:
+        pattern = "none"
+    elif max(per_col.values(), default=0) > 0.5 * any_missing:
+        pattern = "concentrated (likely MNAR/MAR)"
+    else:
+        pattern = "spread (likely MCAR)"
+
+    return {
+        "per_column": per_col,
+        "total_missing": any_missing,
+        "complete_cases": complete_cases,
+        "rows": total_rows,
+        "pattern": pattern,
+    }
+
+
+def _outliers(
+    y: np.ndarray, X: np.ndarray, threshold: Optional[float] = None
+) -> Dict[str, Any]:
+    """Cook's distance for a fitted OLS model.
+
+    Returns the count of influential points (Cook's D > 4/n) and their row
+    indices in the input data (after any internal NaN filtering).
+    """
+    import statsmodels.api as sm
+
+    n = max(len(y), 1)
+    if threshold is None:
+        threshold = 4.0 / n
+
+    Xc = sm.add_constant(X, has_constant="add")
+    model = sm.OLS(y, Xc).fit()
+    infl = model.get_influence()
+    cooks_d, _ = infl.cooks_distance
+    influential_idx = np.where(cooks_d > threshold)[0].tolist()
+    return {
+        "n_outliers": len(influential_idx),
+        "indices": influential_idx,
+        "max_cooks_d": float(np.max(cooks_d)),
+        "threshold": float(threshold),
+        "method": "Cook's distance > 4/n",
+    }
+
+
+def _linearity_test(residuals: np.ndarray, fitted: np.ndarray) -> Dict[str, Any]:
+    """Ramsey RESET test for functional form misspecification.
+
+    Augmented regression: add fitted^2 and fitted^3 to the design and test
+    whether the added terms are jointly zero. A small p-value indicates
+    non-linearity.
+    """
+    import statsmodels.api as sm
+
+    X_aug = np.column_stack([fitted, fitted ** 2, fitted ** 3])
+    Xc = sm.add_constant(X_aug, has_constant="add")
+    model = sm.OLS(residuals, Xc).fit()
+    # The F-test is for whether the augmented terms have zero coefficients
+    # (excluding the constant).
+    r_matrix = np.zeros((3, Xc.shape[1]))
+    r_matrix[0, 1] = 1  # fitted^1
+    r_matrix[1, 2] = 1  # fitted^2
+    r_matrix[2, 3] = 1  # fitted^3
+    try:
+        test = model.f_test(r_matrix)
+        statistic = float(np.squeeze(test.fvalue))
+        p_value = float(np.squeeze(test.pvalue))
+    except Exception:
+        statistic, p_value = float("nan"), float("nan")
+
+    return {
+        "test": "Ramsey RESET",
+        "statistic": statistic,
+        "p_value": p_value,
+        "reject_linearity": bool(p_value < 0.05) if not np.isnan(p_value) else None,
+        "interpretation": (
+            "Reject linearity at alpha=0.05; functional form may be misspecified."
+            if (p_value < 0.05 if not np.isnan(p_value) else False)
+            else "Fail to reject linearity at alpha=0.05."
+        ),
+    }
+
+
+def _heteroscedasticity_test(
+    residuals: np.ndarray, fitted: np.ndarray, X_with_const: np.ndarray
+) -> Dict[str, Any]:
+    """Breusch-Pagan test for non-constant error variance.
+
+    Returns the LM statistic, p-value, and an interpretation.
+    """
+    from statsmodels.stats.diagnostic import het_breuschpagan
+
+    try:
+        lm, lm_pvalue, fvalue, f_pvalue = het_breuschpagan(residuals, X_with_const)
+    except Exception:
+        return {
+            "test": "Breusch-Pagan",
+            "statistic": float("nan"),
+            "p_value": float("nan"),
+            "reject_homoscedasticity": None,
+            "interpretation": "Test could not be computed.",
+        }
+    return {
+        "test": "Breusch-Pagan",
+        "statistic": float(lm),
+        "p_value": float(lm_pvalue),
+        "reject_homoscedasticity": bool(lm_pvalue < 0.05),
+        "interpretation": (
+            "Reject homoscedasticity at alpha=0.05; variance is non-constant."
+            if lm_pvalue < 0.05
+            else "Fail to reject homoscedasticity at alpha=0.05."
+        ),
+    }
+
+
+# --- Public API ---------------------------------------------------------------
+
+
+def diagnose(
+    formula: str,
+    data: pd.DataFrame,
+    verbose: bool = True,
+    outlier_threshold: Optional[float] = None,
+) -> Dict[str, Any]:
+    """Run a data-quality diagnostic on a flexplot formula + data.
+
+    Parameters
+    ----------
+    formula : str
+        Flexplot formula of the form ``y ~ x1 + x2 [+ ...]``. Only the
+        outcome and predictors after ``~`` are used.
+    data : pd.DataFrame
+        Non-empty data frame holding the referenced columns.
+    verbose : bool, default True
+        If True, prints a one-paragraph summary to stdout.
+    outlier_threshold : float, default 4.0 / n
+        Cook's distance cutoff. Default is the conventional ``4/n`` value
+        (applied automatically as ``4.0 / n_complete``). Pass an explicit
+        float to override.
+
+    Returns
+    -------
+    dict
+        Structured diagnostics with keys:
+
+        - ``n_obs`` (int), ``n_complete`` (int), ``columns`` (list[str])
+        - ``missing`` (dict): per-column counts and pattern heuristic
+        - ``outliers`` (dict): Cook's D count and threshold
+        - ``linearity`` (dict): Ramsey RESET test
+        - ``heteroscedasticity`` (dict): Breusch-Pagan test
+
+    Raises
+    ------
+    ValueError
+        If the formula has no outcome or no predictors.
+
+    Examples
+    --------
+    Quiet mode (returns the dict without printing):
+
+    >>> import pandas as pd
+    >>> import numpy as np
+    >>> from pyflexplot.quality import diagnose
+    >>> rng = np.random.default_rng(0)
+    >>> df = pd.DataFrame({
+    ...     "y": rng.normal(size=200),
+    ...     "x": rng.normal(size=200),
+    ... })
+    >>> diag = diagnose("y ~ x", data=df, verbose=False)
+    >>> diag["linearity"]["reject_linearity"]
+    False
+    >>> "missing" in diag and "outliers" in diag
+    True
+
+    Notes
+    -----
+    Designed to surface *why* a fit might be off, not to gate-keep model
+    usage. All test statistics and p-values are returned alongside the
+    plain-English interpretation so users can drill in themselves. The
+    pattern heuristic (`` none`` / ``concentrated`` / ``spread``) is a
+    rough first cut; for missing-data formal tests, see ``statsmodels``.
+    """
+    from .core import parse_flexplot_formula
+
+    variables = parse_flexplot_formula(formula)
+    y_name = variables["y"]
+    x_names = [v for v in variables["all_x"] if v]
+    if not x_names:
+        raise ValueError(
+            f"diagnose() requires a formula with at least one predictor; got {formula!r}."
+        )
+
+    # Drop any predictors that aren't numeric — non-numeric predictors
+    # (categorical color, given groups) belong to the formula but not the
+    # regression design matrix.
+    numeric_x_names = [
+        c for c in x_names if c in data.columns
+        and pd.api.types.is_numeric_dtype(data[c])
+    ]
+    if not numeric_x_names:
+        raise ValueError(
+            f"diagnose() found no numeric predictors in formula {formula!r}; "
+            f"predictors={x_names}."
+        )
+
+    columns = [y_name] + numeric_x_names
+    # Strip any column not actually present (parse_flexplot_formula is permissive).
+    columns = [c for c in columns if c in data.columns]
+    if len(columns) < 2:
+        raise ValueError(
+            f"diagnose() needs at least one predictor present in data; got columns={columns}."
+        )
+
+    missing_summary = _missingness(data, columns)
+
+    # Fit on the complete-case subset.
+    complete = data[[y_name] + numeric_x_names].dropna()
+    n_complete = len(complete)
+    if n_complete < 4:
+        out: Dict[str, Any] = {
+            "n_obs": int(len(data)),
+            "n_complete": n_complete,
+            "columns": columns,
+            "missing": missing_summary,
+            "outliers": {
+                "n_outliers": 0, "indices": [], "max_cooks_d": None,
+                "threshold": (
+                outlier_threshold if outlier_threshold is not None
+                else 4.0 / max(n_complete, 1)
+            ),
+                "method": "Cook's distance > 4/n",
+            },
+            "linearity": {
+                "test": "Ramsey RESET",
+                "statistic": None, "p_value": None, "reject_linearity": None,
+                "interpretation": "Not enough complete cases to run the test.",
+            },
+            "heteroscedasticity": {
+                "test": "Breusch-Pagan",
+                "statistic": None, "p_value": None, "reject_homoscedasticity": None,
+                "interpretation": "Not enough complete cases to run the test.",
+            },
+        }
+        if verbose:
+            print(format_summary(out))
+        return out
+
+    y = _safe_numeric(complete[y_name])
+    x_arrays = [_safe_numeric(complete[c]) for c in numeric_x_names]
+    if y is None or any(arr is None for arr in x_arrays):
+        raise ValueError("Complete numeric cases could not be converted to arrays.")
+    X = np.column_stack([cast(np.ndarray, arr) for arr in x_arrays])
+
+    # Re-fit on the complete-case subset to get residuals/fitted.
+    import statsmodels.api as sm
+
+    Xc = sm.add_constant(X, has_constant="add")
+    fit = sm.OLS(y, Xc).fit()
+    residuals = fit.resid
+    fitted = fit.fittedvalues
+
+    outlier_summary = _outliers(
+        y, X,
+        threshold=(
+            outlier_threshold
+            if outlier_threshold is not None
+            else 4.0 / max(n_complete, 1)
+        ),
+    )
+    linearity_summary = _linearity_test(residuals, fitted)
+    hetero_summary = _heteroscedasticity_test(residuals, fitted, Xc)
+
+    out = {
+        "n_obs": int(len(data)),
+        "n_complete": int(n_complete),
+        "columns": columns,
+        "missing": missing_summary,
+        "outliers": outlier_summary,
+        "linearity": linearity_summary,
+        "heteroscedasticity": hetero_summary,
+        "_r_squared": float(fit.rsquared),
+    }
+
+    if verbose:
+        print(format_summary(out))
+
+    return out
+
+
+def format_summary(diag: Dict[str, Any]) -> str:
+    """Format a diagnosis dict as a one-paragraph human-readable summary.
+
+    Suitable for terminal output, log lines, or email bodies.
+    """
+    n_obs = diag.get("n_obs", "?")
+    n_complete = diag.get("n_complete", "?")
+    columns = diag.get("columns", [])
+    col_str = ", ".join(columns)
+
+    missing = diag.get("missing", {})
+    total_missing = missing.get("total_missing", 0)
+    pattern = missing.get("pattern", "unknown")
+
+    outliers = diag.get("outliers", {})
+    n_outliers = outliers.get("n_outliers", 0)
+    max_cooks = outliers.get("max_cooks_d")
+
+    linearity = diag.get("linearity", {})
+    lin_interp = linearity.get("interpretation", "n/a")
+
+    hetero = diag.get("heteroscedasticity", {})
+    het_interp = hetero.get("interpretation", "n/a")
+
+    r2 = diag.get("_r_squared")
+
+    lines = [
+        f"Diagnostic for {col_str} (n={n_obs}, complete cases={n_complete})",
+        f"  Missingness: {total_missing} missing values total; pattern = {pattern}.",
+    ]
+    if max_cooks is not None:
+        lines.append(
+            f"  Outliers: {n_outliers} influential points (max Cook's D = {max_cooks:.3f})."
+        )
+    else:
+        lines.append(f"  Outliers: {n_outliers} influential points.")
+    lines.append(f"  Linearity: {lin_interp}")
+    lines.append(f"  Heteroscedasticity: {het_interp}")
+    if r2 is not None:
+        lines.append(f"  R-squared (OLS reference): {r2:.3f}")
+    return "\n".join(lines)