PHASE 13.40.DF — Cumulative histogram (cumulative=True/-1)

Adds cumulative: Union[bool, int] = False to hist(). Three values:
  True  → ascending cumulative (each bin = count ≤ right edge)
  False → regular histogram (default, byte-identical backward compat)
  -1    → survival function/CCDF (ROOT convention)

Implementation: ~40 LOC source across 5 forwarding sites (CP1-2 recursive
+ CRR §2.3 NEW faceted dispatch layer):
  Layer 1: DFDraw.hist(cumulative=False)                — named param
  Layer 2: draw_hist(cumulative=False)                  — named param
  Layer 3: _draw_hist_grouped(cumulative=False)         — named param (NEW)
  Layer 4a: ax.hist(cumulative=cumulative) ungrouped    — site 1/4 (line 591)
  Layer 4b: ax.hist(cumulative=cumulative) stacked      — site 2/4 (line 803, CP1-1)
  Layer 4c: ax.hist(cumulative=cumulative) overlaid LS  — site 3/4 (line 878, NEW)
  Layer 4d: ax.hist(cumulative=cumulative) overlaid def — site 4/4 (line 888, NEW)
  Side: _dispatch_faceted_render(cumulative=cumulative) — faceted layer (CRR §2.3)

Every layer forwards explicitly (cumulative=cumulative), NEVER via **kwargs
or kwargs.get — recursively applies Phase 13.39 §2.2 lesson at every
internal layer + faceted side branch (5 forwarding sites total).

Correctness guard (M5):
  hist_errors=True + cumulative=True → NotImplementedError
  (Poisson per-bin errors are independent; cumulative counts have
  correlated uncertainty — silently passing through would render
  statistically wrong error bars on the ECDF.)

CP1-3: drawer.py:3085 docstring fix — drops stale norm='cumulative'
(actual line was 3085, not 3002 as v1.2 spec said; drift from Phase
13.36-13.39 additions).

Compositions locked (10 tests):
  CH.1  monotone non-decreasing + total-N
  CH.2  norm='probability' + cumulative=True → ECDF (max=1.0)
  CH.3  cumulative=-1 + norm='probability' → survival (max=1.0)
  CH.4  cumulative=False byte-identical (backward compat)
  CH.5  group_by + cumulative + hist_norm → per-group ECDFs
  CH.6  hist_errors + cumulative → NotImplementedError (M5)
  CH.7  [x,y] vector + cumulative → both polygons saturate
  CH.8  facet_by + cumulative → per-facet cumulative (CRR §2.3 fix)
  CH.9  histtype='step' + cumulative → Polygon-safe vertex probe
  CH.10 group_by + stacked + cumulative → CP2-1 regression lock

Fix-at-code-time disclosures (CRR §2):
  §2.1: 4 ax.hist() call sites (not 3) — Phase 13.37 split overlaid
        into linestyle_cycle + default branches
  §2.2: Polygon-safe probes in ALL tests (default histtype='stepfilled'
        produces Polygon, not Rectangle — CP1-4 broader than spec)
  §2.3: _dispatch_faceted_render needs explicit cumulative= forward
        (5th forwarding site, not in v1.2 spec)
  §2.4: docstring line drift 3002 → 3085 (caught by §8 protocol)

Tests: 913 → 923 (+10 §9 invariance: CH.1-10).

QRC v1.32 carry-forward AliceO2Group#6 (NEW, recursive forwarding rule):
  'Named param ≠ kwarg after FORWARDED_NAMES promotion applies recursively
   at EVERY forwarding layer including faceted/vector dispatch side
   branches. All N internal call sites must forward explicitly.'

Pre-existing failure (not Phase 13.40):
  test_vector_draw_kwarg_surface_enumeration fails on Linux Py3.12
  (pandas StringDtype in _process_color — Phase 13.39 §2.5 carry-forward).
  Mac Py3.9.6 unaffected.

Author: miranov25

UTILS/dfextensions/dfdraw/docs/CAPABILITY_MATRIX.md

@@ -1,6 +1,6 @@
 # Capability Matrix — dfdraw
 
-**Generated:** 2026-05-21 20:47 UTC
+**Generated:** 2026-05-21 22:27 UTC
 **Phase:** 13.15.DF
 **Generator:** `scripts/generate_capability_matrix.py`
 **Sources:** `tests/feature_taxonomy.py` + `tests/test_layer_classification.py`
@@ -9,13 +9,13 @@
 
 | Status | Count | % |
 |--------|------:|--:|
-| ✅ Verified | 47 | 45% |
+| ✅ Verified | 48 | 45% |
 | ☑️ Smoke-only | 57 | 54% |
 | 🧨 Broken | 0 | 0% |
 | 📋 Planned | 1 | 1% |
-| **Total features** | **105** | |
-| **Total proof tests** | **468** | |
-| **Invariance tests** | **239** | |
+| **Total features** | **106** | |
+| **Total proof tests** | **478** | |
+| **Invariance tests** | **249** | |
 
 **Status key:**
 - ✅ Verified — has at least one invariance test (A ≡ B check)
@@ -167,6 +167,8 @@
 | | **SCATTER** | | |
 | ✅ | **SCATTER.time_axis** — scatter() time_format= pre-conversion: x_data → matplotlib date numbers BEFORE ax.scatter/ax.errorbar — Phase 13.39.DF | 1 | 0 |
 | ✅ | **SCATTER.scatter3d** — draw('z:y:x', type='scatter3d') → 3D point cloud via mpl_toolkits.mplot3d. Reuses Phase 13.38 _process_color() + _process_size() unchanged. color=/size= accept column names or df.eval() expressions. elev=/azim= for ax.view_init(). Stats dict locks mean_x AND mean_y AND mean_z to 1e-9 (CP1-3). Scope boundaries: group_by + scatter3d raises (CP2-1); same=True onto non-3D axes raises (CP2-2). 'y:x' (colon!=2) with type='scatter3d' raises with actionable message — Phase 13.39.DF | 8 | 0 |
+| | **HIST** | | |
+| ✅ | **HIST.cumulative** — hist() cumulative=True/-1/False — ROOT TH1::Draw('cumulative') equivalent. Three values: True (ascending CDF/ECDF), False (default, byte-identical backward compat), -1 (descending/survival, ROOT convention). matplotlib native cumulative= forwarded explicitly at 4 internal call sites (Phase 13.39 §2.2 lesson applied recursively: DFDraw.hist → draw_hist → _draw_hist_grouped → ax.hist; ALSO through _dispatch_faceted_render for facet_by composition). Composes with: norm='probability' (→ ECDF 0-1), group_by overlaid (per-group ECDFs), group_by stacked (CP2-1 regression lock for 3rd call site), facet_by (per-facet cumulative), histtype='step' (HEP-standard step ECDF). Correctness guard (M5): hist_errors+cumulative → NotImplementedError (Poisson per-bin errors are independent; cumulative counts are correlated). Vector dispatch [x,y] propagates cumulative correctly (Phase 13.16.DF FIX1 bug class lock) — Phase 13.40.DF | 10 | 0 |
 
 ---
 

UTILS/dfextensions/dfdraw/drawer.py

@@ -652,6 +652,8 @@ def _auto_label(self, y_expr, x_expr=None):
         'hist_errors', 'linestyle_cycle',
         # Phase 13.39.DF: time-axis formatting (pre-conversion approach)
         'time_format',
+        # Phase 13.40.DF: cumulative histogram (CDF/ECDF/survival)
+        'cumulative',
     )
 
     _SCATTER_FORWARDED_NAMES = (
@@ -3082,7 +3084,9 @@ def draw(
         stats : bool or list, optional
             Show statistics box. True for defaults, or list of stat names.
         norm : str, optional
-            Histogram normalization: "count", "density", "probability", "cumulative".
+            Histogram normalization: "count", "density", "probability".
+            For cumulative distributions, use the `cumulative=True` parameter
+            (Phase 13.40.DF) — NOT norm="cumulative" (raises ValueError).
         title : str, optional
             Plot title.
         ax : matplotlib Axes, optional
@@ -3273,6 +3277,8 @@ def hist(
         nan_policy: str = "filter",
         # Phase 13.39.DF: time-axis formatting (pre-conversion approach)
         time_format: Optional[str] = None,
+        # Phase 13.40.DF: cumulative histogram (CDF/ECDF/survival)
+        cumulative: Union[bool, int] = False,
         # Phase 13.27.DF Commit 2 FIX1 (§7b): weights as column name or
         # df.eval-able expression. Mirrors profile()'s weights= semantics.
         # If both `weights=` and `norm="probability"` are passed, the
@@ -3509,6 +3515,10 @@ def hist(
                 group_by_quantiles=group_by_quantiles,
                 hist_norm=hist_norm,
                 min_entries=min_entries,
+                # Phase 13.40.DF: cumulative must be explicit through faceted
+                # dispatch (recursive QRC v1.32 #6 — every forwarding layer
+                # must pass the named param explicitly). Locked by §9.CH.8.
+                cumulative=cumulative,
                 **kwargs
             )
         # Facet mode (legacy path, same=True ignored in facet mode)
@@ -3551,6 +3561,8 @@ def hist(
                 linestyle_cycle=linestyle_cycle,
                 # Phase 13.39.DF: time-axis formatting
                 time_format=time_format,
+                # Phase 13.40.DF: cumulative histogram (explicit forward)
+                cumulative=cumulative,
                 **kwargs
             )
             axes = ax

UTILS/dfextensions/dfdraw/plots/histogram.py

@@ -240,6 +240,11 @@ def draw_hist(
     linestyle_cycle: bool = False,
     # Phase 13.39.DF: time-axis formatting (pre-conversion approach, CP1-4 auto-detect).
     time_format: Optional[str] = None,
+    # Phase 13.40.DF: cumulative histogram (CDF/ECDF/survival).
+    # False (default) → regular histogram (byte-identical backward compat)
+    # True → ascending cumulative (each bin = count ≤ right edge)
+    # -1 → descending / survival (ROOT convention)
+    cumulative: Union[bool, int] = False,
     **kwargs
 ) -> Tuple[plt.Figure, plt.Axes, Dict[str, Any]]:
     """
@@ -353,6 +358,20 @@ def draw_hist(
         isinstance(x, str) and x in df.columns
         and np.issubdtype(df[x].dtype, np.datetime64)
     )
+
+    # Phase 13.40.DF M5 correctness guard: hist_errors + cumulative is
+    # statistically wrong. Poisson per-bin errors assume independent counts;
+    # cumulative counts have correlated uncertainty. Locked by §9.CH.6.
+    if hist_errors and cumulative:
+        raise NotImplementedError(
+            "hist_errors=True and cumulative=True cannot be composed: "
+            "Poisson per-bin errors assume independent counts; cumulative "
+            "counts have correlated uncertainty (each bin's error depends "
+            "on all prior bins). Use cumulative=True without "
+            "hist_errors=True, or use a single-bin approach for the "
+            "threshold of interest."
+        )
+
     if isinstance(x, str):
         x_name = x
         if _x_is_datetime:
@@ -558,6 +577,11 @@ def draw_hist(
             density=density, weights=_hist_weights,
             alpha=alpha, histtype=histtype, edgecolor=edgecolor,
             linewidth=linewidth,
+            # Phase 13.40.DF CP1-2: cumulative forwarded explicitly to the
+            # grouped path (covers BOTH stacked branch at ~line 803 AND the
+            # 2 overlaid branches at ~847/853). Without this, all 3 grouped
+            # call sites silently drop cumulative.
+            cumulative=cumulative,
             **kwargs   # group_by_bins/hist_norm/min_entries already consumed
         )
         stats_dict["grouped"] = True
@@ -567,7 +591,10 @@ def draw_hist(
         ax.hist(
             x_data, bins=bins, range=_used_range, density=density, weights=_hist_weights,
             color=color, alpha=alpha, histtype=histtype, edgecolor=edgecolor,
-            linewidth=linewidth, label=label, **kwargs
+            linewidth=linewidth, label=label,
+            # Phase 13.40.DF: cumulative histogram (explicit forward — call site 1/4)
+            cumulative=cumulative,
+            **kwargs
         )
         # Phase 13.37.DF: Poisson error bar overlay for ungrouped path.
         # CP1-7: use edges from np.histogram() return (bins= may be int).
@@ -694,6 +721,10 @@ def _draw_hist_grouped(
     # Phase 13.37.DF: pre-computed per-row weights (forwarded from draw_hist
     # for hist_errors weighted-Poisson computation in the grouped path).
     _hist_weights_arr: Optional[np.ndarray] = None,
+    # Phase 13.40.DF CP1-2: cumulative histogram. Recursive named-param
+    # forwarding per QRC v1.32 #6 — DFDraw.hist → draw_hist → _draw_hist_grouped
+    # → ax.hist. NEVER access via kwargs.get/**hist_kwargs.
+    cumulative: Union[bool, int] = False,
     **hist_kwargs
 ) -> int:
     """Draw grouped/overlaid histograms.
@@ -802,7 +833,12 @@ def _draw_hist_grouped(
         hist_kwargs.pop('edgecolor', None)
         ax.hist(data_list, bins=bins_arg, label=labels,
                 color=surviving_colors, edgecolor=_stacked_ec,
-                stacked=True, **hist_kwargs)
+                stacked=True,
+                # Phase 13.40.DF CP1-1: cumulative forwarded explicitly (call
+                # site 2/4 — stacked branch). v1.1 spec missed this site;
+                # added in v1.2 per Sonet50 panel. Locked by §9.CH.10.
+                cumulative=cumulative,
+                **hist_kwargs)
         return len(data_list)
     else:
         # Overlaid histograms — one ax.hist call per surviving group.
@@ -847,13 +883,22 @@ def _draw_hist_grouped(
                 ax.hist(group_data, bins=bins_arg,
                         label=str(group), color=group_color,
                         edgecolor=_ec, linestyle=_per_group_ls,
-                        weights=weights, **hist_kwargs)
+                        weights=weights,
+                        # Phase 13.40.DF: cumulative (call site 3/4 — overlaid
+                        # linestyle_cycle path. Phase 13.37 split overlaid into
+                        # 2 branches; both need explicit forward.)
+                        cumulative=cumulative,
+                        **hist_kwargs)
             else:
                 # No cycle OR user explicit → existing flow (linestyle in **kwargs)
                 ax.hist(group_data, bins=bins_arg,
                         label=str(group), color=group_color,
                         edgecolor=_ec,
-                        weights=weights, **hist_kwargs)
+                        weights=weights,
+                        # Phase 13.40.DF: cumulative (call site 4/4 — overlaid
+                        # default path).
+                        cumulative=cumulative,
+                        **hist_kwargs)
 
             # Phase 13.37.DF: Poisson error bar overlay (CP1-1/CP1-2 fix:
             # color=group_color follows Phase 13.36 sentinel, NOT colors[i]).

UTILS/dfextensions/dfdraw/tests/feature_taxonomy.py

@@ -1312,4 +1312,22 @@
             "test_phase_13_39_df_profile2d_timeaxis.py::TestScatter3D::test_SC3D_8_same_true_non_3d_axes_raises",
         ],
     },
+    # ── Phase 13.40.DF: Cumulative Histogram ──
+    {
+        "id": "HIST.cumulative",
+        "name": "hist() cumulative=True/-1/False — ROOT TH1::Draw('cumulative') equivalent. Three values: True (ascending CDF/ECDF), False (default, byte-identical backward compat), -1 (descending/survival, ROOT convention). matplotlib native cumulative= forwarded explicitly at 4 internal call sites (Phase 13.39 §2.2 lesson applied recursively: DFDraw.hist → draw_hist → _draw_hist_grouped → ax.hist; ALSO through _dispatch_faceted_render for facet_by composition). Composes with: norm='probability' (→ ECDF 0-1), group_by overlaid (per-group ECDFs), group_by stacked (CP2-1 regression lock for 3rd call site), facet_by (per-facet cumulative), histtype='step' (HEP-standard step ECDF). Correctness guard (M5): hist_errors+cumulative → NotImplementedError (Poisson per-bin errors are independent; cumulative counts are correlated). Vector dispatch [x,y] propagates cumulative correctly (Phase 13.16.DF FIX1 bug class lock) — Phase 13.40.DF",
+        "category": "HIST",
+        "tests": [
+            "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_1_monotone_and_total_N_lock",
+            "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_2_ECDF_last_value_is_one",
+            "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_3_survival_starts_at_one",
+            "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_4_cumulative_false_backward_compat",
+            "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_5_group_by_per_group_ecdf",
+            "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_6_hist_errors_plus_cumulative_raises",
+            "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_7_vector_dispatch_propagates_cumulative",
+            "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_8_facet_by_per_facet_ecdf",
+            "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_9_histtype_step_plus_cumulative_polygon_safe",
+            "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_10_group_by_stacked_cumulative_regression_lock",
+        ],
+    },
 ]

UTILS/dfextensions/dfdraw/tests/test_layer_classification.py

@@ -312,5 +312,17 @@
     "test_phase_13_39_df_profile2d_timeaxis.py::TestScatter3D::test_SC3D_7_group_by_raises_value_error": "invariance",
     "test_phase_13_39_df_profile2d_timeaxis.py::TestScatter3D::test_SC3D_8_same_true_non_3d_axes_raises": "invariance",
 
+    # ── Phase 13.40.DF: Cumulative Histogram (10 invariance) ──
+    "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_1_monotone_and_total_N_lock": "invariance",
+    "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_2_ECDF_last_value_is_one": "invariance",
+    "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_3_survival_starts_at_one": "invariance",
+    "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_4_cumulative_false_backward_compat": "invariance",
+    "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_5_group_by_per_group_ecdf": "invariance",
+    "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_6_hist_errors_plus_cumulative_raises": "invariance",
+    "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_7_vector_dispatch_propagates_cumulative": "invariance",
+    "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_8_facet_by_per_facet_ecdf": "invariance",
+    "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_9_histtype_step_plus_cumulative_polygon_safe": "invariance",
+    "test_phase_13_40_df_cumulative_hist.py::TestCumulativeHist::test_CH_10_group_by_stacked_cumulative_regression_lock": "invariance",
+
     # Everything else defaults to "smoke"
 }