robustkit 0.6.0__tar.gz → 0.7.0__tar.gz

{robustkit-0.6.0/robustkit.egg-info → robustkit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robustkit
-Version: 0.6.0
+Version: 0.7.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
@@ -25,6 +25,14 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -42,10 +50,6 @@ Dynamic: license-file
 
 # 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.
 
@@ -72,6 +76,14 @@ individual-level data from aggregated summaries), and
 analysis, no manual hierarchy construction required) are stable and
 tested.
 
+**What is new in 0.7.0:** see `CHANGELOG.md`. In short: a `reference`
+parameter for the outlier reports (`"model"`, `"curve"`, `"benchmark_curve"`),
+dual-reference outlier classification, benchmark screening and
+goodness-of-fit, pointwise stability, per-segment Huber+IQR export,
+several drilldown and quality reports, and `jackknife_cap` for faster
+bootstrap intervals on large segments. Calls written for 0.6.0 keep
+working.
+
 **Recent fixes from real-dataset validation:**
 - `rank_features`/`quadrant_report`/`rank_communicative_pairs` no
   longer crash on pandas `Categorical` columns containing missing
@@ -131,6 +143,31 @@ ci = bca_bootstrap_ci(x, y, statistic_fn=lambda x_, y_: np.median(y_))
 
 See `examples/quickstart_tutorial.py` for a complete, runnable walkthrough.
 
+## Where along x is the trend weak?
+
+`model_stability_pct` summarises the disagreement between Huber, Tukey and
+OLS over the whole x range, and `bootstrap_band` gives the sampling
+uncertainty of the Huber curve. `pointwise_stability_report` puts the two
+side by side at every grid point, together with the number of observations
+near that point, so that a thin region (say, few young employees) can be told
+apart from a region where the fitting method matters:
+
+```python
+from robustkit import pointwise_stability_report, plot_pointwise_stability
+
+report = pointwise_stability_report(x, y, n_boot=300)
+report[["x", "method_spread_pct", "band_width_pct", "local_n", "dominant"]]
+# dominant == "sampling": the bootstrap band is wider than the methods' spread
+# dominant == "method":   the methods differ by more than the band
+
+plot_pointwise_stability(x, y, report=report)   # curves, band and a rug of observations
+```
+
+`window_frac` (default 0.1) sets the width of the window used for `local_n`,
+as a fraction of the x range. The three curves, the band and `pct_spread` are
+the same numbers `model_stability_pct` and `bootstrap_band` return; nothing new
+is fitted. Requires statsmodels (Tukey), like `model_stability_pct`.
+
 ## Trend growth rate and goodness of fit
 
 ```python
@@ -262,6 +299,28 @@ report = segment_position_report(
 `segment_position_report` never inspects what the model uses
 internally -- it only calls `predict()`.
 
+**A pitfall worth knowing about if your custom model's `predict()`
+uses `pd.get_dummies()`:** `segment_position_report` and
+`plot_segment_vs_benchmark` both call `predict()` on ONE segment at a
+time -- data that, by construction, has only a single value in each
+of its defining categorical columns. Calling `pd.get_dummies()` fresh
+on data like that generates a dummy column only for categories
+actually present in that call, which for a single, fully-specified
+segment is often none at all; a `reindex(columns=..., fill_value=0)`
+step then silently fills in `0` where the correct value was `1`,
+corrupting every per-segment prediction without raising an error.
+Verified directly: an under-specified benchmark's segment-level
+finding came out with the wrong sign and a wildly different magnitude
+until this was fixed. The fix is to fit a `sklearn.OneHotEncoder` (or
+equivalent) ONCE during training and reuse that SAME fitted encoder
+inside `predict()`, rather than re-deriving dummy columns from
+whatever data `predict()` happens to receive -- a fitted encoder
+always knows the full set of training-time categories, regardless of
+how homogeneous a later single call's data is. (`mad_outlier_report`
+and `dual_reference_outlier_report` are NOT affected by this, since
+both call `predict()` once on the full, heterogeneous population
+rather than per segment.)
+
 **Small segments:** groups with fewer than `MIN_POINTS_FOR_CI` (default
 20) observations still get `observed_median` / `expected_median` /
 `difference`, but `ci_lower` / `ci_upper` are `NaN` and
@@ -271,7 +330,129 @@ small, since it can fail outright or become statistically meaningless.
 For segments at or above the threshold, the interval is a full BCa
 (bias-corrected and accelerated) bootstrap interval, via the same
 `bca_bootstrap_ci_by_index` primitive used elsewhere in the package --
-not a plain percentile bootstrap.
+not a plain percentile bootstrap. That primitive's jackknife step
+(needed for the acceleration term) is inherently O(n) regardless of
+`n_boot`, which becomes the dominant cost on large real segments --
+verified directly on a ~185,000-row segment (minutes, unusable) --
+so above `jackknife_cap` observations (1000 by default), a random
+subsample of that many positions is left out one at a time instead of
+every single one. Confidence interval bounds from the capped and
+uncapped versions were verified to differ by roughly 0.000005 on that
+same real segment, while cutting its runtime to about 3 seconds; pass
+`jackknife_cap=None` to any function built on
+`bca_bootstrap_ci_by_index` (including `segment_contribution_report`
+and `segment_benchmark_drilldown_report`) to always use the full,
+uncapped jackknife instead.
+
+`plot_segment_vs_benchmark` is the visual counterpart to
+`segment_position_report`: a single summary difference (e.g. "ITS is
+$988 below benchmark") can arise from several different underlying
+patterns that look identical in a table -- the whole segment sitting
+a bit below throughout, only its younger members sitting far below,
+only its older members, or two opposing effects that happen to cancel
+out in the median. This plots, for one or more segments, the actual
+observations, each segment's own OBSERVED trend (via LOWESS -- a
+flexible, assumption-free local smoother, deliberately not a
+Huber/Tukey/OLS fit at a fixed degree, since the point here is a
+segment's raw shape without imposing one), and the benchmark's
+expected trend for that segment, letting you see exactly where
+across `x_col` a segment's divergence actually occurs:
+
+```python
+from robustkit import plot_segment_vs_benchmark
+
+plot_segment_vs_benchmark(
+    df, segment_col="JobFamily", segment_values=["ENG", "ITS"],
+    y_col="salary", x_col="age", benchmark_fit=model_c,
+)
+```
+
+Works with a custom, multivariate `benchmark_fit` (any
+`predict(dataframe)` object) the same way `segment_position_report`
+does -- other columns the model needs are held constant per segment
+(at that segment's own value) when building the benchmark curve, so a
+segment like `"ENG_P2_Yes"` gets its benchmark line computed at
+`P_niva="P2", OT="Yes"` throughout, not averaged across values that
+don't apply to it. Requires `statsmodels` (imported lazily, same as
+`fit_tukey_trend`) -- this is a diagnostic plot only, not a source of
+numbers other functions build on, which is why LOWESS is used here
+specifically rather than elsewhere in the package.
+
+`benchmark_goodness_of_fit` evaluates an ALREADY-FITTED benchmark's
+overall explanatory power -- r_squared, rmse, mae -- against the
+actual values in y_col:
+
+```python
+from robustkit import benchmark_goodness_of_fit
+
+benchmark_goodness_of_fit(df, y_col="salary", benchmark_fit=model_c, x_col="age")
+# {"r_squared": 0.997, "rmse": 895, "mae": 712}
+```
+
+This is a different question from screening, below: even a screen
+that finds nothing (every candidate's residual mutual information
+near zero) says nothing about how much the benchmark explains
+overall -- a benchmark can be "complete", in the sense that no
+obvious structure is left to add, while still explaining relatively
+little of `y_col`'s variance if the underlying noise is simply large.
+Unlike `core.goodness_of_fit.goodness_of_fit`, which fits its own
+trend internally and therefore only evaluates a single-column
+robustkit trend, this function evaluates a benchmark that's already
+been fit elsewhere -- a robustkit trend-fit dict, or any custom,
+potentially multivariate `predict(dataframe)` object -- and never
+re-fits anything itself. Verified directly: an intentionally
+under-specified (age-only, linear) benchmark scored r_squared=0.874;
+adding the true quadratic term and the two missing categorical
+drivers raised it to r_squared=0.997 on the same data.
+
+`benchmark_screening_report` screens a fitted benchmark for likely-missing
+structure -- answering "is this benchmark good enough, or is there
+something it's still missing?" -- without ever building or fitting a
+new benchmark model automatically. Its `result["fit"]` entry is exactly
+`benchmark_goodness_of_fit`'s output for the same benchmark, so the two
+questions -- "how much does it explain overall" and "what specific
+structure might it still be missing" -- are always available side by
+side, numerically identical to calling either function directly:
+
+```python
+from robustkit import benchmark_screening_report
+
+result = benchmark_screening_report(
+    df, y_col="salary", benchmark_fit=model_c, x_col="age",
+    candidate_cols=["JobFamily", "level"],
+)
+result["fit"]            # how much does the benchmark explain overall?
+result["polynomial"]     # does x_col's current degree capture its shape?
+result["interactions"]   # is there missing categorical structure or an interaction?
+```
+
+Two genuinely different questions, deliberately answered with two
+different tools rather than one unified ranking, because mutual
+information cannot distinguish them. `result["polynomial"]` re-runs
+`compare_polynomial_degrees` (Chapter 5) on the raw `(x_col, y_col)`
+relationship directly -- checking polynomial degree this way, rather
+than via mutual information, matters because MI is invariant to
+monotonic reparametrization: on a domain where `x_col` is always
+positive, `x_col`, `x_col**2`, and `x_col**3` are all monotonic
+transforms of each other, so MI-based screening would report them as
+carrying nearly identical information regardless of which degree
+actually fits -- verified directly, within about 2% of each other on
+a deliberately under-fit benchmark that clearly needed degree 2, not
+1. `result["interactions"]` instead fits the benchmark's own residual
+as the target of `rank_features` -- reliable here specifically because
+a genuinely missing categorical variable, or a combination of two
+(`"JobFamily x level"`, generated automatically for every pairwise
+combination of `candidate_cols` unless `interaction_pairs` is given
+explicitly), is not a reparametrization of anything already in the
+model, so MI detects it directly. Sorted by `information_efficiency`,
+not raw `mutual_information` -- verified directly: an interaction term
+can carry MORE raw mutual information than a simpler candidate while
+still ranking lower on efficiency, the same high-cardinality trap
+Chapter 8's `zip_code` example demonstrated. Every row is a candidate
+worth investigating further, not a confirmed missing term -- automatic
+interaction generation grows combinatorially and carries real
+multiple-testing risk, especially with many candidate columns or a
+modest sample size.
 
 ## Reporting: residuals, individual deviations, batch runs, and Excel export
 
@@ -425,6 +606,26 @@ convenience wrappers -- identical results to building the hierarchy
 by hand with `hierarchical_segment` and calling `apply_by_segment` /
 `segment_position_report` directly.
 
+`segment_quality_report` combines several independent robustness
+measures into a single row per segment -- model stability, Cook's
+impact, MdAPE, and IQR of residuals -- so one table shows how
+trustworthy each segment's conclusion is, rather than cross-
+referencing several separate function calls by hand:
+
+```python
+from robustkit import segment_quality_report
+
+segment_quality_report(
+    df, x_col="age", y_col="salary", segment_cols=["JobFamily", "Level", "OT"], min_size=20,
+)
+#   segment  n  skipped  median_pct_diff  max_pct_diff  n_flagged  cook_impact_pct  mdape  iqr_resid  segment_level
+```
+
+Each measure is computed and error-handled independently -- if
+model stability fails (e.g. Tukey needs statsmodels, which may not be
+installed), Cook's impact, MdAPE, and IQR are still reported for that
+segment rather than the whole row failing.
+
 `mad_outlier_report` flags individuals whose residual is an outlier
 relative to their OWN segment's typical spread (MAD), not the whole
 population -- built on the same automatic hierarchical segmentation as
@@ -450,6 +651,26 @@ Segments with zero MAD (a degenerate case, usually a tiny segment
 where every residual happens to match) are treated as having an
 infinite threshold rather than flagging everyone in them.
 
+`reference`: `"model"` (default) flags against `benchmark_fit` (or, if
+none is given, a single Huber trend fit once across the whole
+population). `"curve"` instead fits a fresh Huber trend WITHIN each
+segment, on that segment's own data alone, and flags against THAT --
+no benchmark model involved at all. Use `"curve"` when the flagging
+itself, not just a chart, should match "how does this person compare
+to their immediate segment-mates" -- e.g. a report for someone who
+shouldn't need the underlying benchmark model explained to trust the
+numbers. `"benchmark_curve"` is a third option in between: like
+`"model"`, it starts from `benchmark_fit`'s raw predictions, but then,
+WITHIN each segment, fits a Huber trend to those predictions (not to
+the actual y values, as `"curve"` does) and flags against that smoothed
+curve -- the exact reference `export_outlier_pdf`'s `mode="benchmark"`
+draws, so pairing the two gives full consistency without discarding
+the benchmark model's other covariates the way `"curve"` does.
+`x_col` is required for all three, but `"curve"` and `"benchmark_curve"`
+need it even when a custom `benchmark_fit` would otherwise have made it
+optional. `mad_outlier_drilldown_report` takes the same `reference`
+parameter, with identical semantics.
+
 `export_outlier_pdf` renders one chart per segment -- built from the
 same segmentation and flagging as `mad_outlier_report` -- as a
 one-page-per-segment PDF, for visual verification alongside the
@@ -461,12 +682,53 @@ from robustkit import export_outlier_pdf
 export_outlier_pdf(
     df, y_col="salary", segment_cols=["JobFamily", "Level", "OT"], x_col="age",
     path="outliers.pdf", min_size=20, k=3.0, id_cols=["employee_id"],
+    annotate_flagged_with="employee_id",  # optional: label flagged points directly
 )
 ```
 
-Each page plots every observation in that segment, the benchmark's
-expected values (the exact same values used for flagging, not a
-separately re-fit curve), and flagged outliers marked distinctly.
+`mode="benchmark"` (default) plots a Huber curve fit to the benchmark's
+own predicted values, not the raw values connected point-to-point --
+for a multivariate benchmark model (depending on more than `x_col`),
+raw expected values aren't a pure function of `x_col` within a
+segment, so connecting them can zig-zag sharply even for a perfectly
+sensible model. The Huber-fit curve smooths over that without becoming
+a different reference: it's still derived entirely from the
+benchmark's own predictions. `mode="local"` instead fits a fresh Huber
+trend within each segment on the actual observed values alone -- often
+easier to read for "where does this person sit relative to their
+immediate colleagues?"
+
+`mode` (what's drawn) and `reference` (what flagging actually uses)
+are independent choices -- `export_outlier_pdf` takes the same
+`reference="model"/"curve"/"benchmark_curve"` parameter as
+`mad_outlier_report`, and always computes flagging exactly the way
+that report would with matching arguments, so the chart and the
+numeric report never disagree. Pairing `mode="local"` with
+`reference="curve"`, or `mode="benchmark"` with
+`reference="benchmark_curve"`, gives a chart where the drawn curve and
+the flagging rule are the *same thing* -- no benchmark model to
+explain at all in the first case, or the full benchmark model's
+covariates preserved (just smoothed for display) in the second --
+useful for charts handed to someone who should just be able to look
+and trust it. Other combinations -- e.g. `mode="benchmark"` with
+`reference="curve"` -- are allowed too (draw the benchmark's smoothed
+curve for context, but flag against each segment's own local trend);
+the info box always states plainly which curve is drawn and which
+reference the flagging rule actually used, so no combination is
+ambiguous on the page itself.
+
+`segment_mode="exclusive"` (default) vs. `segment_mode="drilldown"`
+offers the same choice as `export_huber_iqr_pdf`: one page per
+individual's single most-specific segment, or a page for every
+qualifying group at every hierarchy level independently (with the
+expected overlap -- the same individual can appear on multiple pages).
+
+Each page plots every observation in that segment, the reference
+curve, flagged outliers marked distinctly, and an info box (n, flagged
+count/percentage, the segment's MAD, the flagging rule, and which
+curve/reference is in play) so a reviewer can see *why* points are
+flagged directly from the chart, without cross-referencing the numeric
+report.
 Segments with fewer than `min_points_to_plot` (default 5) observations
 are skipped in the PDF -- a chart with a handful of points isn't
 meaningfully verifiable -- but still appear in `mad_outlier_report`'s
@@ -491,7 +753,10 @@ and again in the broader `Level x OT` row), whenever both groupings
 independently meet `min_size`:
 
 ```python
-from robustkit import segment_benchmark_drilldown_report, mad_outlier_drilldown_report
+from robustkit import (
+    segment_benchmark_drilldown_report, mad_outlier_drilldown_report,
+    segment_stability_drilldown_report, outlier_drilldown_summary,
+)
 
 segment_benchmark_drilldown_report(
     df, y_col="salary", segment_cols=["JobFamily", "Level", "OT"], x_col="age", min_size=20,
@@ -499,6 +764,9 @@ segment_benchmark_drilldown_report(
 mad_outlier_drilldown_report(
     df, y_col="salary", segment_cols=["JobFamily", "Level", "OT"], x_col="age", k=3.0,
 )
+segment_stability_drilldown_report(
+    df, x_col="age", y_col="salary", segment_cols=["JobFamily", "Level", "OT"], min_size=20,
+)
 ```
 
 Both add a `segment_level` column, and the sum of `n` across rows will
@@ -507,6 +775,127 @@ overlap, not a bug. Use the exclusive functions when you need to route
 each individual to one home; use the drilldown functions when you want
 to see every level side by side.
 
+**A conclusion that survives multiple reference populations is more
+trustworthy than one that only holds under a single, narrow
+definition of "expected".** `outlier_drilldown_summary` counts how
+many hierarchy levels each individual was flagged on:
+
+```python
+drilldown = mad_outlier_drilldown_report(
+    df, y_col="salary", segment_cols=["JobFamily", "Level", "OT"], x_col="age",
+    k=3.0, id_cols=["employee_id"],
+)
+outlier_drilldown_summary(drilldown, id_col="employee_id")
+#   employee_id  outlier_levels          levels
+```
+
+An individual flagged at every level (finest grouping AND every
+broader fallback) is a stronger candidate than one that only appears
+as an outlier under one specific, narrow segmentation -- a Cook's-
+distance-style robustness check, applied to the choice of reference
+population rather than to individual data points.
+
+### Reference Population Sensitivity: a fourth robustness axis
+
+`robustkit` already checks robustness against fitting method
+(Huber/Tukey/OLS, `core`), individual observations (Cook's impact,
+`core.diagnostics`), and segment granularity (the drilldown functions
+above). `dual_reference_outlier_report` adds a fourth axis: robustness
+against WHICH reference population an individual is compared to.
+
+```python
+from robustkit import dual_reference_outlier_report
+
+report = dual_reference_outlier_report(
+    df, y_col="salary", x_col="age", segment_cols=["JobFamily", "Level", "OT"],
+    min_size=20, k=3.0, id_cols=["employee_id"],
+)
+#   employee_id  ...  local_flagged  global_flagged  reference_type
+```
+
+Each individual's residual is computed against two different
+references simultaneously:
+- **local** -- their own segment's Huber trend, fit fresh on just that
+  segment. Answers "how does this person deviate from their immediate
+  colleagues?"
+- **global** -- the benchmark model (default single-column Huber, or
+  a custom multi-column model). Answers "how does this person deviate
+  from the organization's expected structure?"
+
+`reference_type` classifies each individual: **"A"** (outlier under
+both -- the strongest candidates, low regardless of how "expected" is
+defined), **"B"** (outlier locally only -- often a tightly-clustered
+segment where a modest dip stands out among close peers but not
+against the wider population), **"C"** (outlier globally only --
+often a whole segment trending low while each individual is typical
+within it), or **"D"** (neither -- the normal case).
+
+**A subtlety that matters for what "global" actually means:** the
+global reference's MAD/median is computed across the ENTIRE
+population, not re-centered per segment. If it were centered per
+segment, a segment uniformly shifted below the benchmark would have
+that shift silently absorbed by the per-segment median subtraction --
+nobody in it would ever register as a global outlier, no matter how
+far the whole segment sits from the benchmark, since everyone would
+share roughly the same "typical" residual for their segment. This was
+found by testing, not designed in from the start: an earlier version
+reused `mad_outlier_report`'s per-segment MAD for the "global" side
+and it could never produce a genuine Type C, because per-segment
+recentering makes "global" behave like a second "local" view. It's
+also worth knowing that if segment-level shifts are large relative to
+individual noise AND affect a large share of the population, the
+population-wide MAD naturally inflates to accommodate that variation
+-- so a single shifted segment competing against several
+similarly-large ones may not clear the threshold either; Type C shows
+up most clearly when one segment's shift is a real minority pattern
+against an otherwise-homogeneous majority, not when most segments
+already differ substantially from each other.
+
+`dual_reference_outlier_drilldown_report` extends the same A/B/C/D
+classification to every hierarchy level at once, without exclusive
+assignment -- the drilldown counterpart, same overlap semantics as
+the other drilldown functions:
+
+```python
+from robustkit import dual_reference_outlier_drilldown_report
+
+dual_reference_outlier_drilldown_report(
+    df, y_col="salary", x_col="age", segment_cols=["JobFamily", "Level", "OT"], k=3.0,
+)
+#   ...  segment  segment_level  reference_type
+```
+
+The GLOBAL reference is still computed once across the whole
+population (not per level) for the same reason as above; only the
+LOCAL reference is refit fresh within each group at each level.
+
+### Where does the effect come from: segment_contribution_report
+
+`segment_benchmark_report`/`-drilldown_report` answer "how far from
+benchmark is this segment?" `segment_contribution_report` answers a
+different question: **where in the hierarchy does that gap actually
+arise?**
+
+```python
+from robustkit import segment_contribution_report
+
+segment_contribution_report(
+    df, y_col="salary", segment_cols=["JobFamily", "Level", "OT"], x_col="age", min_size=20,
+)
+#   segment  segment_level  ...  difference  parent_segment  contribution
+```
+
+Each segment's `contribution` is `child_difference - parent_difference`
+-- the part of its benchmark gap NOT already explained by its broader,
+coarser parent. A JobFamily within a Level+OT combination might show a
+large `difference` from benchmark simply because that whole Level+OT
+combination runs high or low (a STRUCTURAL effect, already visible one
+level up); `contribution` isolates whatever remains once that broader
+pattern is subtracted out -- the LOCAL effect specific to this finer
+grouping. Segments at the coarsest hierarchy level have no parent
+within `segment_cols`, so `contribution` is `NaN` and `parent_segment`
+is `None` for them.
+
 ## Combined model + spread view
 
 `plot_analyst_view` and `plot_publisher_view` each show one thing --
@@ -576,6 +965,89 @@ The absence of an error bar at a given age is itself information --
 it signals the sample at that exact value is too small to say
 anything about spread, not just a plotting simplification.
 
+**Per-segment PDF export:** `export_huber_iqr_pdf` renders one
+`plot_huber_iqr` chart per segment -- built from the same automatic
+hierarchical segmentation as the rest of `segment_awareness` -- as a
+one-page-per-segment PDF, suitable for sharing with the people each
+chart describes:
+
+```python
+from robustkit import export_huber_iqr_pdf
+
+export_huber_iqr_pdf(
+    df, x_col="age", y_col="salary", segment_cols=["JobFamily", "Level", "OT"],
+    path="segments.pdf", min_size=20,
+)
+```
+
+Domain-specific segment naming (e.g. translating an internal code like
+`"ENG_P3_Yes"` into a readable label such as "Engineers, level 3,
+overtime-eligible") stays entirely outside the package via an optional
+`title_fn(segment_name, info) -> str` callback, where `info` is
+`{"n", "segment_level"}`:
+
+```python
+def pretty_title(segment_code, info):
+    return f"{my_own_translation(segment_code)} (n={info['n']})"
+
+export_huber_iqr_pdf(..., title_fn=pretty_title)
+```
+
+`export_outlier_pdf` accepts the same `title_fn(segment_name, info)`
+callback for symmetry, with `info` there being `{"n", "n_flagged",
+"pct_flagged", "k", "segment_mad", "segment_level"}` -- useful if
+outlier review PDFs also need domain-specific titles, even though for
+many teams that PDF stays internal and doesn't need one. Both default
+to a generic title when `title_fn` is omitted, so existing calls are
+unaffected.
+
+**`mode="exclusive"` (default) vs. `mode="drilldown"`**, matching the
+same distinction as the report functions above: `"exclusive"` assigns
+each individual to exactly one, most-specific segment -- one page per
+final segment, no overlap. `"drilldown"` instead renders a page for
+EVERY qualifying group at EVERY hierarchy level independently -- e.g.
+a page for `"ENG_P3_Yes"` AND a separate page for the broader
+`"P3_Yes"`, which includes those same individuals alongside everyone
+else at that level. The same individual can appear on multiple pages
+in drilldown mode -- that's the expected signature of overlap, same as
+the drilldown reports:
+
+```python
+export_huber_iqr_pdf(..., mode="drilldown")
+```
+
+All of `plot_huber_iqr`'s style parameters (`methods`, `show_points`,
+`show_bootstrap_band`, `cap_style`, `residual_box_metric`, `ylim`,
+`style`, `show_undersized_points`, ...) pass straight through `export_huber_iqr_pdf` to each
+segment's page -- including `show_points`, which switches between
+"publisher" charts (the default, `show_points=False`, no raw scatter)
+and "analyst" charts (`show_points=True`, individual observations
+visible) without needing to fall back to a manual per-segment loop.
+
+**`export_huber_iqr_images`** is the same function in every respect
+except where the output goes: one image file per segment in a
+directory, instead of one combined PDF. Same segment_cols, same
+`mode`, same `title_fn`, same style parameters -- swap the function
+name and `path` for `output_dir` to get individual files instead of
+pages:
+
+```python
+from robustkit import export_huber_iqr_images
+
+export_huber_iqr_images(
+    df, x_col="age", y_col="salary", segment_cols=["JobFamily", "Level", "OT"],
+    output_dir="salary_plots", mode="drilldown",
+)
+```
+
+Useful whenever per-segment charts get consumed individually --
+dropped into slide decks one at a time, browsed in a file explorer,
+or fed into some other pipeline expecting separate image files --
+rather than as a single document. Filenames are derived from each
+segment's id or label, sanitized for the filesystem; a numeric suffix
+is appended if two segments would otherwise collide. Returns the list
+of saved file paths, in the order rendered.
+
 ## Loading published quantile tables (SCB / JSON-stat)
 
 Some statistics agencies (e.g. Statistics Sweden, SCB) publish
@@ -674,16 +1146,19 @@ from robustkit import (
 )
 
 # Method 1: repeat the mean n times -- zero within-group spread.
-# Recovers between-group regression coefficients reasonably well
+# Equivalent to weighting each group by n (see "What the flat method
+# actually is", below); recovers between-group regression coefficients
 # (validated in the original technique this is based on) but
 # understates individual-level variation.
 flat = expand_aggregated_table_flat(df, n_col="n", mean_col="mean_salary", group_cols=["age"])
 
 # Method 2: borrow a dispersion_ratio from a DIFFERENT table that does
 # report quantiles, and use it to imply an approximate spread around
-# the mean. Stacks two assumptions (mean-as-median, and that the
-# borrowed ratio transfers to this population) -- illustrative, not a
-# substitute for genuine quantile data for this specific table.
+# the given value, which becomes the reconstruction's MEDIAN (see
+# "What the borrowed-dispersion method does with `mean_col`", below).
+# Stacks two assumptions (mean-as-median, and that the borrowed ratio
+# transfers to this population) -- illustrative, not a substitute for
+# genuine quantile data for this specific table.
 borrowed = expand_aggregated_table_borrowed_dispersion(
     df, n_col="n", mean_col="mean_salary", dispersion_ratio=0.45, group_cols=["age"],
 )
@@ -692,6 +1167,53 @@ borrowed = expand_aggregated_table_borrowed_dispersion(
 compare_reconstruction_methods(n=2000, mean=52200, dispersion_ratio=0.45)
 ```
 
+**What the flat method actually is.** Repeating a group's number *n*
+times is exactly the same as weighting that group by *n*. For an
+ordinary least-squares fit whose regressors are constant within each
+group (an age band, say), a fit on the reconstructed rows is identical
+to a fit on the group values weighted by *n* -- and therefore to a fit
+on the original individuals; in a synthetic check, a slope of 1.948
+against 1.950. For a Huber fit it matches a Huber fit on the group
+values weighted by *n* (2.029 against 2.029). robustkit's `fit_*_trend`
+functions take no weights, so this is how to obtain *n*-weighting here.
+Treat it as a workaround rather than a feature: it adds no information
+beyond the group values and sizes. Two practical notes:
+
+- It answers questions about whatever the table's number is. A table of
+  means supports questions about the mean; a table of medians,
+  questions about the typical value. Asking the other question gives
+  large errors -- in the synthetic check, +75% (a means table asked
+  about the typical value) and -37% (a medians table asked about the
+  mean). The `mean_col` argument accepts a median if that is what the
+  table gives.
+- Only the relative group sizes matter, so if the true *n* is very large
+  (national tables can report millions per group), scale every *n* down
+  by a common factor before reconstructing. Scaling by 0.1 changed a
+  fitted slope only in the fourth decimal in the same check; scaling by
+  0.01, which rounds the smallest groups to a few rows, moved it by
+  under half a percent. This applies to the flat method only -- in
+  `expand_aggregated_table` and the borrowed-dispersion reconstruction
+  the number of draws changes the tail, not just the weight.
+
+**What the borrowed-dispersion method does with `mean_col`.** The
+reconstruction's *median* is set to that value, whatever the column is
+called. If the table publishes a median, pass it: the first assumption
+above (mean-as-median) then does not apply, and the reconstruction
+reproduces the median (a published 10.4 came back as 10.3 in a
+synthetic check). If the table publishes a mean, two things follow:
+
+- The reconstruction does not reproduce the mean it was given. A
+  lognormal's mean lies above its median, so the reconstructed mean is
+  about `mean * exp(sigma**2 / 2)`, with
+  `sigma = ln((1 + r/2) / (1 - r/2)) / (2 * 0.6745)` for a borrowed
+  ratio `r`. For `r` = 0.4, 0.8 and 1.2 that is roughly 5%, 22% and 70%
+  above the published mean (15.0 published, 18.3 reconstructed at
+  `r` = 0.8 in the synthetic check).
+- How far a mean sits above its median depends on the spread, so the
+  error this stand-in introduces differs between groups whose spread
+  differs (in the same check the mean was 18% above the median in the
+  youngest age band and 45% above it in the oldest).
+
 Both methods are documented with their specific assumptions rather
 than presented as equally valid defaults -- being explicit about which
 assumption was made lets the analyst judge how much a conclusion