Document interval homogeneity metric semantics

ANALYSIS_PRESET.md

@@ -2,6 +2,8 @@
 
 This page lists **exact control labels** as shown in the Streamlit app. Use the same homogeneity block for every example so results stay comparable.
 
+**What H and related scores mean (not formulas):** [docs/METRIC_SEMANTICS.md](docs/METRIC_SEMANTICS.md).
+
 ## In the app
 
 Open **Analysis presets** at the top of the main page:

QUICK_GUIDE.md

@@ -1,6 +1,6 @@
 # Interface quick guide
 
-Short guide for **non-specialists**: what each option does and **when to use it**. The tool measures **pitch distances** (symbolic intervals on the grid you choose), not “how the orchestra sounds”.
+Short guide for **non-specialists**: what each option does and **when to use it**. The tool measures **pitch distances** (symbolic intervals on the grid you choose), not “how the orchestra sounds”. For metric meaning, limits, and musicological use, see **[docs/METRIC_SEMANTICS.md](docs/METRIC_SEMANTICS.md)**.
 
 **Fixed workflow (thesis / many examples):** [ANALYSIS_PRESET.md](ANALYSIS_PRESET.md) — presets ①–④, pairwise headline **H** by default, exact UI labels.
 

README.md

@@ -4,6 +4,8 @@
 
 Streamlit app for **intervallic homogeneity** in notated pitch aggregates (non-octave-equivalent intervals), from manual note entry or MusicXML — including **H-over-time** passage profiles and **vertical symbolic cardinality** (note-count thickness per slice) for verticality slices.
 
+**Semantic scope:** symbolic / score-based interval descriptors — not audio, spectral, or psychoacoustic consonance analysis. See [docs/METRIC_SEMANTICS.md](docs/METRIC_SEMANTICS.md).
+
 ## Setup
 
 From this directory, install the package in editable mode so the **`iav`** package and root **shims** (`pitch_model`, `analysis_core`, `interval_analysis`) resolve:
@@ -71,6 +73,7 @@ Annotated pilot (human labels): `python scripts/run_annotated_study.py` → `doc
 
 ## Documentation
 
+- **Metric meaning and interpretive limits (H, pair_score, adjacent, EDO, MusicXML):** [docs/METRIC_SEMANTICS.md](docs/METRIC_SEMANTICS.md)
 - **Contributing / CI:** [CONTRIBUTING.md](CONTRIBUTING.md)
 - **Validation protocol (human labels):** [docs/VALIDATION_PROTOCOL.md](docs/VALIDATION_PROTOCOL.md)
 - **Fixed analysis preset (exact UI labels):** [ANALYSIS_PRESET.md](ANALYSIS_PRESET.md)

TECHNICAL_MANUAL.md

@@ -3,6 +3,8 @@
 **Version:** 2026-05-21 (rev. 2) — aligned with `iav.pitch_model`, `iav.musicxml_io`, `iav.interval_analysis_core` (intervallic headline modes), `iav.set_class_12tet`, **`iav/symbolic_profile`**, **`iav/vertical_cardinality`** (§7.8; no PC inference from unique-pitch count), **`iav/charts.py`** (passage timelines: **H** + vertical note count), **`iav/musicxml.py`** (slice summary + JSON), batch/canonical tooling, **`installers/`**, Streamlit (`iav.widgets*`, `pages/1_Which_metric_to_use.py`, `app.py`), root **shims**, and `tests/` (see `docs/ARCHITECTURE.md`, §10).  
 **Scope:** This document specifies **intervallic homogeneity** on a declared EDO grid: how concentrated or diverse the **unordered pairwise interval multiset** is for a notated sonority (§4–§5). Analysis is **symbolic and score-based** (§1.3)—not audition, not psychoacoustics. **Registral dispersion** (register layout, density, banding) is **out of scope**; use a separate tool for that. Optional §12 adds mod-12 interval-class evenness and reference **interval** fingerprints only.
 
+**Interpretive guide:** For musicological reading, what **H**, **pair_score**, **chain_score** (adjacent), proximity-weighted scores, dominance, entropy, and headline modes **mean and do not mean**, see **[docs/METRIC_SEMANTICS.md](docs/METRIC_SEMANTICS.md)** (formulas here remain authoritative for implementation).
+
 **Math formatting:** Delimiters use **MathJax / KaTeX conventions** — inline `$…$`, display `$$…$$` — so the same source renders on **Stack Exchange**, many Markdown previews, and Jupyter. (Avoid legacy LaTeX `\$` / `\\[` delimiters when pasting; use `$` / `$$`.)
 
 ---

docs/ARCHITECTURE.md

@@ -36,6 +36,8 @@ Legacy imports used in notebooks, tests, and older scripts are preserved:
 
 ## Scientific scope (where logic lives)
 
+**Metric semantics (interpretive):** [METRIC_SEMANTICS.md](METRIC_SEMANTICS.md) — what **H**, **pair_score**, **chain_score**, dominance, entropy, EDO, and MusicXML modes measure and do *not* measure.
+
 - **Pitch distance vs spelling:** interval sizes and homogeneity use quantized height from `chromatic_midi_float` / `note_to_units`. Pairwise **labels** are grid summaries, not voice-leading–aware spellings.
 - **Octave:** default pairwise analysis is **not** octave-equivalent unless you interpret §6 pitch-class tools in the technical manual.
 - **Homogeneity (H, bands, “combined”):** implemented under **`iav.interval_analysis_core`**. Four intervallic concentrations (pairwise, adjacent, proximity-weighted linear/quadratic) are always computed; headline **H** selects one via **`IntervallicHeadlineMode`** (default pairwise). Hybrid: `H = α·adjacent + (1−α)·pairwise`. See **`TECHNICAL_MANUAL.md`** §4.5.