robustkit 0.0.1__tar.gz → 0.4.0__tar.gz

{robustkit-0.0.1/robustkit.egg-info → robustkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robustkit
-Version: 0.0.1
+Version: 0.4.0
 Summary: Practical tools for robust analysis of a single continuous relationship: trend fitting, stability checks, influence diagnostics, and bootstrap uncertainty.
 Author: Mikael Lundqvist
 License: MIT License
@@ -57,10 +57,21 @@ observations, and get honest, bias-corrected uncertainty estimates.
 
 `robustkit.core` (trend fitting, stability, diagnostics, uncertainty,
 consistency checks), `robustkit.segmentation` (hierarchical grouping,
-per-segment analysis), and `robustkit.information` (mutual-information
-feature ranking) are stable and tested. A more advanced
-information-theoretic pairing layer (conditional MI for a second
-variable, synergy/redundancy scoring) is planned but not yet included.
+per-segment analysis), `robustkit.information` (mutual-information
+feature ranking, quadrant classification, pairwise redundancy/synergy
+scoring), `robustkit.benchmark` (global-trend segment comparison,
+Robustness Map), and `robustkit.report` (analyst vs. publisher views,
+dispersion measures) are stable and tested.
+
+**Note on `information_efficiency`:** values can exceed 1.0 for
+continuous features. `mutual_information` is estimated on the
+full-resolution continuous values, while `entropy_bits` is computed on
+a binned version of the same feature (since `entropy()` expects
+categorical input). Binning discards information, so `entropy_bits` is
+a lower bound on the feature's true entropy -- an efficiency above 1.0
+signals that the feature carries more usable information than a coarse
+categorical summary of it would capture. This is expected behavior,
+not a bug.
 
 ## Installation
 
@@ -153,6 +164,122 @@ quadrant label alone.
 
 See `examples/information_tutorial.py` for a complete walkthrough.
 
+## Benchmarking against a global trend
+
+Compare each segment's observed outcome against what a single global
+robust trend predicts, with bootstrap uncertainty on the difference --
+answers "which groups deviate from the overall trend, and by how
+much?" rather than "how does the trend look overall?":
+
+```python
+from robustkit import segment_position_report
+
+report = segment_position_report(
+    df, segment_col="department", x_col="age", y_col="salary",
+)
+#   segment    n  observed_median  expected_median  difference  ci_lower  ci_upper
+#   Finance  176        48339.70         47799.82      539.88    202.15   1031.01
+#        HR  174        45718.84         46647.39     -928.55  -1293.26   -580.36
+#        IT  250        47226.50         47126.91       99.59   -117.56    510.81
+```
+
+A segment's confidence interval crossing zero means no clear deviation
+from the benchmark; HR and Finance above don't cross zero, IT does.
+
+## Robustness Map
+
+Classify features by how much a conclusion about their relationship
+with the target depends on (a) fitting method choice and (b) specific
+influential observations -- two genuinely different failure modes that
+a single diagnostic can miss:
+
+```python
+from robustkit import feature_robustness_report, plot_feature_robustness
+
+report = feature_robustness_report(df, target="value")
+#   feature  stability_pct  cook_impact_pct    quadrant
+#      CRIM          8.9             17.1     fragile
+#       AGE         16.8             15.5     fragile
+#        RM          4.9              0.1     robust
+#       TAX         22.2              1.4     structural_sensitivity
+
+plot_feature_robustness(report=report)
+```
+
+Four quadrants: **robust** (low spread, low impact), **structural
+sensitivity** (sensitive to fitting method, not to specific points),
+**data sensitive** (a few points drive the conclusion, method choice
+barely matters), **fragile** (both -- least trustworthy).
+
+`quadrant_report`/`plot_feature_space` (information) and
+`feature_robustness_report`/`plot_feature_robustness` (benchmark) both
+route through the same shared classifier, `robustkit.classify_quadrants`
+-- any future quadrant-based analysis in this package will too.
+
+## Analyst view vs. publisher view
+
+Two visualizations that look superficially similar but answer
+genuinely different questions:
+
+```python
+from robustkit import plot_analyst_view, plot_publisher_view, dispersion_ratio, iqr
+
+# "How confident are we in the trend estimate?" -- a bootstrap
+# confidence band that SHRINKS as sample size grows.
+plot_analyst_view(df["age"], df["salary"])
+
+# "How spread out are actual values in the population?" -- a median +
+# IQR band that does NOT shrink with more data, since it reflects
+# real dispersion, not estimation uncertainty. show_points defaults to
+# False, since this view is meant for publishing potentially sensitive
+# data (e.g. individual salaries) without exposing raw points.
+plot_publisher_view(df["age"], df["salary"])
+```
+
+This distinction matters in practice: with 20x more data (same
+underlying distribution), the analyst view's confidence band roughly
+halves in width, while the publisher view's IQR band stays essentially
+unchanged -- confirmed by the package's own test suite.
+
+`dispersion_ratio(y)` -- (Q3-Q1)/median -- and `iqr(y)` are available
+standalone for tabular reporting; `dispersion_by_bin(x, y, n_bins=10)`
+computes both across bins of a continuous x, e.g. to check whether
+dispersion (inequality) grows with age.
+
+## Feature pairing (information)
+
+Beyond ranking single features, evaluate *pairs* of features together:
+how redundant are they with each other, and does knowing one reveal
+additional predictive value in the other (synergy, e.g. an interaction
+effect)?
+
+```python
+from robustkit import (
+    conditional_mutual_information, communication_score,
+    rank_by_communication, pair_redundancy, pair_synergy,
+    rank_communicative_pairs,
+)
+
+# How communicable is a single feature -- not just predictive, but
+# suitable for a clear chart/table (adequate group sizes, homogeneous
+# groups, few enough categories to show at once)?
+comm_ranking = rank_by_communication(df, target="value")
+
+# How much does region's relevance to the target change once
+# department is already known?
+synergy = pair_synergy(df, feature_1="department", feature_2="region", target="value")
+
+# Rank every candidate pair by combined relevance, penalizing
+# redundant pairs and rewarding genuine synergy
+pairs = rank_communicative_pairs(df, target="value")
+```
+
+All mutual-information-based quantities in this module (`rank_features`,
+`conditional_mutual_information`, `pair_redundancy`, `pair_synergy`,
+`communication_score`) are expressed in **bits**, consistent with
+`entropy()` -- internally, scikit-learn's MI estimators return nats
+and are converted before being used anywhere in this package.
+
 ## Design principles
 
 - **One continuous x, one continuous y** at the core. This keeps every

robustkit-0.4.0/README.md

@@ -0,0 +1,256 @@
+# robustkit
+
+> ⚠️ **Under active development.** This is an early placeholder release
+> to claim the package name on PyPI. The API is incomplete and may
+> change without notice. Not yet recommended for production use.
+
+Practical tools for robust analysis of a single continuous relationship:
+y as a function of one continuous x.
+
+The guiding idea: **a conclusion that survives multiple fitting methods
+is more trustworthy than one that only holds under a single model.**
+`robustkit` makes it easy to compare Huber, Tukey biweight, and OLS
+fits side by side, identify and quantify the influence of individual
+observations, and get honest, bias-corrected uncertainty estimates.
+
+## Status
+
+`robustkit.core` (trend fitting, stability, diagnostics, uncertainty,
+consistency checks), `robustkit.segmentation` (hierarchical grouping,
+per-segment analysis), `robustkit.information` (mutual-information
+feature ranking, quadrant classification, pairwise redundancy/synergy
+scoring), `robustkit.benchmark` (global-trend segment comparison,
+Robustness Map), and `robustkit.report` (analyst vs. publisher views,
+dispersion measures) are stable and tested.
+
+**Note on `information_efficiency`:** values can exceed 1.0 for
+continuous features. `mutual_information` is estimated on the
+full-resolution continuous values, while `entropy_bits` is computed on
+a binned version of the same feature (since `entropy()` expects
+categorical input). Binning discards information, so `entropy_bits` is
+a lower bound on the feature's true entropy -- an efficiency above 1.0
+signals that the feature carries more usable information than a coarse
+categorical summary of it would capture. This is expected behavior,
+not a bug.
+
+## Installation
+
+```bash
+git clone https://github.com/<your-username>/robustkit.git
+cd robustkit
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+import numpy as np
+from robustkit import (
+    fit_huber_trend, fit_tukey_trend, predict_trend,
+    model_stability_pct, cooks_diagnostic, cook_impact,
+    bootstrap_band, bca_bootstrap_ci,
+)
+
+# x: a single continuous predictor, y: a single continuous outcome
+x = np.random.default_rng(0).uniform(20, 60, 200)
+y = 1000 + 50 * x - 0.4 * x**2 + np.random.default_rng(1).normal(0, 500, 200)
+
+fit = fit_huber_trend(x, y, degree=2)
+y_pred = predict_trend(fit, x_new=[30, 40, 50])
+
+stability = model_stability_pct(x, y)
+print("Median % spread between Huber/Tukey/OLS:", stability["median_pct_diff"])
+
+diag = cooks_diagnostic(x, y)
+impact = cook_impact(x, y, diag["flagged_indices"])
+print("Median % change in curve if flagged points removed:", impact["median_pct_change"])
+
+band = bootstrap_band(x, y)
+ci = bca_bootstrap_ci(x, y, statistic_fn=lambda x_, y_: np.median(y_))
+```
+
+See `examples/quickstart_tutorial.py` for a complete, runnable walkthrough.
+
+## Segmentation
+
+Run any `robustkit.core` analysis independently across subgroups of a
+larger dataset, with automatic fallback to coarser groupings when a
+finer one is too small to analyze reliably:
+
+```python
+from robustkit import hierarchical_segment, apply_by_segment, model_stability_pct
+
+hierarchy = [["department", "level", "status"], ["level", "status"], ["status"]]
+segmented = hierarchical_segment(df, hierarchy, min_size=20)
+
+report = apply_by_segment(
+    segmented, segment_col="segment_id", x_col="age", y_col="value",
+    analysis_fn=model_stability_pct,
+)
+```
+
+`apply_by_segment` works with any function shaped like
+`analysis_fn(x, y, **kwargs) -> dict` -- built-in ones
+(`model_stability_pct`, `cook_impact`, `bca_bootstrap_ci`, ...) or your
+own. Only scalar values in the returned dict end up in the report
+table; segments below `min_points` are skipped rather than causing an
+error.
+
+## Feature ranking (information)
+
+Rank features by mutual information with a target, normalized by each
+feature's own entropy, and classify them into four quadrants:
+
+```python
+from robustkit import rank_features, quadrant_report, plot_feature_space
+
+ranking = rank_features(df, target="value")
+report = quadrant_report(df, target="value")   # adds a `quadrant` column
+plot_feature_space(df, target="value")          # same quadrants, visualized
+```
+
+`quadrant_report` and `plot_feature_space` always agree on quadrant
+assignment -- both route through the same thresholding logic.
+
+**Caveat:** default thresholds are the *median* mutual information /
+efficiency across the ranked features. With only a handful of
+features, this can put a genuinely weak feature in the same "high"
+half as a strong one, since roughly half of any list sits above its
+own median regardless of how large the actual gap is. Median
+thresholding becomes meaningful with a reasonably large feature set;
+for a handful of candidates, read the raw `mutual_information` /
+`information_efficiency` values directly rather than relying on the
+quadrant label alone.
+
+See `examples/information_tutorial.py` for a complete walkthrough.
+
+## Benchmarking against a global trend
+
+Compare each segment's observed outcome against what a single global
+robust trend predicts, with bootstrap uncertainty on the difference --
+answers "which groups deviate from the overall trend, and by how
+much?" rather than "how does the trend look overall?":
+
+```python
+from robustkit import segment_position_report
+
+report = segment_position_report(
+    df, segment_col="department", x_col="age", y_col="salary",
+)
+#   segment    n  observed_median  expected_median  difference  ci_lower  ci_upper
+#   Finance  176        48339.70         47799.82      539.88    202.15   1031.01
+#        HR  174        45718.84         46647.39     -928.55  -1293.26   -580.36
+#        IT  250        47226.50         47126.91       99.59   -117.56    510.81
+```
+
+A segment's confidence interval crossing zero means no clear deviation
+from the benchmark; HR and Finance above don't cross zero, IT does.
+
+## Robustness Map
+
+Classify features by how much a conclusion about their relationship
+with the target depends on (a) fitting method choice and (b) specific
+influential observations -- two genuinely different failure modes that
+a single diagnostic can miss:
+
+```python
+from robustkit import feature_robustness_report, plot_feature_robustness
+
+report = feature_robustness_report(df, target="value")
+#   feature  stability_pct  cook_impact_pct    quadrant
+#      CRIM          8.9             17.1     fragile
+#       AGE         16.8             15.5     fragile
+#        RM          4.9              0.1     robust
+#       TAX         22.2              1.4     structural_sensitivity
+
+plot_feature_robustness(report=report)
+```
+
+Four quadrants: **robust** (low spread, low impact), **structural
+sensitivity** (sensitive to fitting method, not to specific points),
+**data sensitive** (a few points drive the conclusion, method choice
+barely matters), **fragile** (both -- least trustworthy).
+
+`quadrant_report`/`plot_feature_space` (information) and
+`feature_robustness_report`/`plot_feature_robustness` (benchmark) both
+route through the same shared classifier, `robustkit.classify_quadrants`
+-- any future quadrant-based analysis in this package will too.
+
+## Analyst view vs. publisher view
+
+Two visualizations that look superficially similar but answer
+genuinely different questions:
+
+```python
+from robustkit import plot_analyst_view, plot_publisher_view, dispersion_ratio, iqr
+
+# "How confident are we in the trend estimate?" -- a bootstrap
+# confidence band that SHRINKS as sample size grows.
+plot_analyst_view(df["age"], df["salary"])
+
+# "How spread out are actual values in the population?" -- a median +
+# IQR band that does NOT shrink with more data, since it reflects
+# real dispersion, not estimation uncertainty. show_points defaults to
+# False, since this view is meant for publishing potentially sensitive
+# data (e.g. individual salaries) without exposing raw points.
+plot_publisher_view(df["age"], df["salary"])
+```
+
+This distinction matters in practice: with 20x more data (same
+underlying distribution), the analyst view's confidence band roughly
+halves in width, while the publisher view's IQR band stays essentially
+unchanged -- confirmed by the package's own test suite.
+
+`dispersion_ratio(y)` -- (Q3-Q1)/median -- and `iqr(y)` are available
+standalone for tabular reporting; `dispersion_by_bin(x, y, n_bins=10)`
+computes both across bins of a continuous x, e.g. to check whether
+dispersion (inequality) grows with age.
+
+## Feature pairing (information)
+
+Beyond ranking single features, evaluate *pairs* of features together:
+how redundant are they with each other, and does knowing one reveal
+additional predictive value in the other (synergy, e.g. an interaction
+effect)?
+
+```python
+from robustkit import (
+    conditional_mutual_information, communication_score,
+    rank_by_communication, pair_redundancy, pair_synergy,
+    rank_communicative_pairs,
+)
+
+# How communicable is a single feature -- not just predictive, but
+# suitable for a clear chart/table (adequate group sizes, homogeneous
+# groups, few enough categories to show at once)?
+comm_ranking = rank_by_communication(df, target="value")
+
+# How much does region's relevance to the target change once
+# department is already known?
+synergy = pair_synergy(df, feature_1="department", feature_2="region", target="value")
+
+# Rank every candidate pair by combined relevance, penalizing
+# redundant pairs and rewarding genuine synergy
+pairs = rank_communicative_pairs(df, target="value")
+```
+
+All mutual-information-based quantities in this module (`rank_features`,
+`conditional_mutual_information`, `pair_redundancy`, `pair_synergy`,
+`communication_score`) are expressed in **bits**, consistent with
+`entropy()` -- internally, scikit-learn's MI estimators return nats
+and are converted before being used anywhere in this package.
+
+## Design principles
+
+- **One continuous x, one continuous y** at the core. This keeps every
+  function's output visually and numerically interpretable (a curve
+  you can plot, a band you can read).
+- **Diagnosis and action are separate steps.** `cooks_diagnostic`
+  flags candidates; `cook_impact` tells you whether removing them
+  actually changes anything.
+- **OLS is a reference point, not the enemy.** Comparing robust fits
+  against OLS is how you know whether robustness mattered at all.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

{robustkit-0.0.1 → robustkit-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "robustkit"
-version = "0.0.1"
+version = "0.4.0"
 description = "Practical tools for robust analysis of a single continuous relationship: trend fitting, stability checks, influence diagnostics, and bootstrap uncertainty."
 readme = "README.md"
 license = { file = "LICENSE" }

{robustkit-0.0.1 → robustkit-0.4.0}/robustkit/__init__.py

@@ -25,6 +25,15 @@ from .information.mutual_info import rank_features, information_efficiency
 from .information.quadrants import quadrant_report
 from .information.visualization import plot_feature_space, feature_map
 from .information.profile import profile, print_profile
+from .information.conditional_mi import conditional_mutual_information
+from .information.communication import communication_score, rank_by_communication
+from .information.pairs import pair_redundancy, pair_synergy, rank_communicative_pairs
+from .common.quadrants import classify_quadrants
+from .benchmark.global_model import fit_huber_benchmark, segment_position_report
+from .benchmark.robustness_map import feature_robustness_report, plot_feature_robustness
+from .report.dispersion import iqr, dispersion_ratio, dispersion_by_bin
+from .report.visualize_analyst import plot_analyst_view
+from .report.visualize_publisher import plot_publisher_view
 
 __all__ = [
     "fit_huber_trend",
@@ -49,6 +58,22 @@ __all__ = [
     "feature_map",
     "profile",
     "print_profile",
+    "conditional_mutual_information",
+    "communication_score",
+    "rank_by_communication",
+    "pair_redundancy",
+    "pair_synergy",
+    "rank_communicative_pairs",
+    "classify_quadrants",
+    "fit_huber_benchmark",
+    "segment_position_report",
+    "feature_robustness_report",
+    "plot_feature_robustness",
+    "iqr",
+    "dispersion_ratio",
+    "dispersion_by_bin",
+    "plot_analyst_view",
+    "plot_publisher_view",
 ]
 
 __version__ = "0.0.1"

robustkit-0.4.0/robustkit/benchmark/global_model.py

@@ -0,0 +1,74 @@
+"""
+Compare each segment's observed outcome against what a single global
+robust trend would predict, with bootstrap uncertainty on the
+difference.
+
+This answers a different question than robustkit.core.stability
+(which asks "how does the trend look overall, across fitting
+methods?"): here the question is "which groups deviate from the
+overall robust trend, once we account for their x values, and how
+confident are we in that deviation?"
+"""
+
+import numpy as np
+import pandas as pd
+
+from ..core.trend import fit_huber_trend, predict_trend
+from ..core.uncertainty import bca_bootstrap_ci
+
+
+def fit_huber_benchmark(x, y, degree=2):
+    """
+    Fit a single global Huber trend intended to serve as the
+    reference/benchmark that segments will be compared against. This
+    is just fit_huber_trend under a clearer name for this use case --
+    fit it once on the FULL population, not on any one segment.
+    """
+    return fit_huber_trend(x, y, degree=degree)
+
+
+def segment_position_report(df, segment_col, x_col, y_col, benchmark_fit=None,
+                             degree=2, n_boot=500, ci=95, seed=0):
+    """
+    For each segment, compare its observed median outcome against what
+    the global benchmark trend predicts at each row's x, with a BCa
+    bootstrap confidence interval on the (observed - expected)
+    difference.
+
+    benchmark_fit: a fit dict from fit_huber_benchmark, ideally fitted
+        on the full dataset (df should then be the same full dataset
+        this was fitted on, not a pre-filtered subset -- otherwise the
+        benchmark isn't a genuine "overall" reference for the segments
+        being compared). If omitted, one is fitted here on all of df.
+
+    Returns one row per segment: n, observed_median, expected_median,
+    difference (bootstrap point estimate), and the CI bounds.
+    """
+    if benchmark_fit is None:
+        benchmark_fit = fit_huber_benchmark(
+            df[x_col].to_numpy(dtype=float), df[y_col].to_numpy(dtype=float), degree=degree,
+        )
+
+    rows = []
+    for segment_value, group in df.groupby(segment_col, observed=True):
+        x = group[x_col].to_numpy(dtype=float)
+        y = group[y_col].to_numpy(dtype=float)
+        expected = predict_trend(benchmark_fit, x)
+
+        def difference_stat(x_, y_, _fit=benchmark_fit):
+            exp = predict_trend(_fit, x_)
+            return float(np.median(y_ - exp))
+
+        ci_result = bca_bootstrap_ci(x, y, difference_stat, n_boot=n_boot, ci=ci, seed=seed)
+
+        rows.append({
+            "segment": segment_value,
+            "n": len(group),
+            "observed_median": float(np.median(y)),
+            "expected_median": float(np.median(expected)),
+            "difference": ci_result["estimate"],
+            "ci_lower": ci_result["lower"],
+            "ci_upper": ci_result["upper"],
+        })
+
+    return pd.DataFrame(rows).sort_values("segment").reset_index(drop=True)

robustkit-0.4.0/robustkit/benchmark/robustness_map.py

@@ -0,0 +1,142 @@
+"""
+The "Robustness Map": classify features by how much a conclusion about
+their relationship with the target depends on (a) which robust fitting
+method is used, and (b) which specific observations are included.
+
+Motivated by a concrete finding: two features can have a similar
+number of Cook's-distance-flagged observations while having wildly
+different actual influence on the fitted trend (cook_impact). Model
+stability and Cook-impact are answering genuinely different questions,
+and a feature's position on both axes together says more about how
+much to trust a conclusion involving it than either axis alone.
+"""
+
+import pandas as pd
+
+from ..core.stability import model_stability_pct
+from ..core.diagnostics import cooks_diagnostic, cook_impact
+from ..common.quadrants import classify_quadrants
+
+ROBUSTNESS_LABELS = {
+    "high_high": "fragile",                     # unstable AND data-driven -- least trustworthy
+    "high_y_only": "data_sensitive",             # stable across methods, but driven by a few points
+    "high_x_only": "structural_sensitivity",     # sensitive to method choice, not to specific points
+    "low_low": "robust",                         # stable across methods AND not driven by outliers
+}
+
+_ROBUSTNESS_DISPLAY = {
+    "robust": "Robust",
+    "structural_sensitivity": "Structural Sensitivity",
+    "data_sensitive": "Data Sensitive",
+    "fragile": "Fragile",
+}
+
+
+def feature_robustness_report(df, target, features=None, degree=2,
+                               stability_threshold="median", impact_threshold="median"):
+    """
+    For each candidate feature (used as x against target as y),
+    compute model_stability_pct and cook_impact, and classify the
+    feature into one of four robustness quadrants:
+
+        robust                  -- low stability spread, low Cook impact
+        structural_sensitivity  -- high stability spread, low Cook impact
+                                    (the conclusion depends on which
+                                    fitting method you pick, not on
+                                    specific data points)
+        data_sensitive          -- low stability spread, high Cook impact
+                                    (a handful of observations drive
+                                    the conclusion, but method choice
+                                    barely matters)
+        fragile                 -- high stability spread AND high Cook
+                                    impact (the least trustworthy)
+    """
+    features = features or [c for c in df.columns if c != target]
+    y = df[target].to_numpy(dtype=float)
+
+    rows = []
+    for feature in features:
+        x = df[feature].to_numpy(dtype=float)
+
+        stability = model_stability_pct(x, y, degree=degree)
+        diag = cooks_diagnostic(x, y, degree=degree)
+
+        if len(diag["flagged_indices"]) > 0:
+            impact = cook_impact(x, y, diag["flagged_indices"], degree=degree)
+            cook_impact_pct = impact["median_pct_change"]
+        else:
+            cook_impact_pct = 0.0
+
+        rows.append({
+            "feature": feature,
+            "stability_pct": stability["median_pct_diff"],
+            "cook_impact_pct": cook_impact_pct,
+            "n_flagged": len(diag["flagged_indices"]),
+        })
+
+    report = pd.DataFrame(rows)
+    classified = classify_quadrants(
+        report, x_col="stability_pct", y_col="cook_impact_pct",
+        x_threshold=stability_threshold, y_threshold=impact_threshold,
+        labels=ROBUSTNESS_LABELS,
+    )
+    return classified.sort_values("cook_impact_pct", ascending=False).reset_index(drop=True)
+
+
+def plot_feature_robustness(df=None, target=None, report=None, annotate=True, figsize=(10, 7), ax=None):
+    """
+    Scatter plot of features in robustness space: x = model stability
+    spread (%), y = Cook-impact (%), colored by robustness quadrant.
+
+    Provide either a precomputed `report` (ideally the output of
+    feature_robustness_report, so quadrant labels are already
+    attached) or a `df`/`target` pair to compute everything internally.
+    Always routes quadrant assignment through the same logic as
+    feature_robustness_report, so the plot and the table can never
+    disagree.
+    """
+    import matplotlib.pyplot as plt
+    from matplotlib.lines import Line2D
+
+    if report is None or "quadrant" not in report.columns:
+        report = feature_robustness_report(df, target=target)
+
+    colors_map = {
+        "robust": "green",
+        "structural_sensitivity": "steelblue",
+        "data_sensitive": "darkorange",
+        "fragile": "red",
+    }
+    colors = report["quadrant"].map(colors_map)
+
+    created_fig = ax is None
+    if created_fig:
+        fig, ax = plt.subplots(figsize=figsize)
+
+    ax.scatter(
+        report["stability_pct"], report["cook_impact_pct"],
+        c=colors, s=80, edgecolors="black", linewidths=0.5, alpha=0.8,
+    )
+
+    if annotate:
+        for _, row in report.iterrows():
+            ax.annotate(
+                row["feature"], (row["stability_pct"], row["cook_impact_pct"]),
+                fontsize=8, xytext=(4, 4), textcoords="offset points",
+            )
+
+    legend_elements = [
+        Line2D([0], [0], marker="o", color="w", label=_ROBUSTNESS_DISPLAY[quadrant],
+               markerfacecolor=color, markersize=10)
+        for quadrant, color in colors_map.items()
+    ]
+    ax.legend(handles=legend_elements, loc="best")
+    ax.set_xlabel("Model Stability Spread (%)")
+    ax.set_ylabel("Cook Impact (%)")
+    ax.set_title("Feature Robustness Map")
+    ax.grid(True, alpha=0.3)
+
+    if created_fig:
+        fig.tight_layout()
+
+    return report