Phase 13.17.DF v1.0: documentation refresh

- docs/README.md: full rewrite (883 lines, was 710) reflecting Phase 13.12-13.16
  features. New sections: 'What's New in Phase 13.16.DF', 'Multi-Plot Overlays
  (same=True)', 'Vector Expressions', 'Auto-Title'. Mode 2 (AliasDataFrame)
  rewritten per ADF team Q&A with aDF.draw() as primary API and vector form
  recommended for multi-series. Mode 3 (RDataFrameDSL) revised to prefer vector
  syntax for multi-series overlays. Toolkit architecture table updated with
  RootInteractive status per architect Q&A. Expression Syntax table extended
  with bracket-vector rows. API table includes vector_style, group_style,
  auto_title, same parameters. Test file list updated (19 files, all verified
  against git ls-files). Test count 310 -> 451. Dead references removed
  (dfdraw_README.md, dfdraw_api_summary.md, test_facet.py).

- examples/generate_gallery.py: full rewrite (600 lines) with 10 ALICE-flavored
  examples covering the full feature set. Per-example reproducible seeds.
  Example 08 is the vector-expression ITS centerpiece — two-panel figure
  showing the AD-37 bug reproduction (left: scalar loop with fresh DFDraw per
  call, 2 colors for 6 layers) alongside the Phase 13.16.DF fix (right: vector
  expression in a single call, 6 distinct colors). ALICE data generators
  (TPC tracks, ITS residuals, pulls) with physically-plausible distributions.
  Executed cleanly in production environment (10/10 figures generated).

- examples/dfdraw_gallery.ipynb: new Jupyter notebook (27 cells) mirroring
  generate_gallery.py 1:1 with markdown commentary per example. Self-contained
  cells for experimentation. CI-testable via pytest-nbmake or nbconvert.
  Example 08 has extra markdown explaining the expected AD-37 before/after
  visual. Architect-confirmed to execute cleanly.

- docs/dfdraw_PLOTTING_LIBRARY_COMPARISON.md: light refresh (342 lines,
  was 301). Added Phase 13.12-13.16 feature capabilities to ROOT TTree::Draw
  'What to Keep' table (auto-title, same=True, vector expressions, batch QA).
  Added new rows to Plot Types comparison matrix. Phase 2 renamed, Phase 2b
  added for Interactive Features (Phase 13.12-13.16.DF) with 8 sub-items.
  Phase 3 Backend Abstraction and Phase 4 RootInteractive Integration
  checklists updated per architect Q&A (HistoNdCDS done, HTML export done
  in RootInteractive but not wired to dfdraw, bridge module not started).
  Current Status Summary updated (451 tests, 43 features, 21 invariance).
  Revision history entry 1.2. Strategic/architectural content preserved
  verbatim from v1.1.

- docs/examples/*.png: 10 generated ALICE-flavored gallery figures (source of
  truth is generate_gallery.py).

Repository hygiene:
- Removed root-level dfdraw_Technical_Summary.md (duplicate of docs/ version;
  current canonical location is docs/dfdraw_Technical_Summary.md as of
  Phase 13.16.DF).
- Moved dfdraw_PLOTTING_LIBRARY_COMPARISON.md into docs/ (was at project root).

Governance:
- First application of 'doc-only phase' lightweight gate pattern per Org v1.25
  § Phase Lifecycle (justified in proposal §5.2: content derived from already-
  reviewed authoritative Phase 13.16.DF docs + ADF/RootInteractive team Q&A).
- Single reviewer: Claude40 (author self-check). Independent cross-check:
  Claude42 (non-author, per proposal review Group F). Architect visual
  confirmation pre-review: gallery figures verified, notebook execution
  verified, text reasonableness confirmed.
- Q&A-driven cross-team content: ADF team Q&A served as source-of-truth for
  README Mode 2 content with per-question traceability. RootInteractive team
  Q&A informed toolkit architecture table and PLOTTING_LIBRARY_COMPARISON
  Phase 4 status.

Deferred to follow-up (not blocking):
- docs/API_REFERENCE.md: 8 small clarity patches (4 GPT5 P1 items from
  Phase 13.16.DF documentation review + 4 Claude42 D-P2 items from
  Phase 13.16.DF documentation review). Tracked as Phase 13.17.1.DF or
  rolled into next doc-touch phase.
- ADF-side persistent DFDraw cache for scalar same=True loops (architect is
  considering; suggested future phase: Phase 13.13.ADF v1.0).
- MTTU codification of doc-only phase lightweight gate pattern.

Approved by:
- PHASE_13_17_DF_v1_0_Proposal_DocumentationRefresh.md (5 of 5 reviewers)
- PHASE_13_17_DF_v1_0_PROPOSAL_REVIEW_SUMMARY.md
- PHASE_13_17_DF_v1_0_CODE_REVIEW_REQUEST.md (this document)

Prior phase: PHASE_13_16_DF_v1_0_END

Author: miranov25

…aw/dfdraw_PLOTTING_LIBRARY_COMPARISON.md …cs/dfdraw_PLOTTING_LIBRARY_COMPARISON.mdUTILS/dfextensions/dfdraw/dfdraw_PLOTTING_LIBRARY_COMPARISON.md renamed to UTILS/dfextensions/dfdraw/docs/dfdraw_PLOTTING_LIBRARY_COMPARISON.md UTILS/dfextensions/dfdraw/dfdraw_PLOTTING_LIBRARY_COMPARISON.md renamed to UTILS/dfextensions/dfdraw/docs/dfdraw_PLOTTING_LIBRARY_COMPARISON.md

@@ -1,16 +1,21 @@
 # Plotting Library Comparison for dfdraw Wrapper Design
 
-**Date:** 2026-01-29 (Updated)  
-**Purpose:** Inform wrapper design for dfdraw with potential RootInteractive backend  
-**Author:** Claude2-dfdraw (Coder)
+**Date:** 2026-04-09 (Phase 13.17.DF refresh)
+**Original:** 2026-01-29 (Phase 13.6.G.DF initial version)
+**Purpose:** Inform wrapper design for dfdraw with potential RootInteractive backend
+**Author:** Claude2-dfdraw (original), Claude40 (Phase 13.17.DF status refresh)
 
 ---
 
 ## Executive Summary
 
 This document compares dfdraw with other Python plotting libraries and ROOT to inform the design of a unified wrapper interface. The goal is to preserve ROOT's best features (one-liner syntax, rich statistics) while leveraging Python's ecosystem and avoiding ROOT's pain points.
 
-**Update (Phase 13.6.G.DF):** Statistics enhancements now complete. dfdraw has full ROOT parity for statistics features.
+**Update (Phase 13.6.G.DF, 2026-01-29):** Statistics enhancements complete. dfdraw has full ROOT parity for statistics features.
+
+**Update (Phase 13.16.DF, 2026-04-09):** Vector expression interface complete. Bracket-vector syntax (`"[y1,y2,y3]:x"`) provides single-call multi-series overlay, resolving the AD-37 AliasDataFrame color-cycling bug via architectural fix. 7 strong A≡B invariance tests establish the new testing quality bar.
+
+**Update (Phase 13.17.DF, 2026-04-09):** This document refreshed to reflect Phase 13.12–13.16 capability additions. Status tables updated; backend abstraction section annotated with current RootInteractive integration status. No structural changes; strategic/architectural framing preserved from original.
 
 ---
 
@@ -62,6 +67,10 @@ This document compares dfdraw with other Python plotting libraries and ROOT to i
 | **2D histograms** | `tree->Draw("y:x", "", "colz")` | `drawer.draw("y:x", type="hist2d")` | Density visualization |
 | **Population std** | ddof=0 | ddof=0 (Phase 13.6.G.DF) | ROOT compatibility |
 | **Range-aware stats** | Within range only | range_x, range_y (Phase 13.6.G.DF) | Filtered statistics |
+| **Auto-title from expression** | Auto | `auto_title=True` (Phase 13.12.DF) | QA plot caption automation |
+| **Multi-plot overlay on same axes** | `"same"` option | `same=True` (Phase 13.13.DF) | Superposition without manual axes |
+| **Multi-series from column list** | `tree->Draw("y1:x"); tree->Draw("y2:x","","same")` (loop) | `drawer.draw("[y1,y2,y3]:x")` (Phase 13.16.DF) | Single-call vector expression; fixes ADF color-cycling (AD-37) |
+| **Batch QA dashboards** | Canvas + Divide loop | `draw_batch(specs)` with group format (Phase 13.14.DF) | YAML/JSON spec-driven QA |
 
 ### ❌ Bad Parts (Avoid in Wrapper)
 
@@ -108,6 +117,9 @@ This document compares dfdraw with other Python plotting libraries and ROOT to i
 | Hexbin | - | `hexbin()` | - | `hexbin()` | ✅ |
 | Facet/Grid | - | `subplots` | `FacetGrid` | `facet=True` | Layout system |
 | Group overlay | - | Manual | `hue=` | `group_by=` | ✅ |
+| **Same-axes superposition** | **`"same"` option** | **Manual `ax=`** | **Manual** | **`same=True` (13.13.DF)** | **figureArray** |
+| **Vector expression (multi-series)** | **Loop + "same"** | **Manual loop** | **`melt()` + `hue=`** | **`"[y1,y2]:x"` (13.16.DF)** | **figureArray** |
+| **Batch QA dashboard** | **Canvas + Divide** | **Manual subplots** | **FacetGrid** | **`draw_batch` group format (13.14.DF)** | **widgetArray + figureArray** |
 
 ---
 
@@ -204,10 +216,10 @@ drawer.draw_batch(specs, backend='rootinteractive', save_dir='dashboards/')
 
 ## Feature Parity Checklist
 
-### Phase 1: Core Parity (Current dfdraw) ✅ COMPLETE
+### Phase 1: Core Parity (Phase 13.5 and earlier) ✅ COMPLETE
 - [x] 1D/2D histograms
 - [x] Scatter plots
-- [x] Profile plots  
+- [x] Profile plots
 - [x] Hexbin plots
 - [x] Grouping/overlay
 - [x] Faceting
@@ -222,33 +234,58 @@ drawer.draw_batch(specs, backend='rootinteractive', save_dir='dashboards/')
 - [x] Population std (ddof=0) for ROOT match
 - [x] 2D n counts both-valid pairs
 
-### Phase 3: Backend Abstraction (Future)
-- [ ] PlotSpec intermediate representation
-- [ ] Matplotlib backend (refactor)
-- [ ] Bokeh backend
-- [ ] RootInteractive backend
-- [ ] Plotly backend (optional)
+### Phase 2b: Interactive Features (Phase 13.12–13.16.DF) ✅ COMPLETE
+- [x] **Auto-title from expression** (Phase 13.12.DF v1.2) — `auto_title=True` / style key
+- [x] **Profile enhancements** (Phase 13.12.DF) — `return_data`, `min_entries`, `group_by_bins`, `group_by_quantiles`, `sort_groups`, `weights`
+- [x] **Same-axes superposition** (Phase 13.13.DF) — `same=True` for all draw methods, auto-color, auto-label
+- [x] **Batch group format** (Phase 13.14.DF) — `draw_batch` with defaults cascade, subplot grids, `verbose=2` debug
+- [x] **Test infrastructure** (Phase 13.15.DF) — feature taxonomy (43 features), capability matrix, `run_tests.sh`, reviewer.zip packaging
+- [x] **Vector expression interface** (Phase 13.16.DF) — bracket syntax `"[y1,y2,y3]:x"`, `"y:[x1,x2]"`, `"[y1,y2]:[x1,x2]"`, paren-aware split, `vector_style`/`group_style` channels
+- [x] **Strong A≡B invariance testing** (Phase 13.16.DF) — 7 byte-identical axis + per-pair stats comparisons
+- [x] **AD-37 architectural fix** (Phase 13.16.DF) — single-instance vector path bypasses AliasDataFrame color-cycling bug
+
+### Phase 3: Backend Abstraction (Partially Complete)
+
+Status updated 2026-04-09 per architect Q&A (PHASE_END_PHASE-0.2.A):
+
+- [ ] **PlotSpec intermediate representation** — Not started
+- [x] **Matplotlib backend (refactor)** — Current production backend, in use
+- [ ] **Bokeh backend** — Not started
+- [ ] **RootInteractive backend** — Bridging module proposed but not implemented; architecture direction (e.g., `dfdraw.backends.rootinteractive`) is architect decision pending
+- [ ] **Plotly backend (optional)** — Not started
+
+**Summary:** Backend abstraction as a formal architectural layer has not been built. dfdraw continues to use matplotlib directly. The RootInteractive foundation work (see Phase 4 below) is proceeding in the RootInteractive repository; the dfdraw-facing bridge remains proposal/prototype stage.
+
+### Phase 4: RootInteractive Integration (Partially Complete)
+
+Status updated 2026-04-09 per RootInteractive team Q&A (PHASE_END_PHASE-0.2.A):
+
+- [x] **N-dimensional histogram export** — Done in RootInteractive (`HistoNdCDS` exists and is validated)
+- [ ] **Dashboard layout specification** — Not started (no dfdraw-facing spec)
+- [x] **HTML export** — Done in RootInteractive itself via `bokehDrawSA.fromArray()`, but not wired to dfdraw
+- [ ] **Live aggregation mode** — Not started
+
+**Summary:** RootInteractive foundation capabilities (compression, histograms, ONNX, joins) are advancing in phases 0.1.B–0.2.A of the RootInteractive repository. There is currently no implemented dfdraw→RootInteractive integration layer — none of the API patterns proposed in the [Proposed Wrapper Architecture](#proposed-wrapper-architecture) section above are functional today. When the bridging work begins, the RootInteractive team will communicate the phase ID, API shape, and stability level.
 
-### Phase 4: RootInteractive Integration (Future)
-- [ ] N-dimensional histogram export
-- [ ] Dashboard layout specification
-- [ ] HTML export
-- [ ] Live aggregation mode
+**For dfdraw users today:** use matplotlib backend (the default and only working backend). For interactive multi-dimensional exploration of ALICE data, use RootInteractive directly at https://github.com/miranov25/RootInteractive.
 
 ---
 
 ## Current Status Summary
 
-### dfdraw Capabilities (Phase 13.6.G.DF)
+### dfdraw Capabilities (Phase 13.16.DF, refreshed Phase 13.17.DF)
 
 | Category | Status | Details |
 |----------|--------|---------|
 | **Plot Types** | ✅ Complete | 5 types: hist, scatter, profile, hist2d, hexbin |
-| **Statistics** | ✅ Complete | Full ROOT parity including robust stats |
+| **Statistics** | ✅ Complete | Full ROOT parity including robust stats (Phase 13.6.G.DF) |
+| **Multi-series overlay** | ✅ Complete | Vector expressions + `same=True` chaining (Phases 13.13.DF, 13.16.DF) |
+| **Batch QA** | ✅ Complete | Group format, subplot grid, defaults cascade (Phase 13.14.DF) |
+| **Auto-title** | ✅ Complete | Expression-derived titles (Phase 13.12.DF v1.2) |
 | **Styling** | ✅ Complete | Global + per-plot + matplotlib pass-through |
 | **Integration** | ✅ Complete | AliasDataFrame, PyArrow, batch mode |
-| **Testing** | ✅ Complete | 310 tests, 100% passing |
-| **Documentation** | ✅ Complete | README, API_REFERENCE, PHASE_HISTORY |
+| **Testing** | ✅ Complete | 451 tests, 43 features, 21 invariance tests, 100% passing |
+| **Documentation** | ✅ Complete | README (refreshed Phase 13.17.DF), API_REFERENCE, PHASE_HISTORY, Technical Summary, Capability Matrix |
 
 ### ROOT Compatibility Achieved
 
@@ -259,6 +296,9 @@ drawer.draw_batch(specs, backend='rootinteractive', save_dir='dashboards/')
 | 2D both-valid n | Yes | Yes | ✅ Match |
 | Auto stats fields | Yes | Yes | ✅ Match |
 | Robust stats | Yes | Yes | ✅ Match |
+| Multi-series overlay | `"same"` option | `same=True` / vector `"[y1,y2]:x"` | ✅ Match (two paths) |
+| Auto-title | Auto | `auto_title=True` | ✅ Match |
+| Batch QA dashboard | Canvas + Divide | `draw_batch` group format | ✅ Match |
 
 ---
 
@@ -299,3 +339,4 @@ drawer.draw_batch(specs, backend='rootinteractive', save_dir='dashboards/')
 |---------|------|---------|
 | 1.0 | 2026-01-29 | Initial comparison document |
 | 1.1 | 2026-01-29 | Updated for Phase 13.6.G.DF completion: statistics enhancements complete, ROOT parity achieved |
+| 1.2 | 2026-04-09 | Phase 13.17.DF refresh: added Phase 13.12–13.16 feature capabilities (auto-title, same=True, draw_batch groups, vector expressions, strong invariance testing, AD-37 architectural fix); updated Plot Types and ROOT TTree::Draw "What to Keep" matrices with new multi-series / vector / batch rows; updated Phase 3 Backend Abstraction and Phase 4 RootInteractive Integration checklists with current status per architect Q&A (2026-02-22); test count 310 → 451, feature count → 43, added invariance test count 21; Current Status Summary updated with new capability categories. Strategic/architectural framing preserved verbatim from v1.1; no structural changes.