hamonpy 0.3.0__py3-none-any.whl

hamonpy/__init__.py

@@ -0,0 +1,5 @@
+"""We implement hamon parsing/normalization and adapters in Python."""
+
+from .parse import parse_hamon, parse_hamon_sequence
+
+__all__ = ["parse_hamon", "parse_hamon_sequence"]

hamonpy/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m hamonpy ...`."""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hamonpy/adapters/__init__.py

@@ -0,0 +1,20 @@
+"""We collect adapters for MEI, MusicXML, Humdrum/**kern, ABC, LilyPond, MuseScore, and music21."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List
+
+from ..ast import HarmonyGroup
+
+@dataclass
+class Adapter:
+    name: str
+    from_: Callable[[Any], List[HarmonyGroup]]
+    to: Callable[[List[HarmonyGroup]], Any]
+
+registry: Dict[str, Adapter] = {}
+
+
+def register(adapter: Adapter) -> None:
+    registry[adapter.name] = adapter

hamonpy/adapters/bps_fh.py

@@ -0,0 +1,161 @@
+"""BPS-FH adapter — Beethoven Piano Sonatas Functional Harmony (Chen & Su) → HamonSequence.
+
+The BPS-FH dataset (https://github.com/Tsung-Ping/functional-harmony) ships one
+``chords.xlsx`` per movement with seven unlabelled columns:
+
+    onset | offset | key | degree | quality | inversion | roman
+
+where ``key`` is a letter (upper = major, lower = minor) with ``-`` = flat / ``+`` =
+sharp (e.g. ``A-`` = A♭ major, ``c+`` = C♯ minor); ``degree`` is a scale degree
+(``1``–``7``, optionally ``-``/``+`` altered and ``P/S`` for a secondary, e.g. ``5/5``);
+``quality`` ∈ {M, m, D7, M7, m7, d, d7, h7, a, a6}; ``inversion`` ∈ {0,1,2,3}; and the
+last column is the analysts' Roman-numeral string.
+
+This adapter reconstructs a **canonical HAMON Roman surface** from the structured
+``degree``/``quality``/``inversion`` columns (so ``°``/``ø``/``+`` and figured-bass tails
+match HAMON's grammar), parses it into the rn/degree layer, attaches each chord's onset
+as a time ``Position``, and turns key changes into ``TonalRegion``s (first = home key,
+later = modulation). Augmented-sixth chords (``a6``: It/Ger/Fr) have no HAMON Roman
+vocabulary yet — their original label (``It+6``…) is preserved as the surface (text).
+
+Reading ``.xlsx`` needs ``openpyxl`` (``pip install -e ./hamonpy[bps]``).
+"""
+from __future__ import annotations
+
+from dataclasses import replace
+from fractions import Fraction as _Fraction
+from pathlib import Path
+from typing import List, Optional
+
+from hamonpy.ast import (
+    Fraction, HamonSequence, HarmonyGroup, HarmonyLabel, Key, PitchClass,
+    Position, RenderingHints, TextSemantic, TonalRegion,
+)
+from hamonpy.parse import parse_hamon_sequence
+
+_ROMAN = {1: "I", 2: "II", 3: "III", 4: "IV", 5: "V", 6: "VI", 7: "VII"}
+
+# quality -> (case, is_seventh, quality_glyph)
+_QUALITY = {
+    "M":  ("upper", False, ""),
+    "m":  ("lower", False, ""),
+    "a":  ("upper", False, "+"),
+    "d":  ("lower", False, "°"),
+    "D7": ("upper", True, ""),
+    "M7": ("upper", True, ""),
+    "m7": ("lower", True, ""),
+    "d7": ("lower", True, "°"),
+    "h7": ("lower", True, "ø"),
+}
+_TRIAD_FIG = {0: "", 1: "6", 2: "64"}
+_SEVENTH_FIG = {0: "7", 1: "65", 2: "43", 3: "42"}
+
+
+def _parse_key(s: str) -> Optional[Key]:
+    s = (s or "").strip()
+    if not s or not s[0].isalpha():
+        return None
+    mode = "minor" if s[0].islower() else "major"
+    acc = {"-": "flat", "+": "sharp"}.get(s[1], None) if len(s) > 1 else None
+    return Key(tonic=PitchClass(note=s[0].upper(), accidental=acc), mode=mode)
+
+
+def _degree_part_to_roman(part: str, case: str) -> Optional[str]:
+    part = part.strip()
+    acc = ""
+    if part and part[0] in "+-":
+        acc = "#" if part[0] == "+" else "b"
+        part = part[1:]
+    if not part.isdigit() or int(part) not in _ROMAN:
+        return None
+    roman = _ROMAN[int(part)]
+    return acc + (roman.lower() if case == "lower" else roman)
+
+
+def _row_to_roman_parts(degree: str, quality: str, inversion: int):
+    """Return ``(primary_surface, secondary_roman_or_None)`` for a BPS-FH row, or
+    ``None`` for unsupported qualities (a6). ``primary_surface`` is a HAMON Roman the
+    grammar parses on its own; the secondary is attached separately because HAMON's
+    Roman grammar rejects flat-prefixed secondaries (e.g. ``/bVII``)."""
+    if quality not in _QUALITY:
+        return None  # a6 (augmented sixth) and any future quality
+    case, is_seventh, glyph = _QUALITY[quality]
+    primary, _, secondary = degree.partition("/")
+    base = _degree_part_to_roman(primary, case)
+    if base is None:
+        return None
+    fig = (_SEVENTH_FIG if is_seventh else _TRIAD_FIG).get(inversion, "7" if is_seventh else "")
+    primary_surface = base + glyph + fig
+    sec = _degree_part_to_roman(secondary, "upper") if secondary else None
+    return primary_surface, sec
+
+
+def _to_fraction(value) -> Optional[Fraction]:
+    try:
+        fr = _Fraction(float(value)).limit_denominator(960)
+    except (TypeError, ValueError):
+        return None
+    return Fraction(numerator=fr.numerator, denominator=fr.denominator)
+
+
+def _rows_to_hamon(rows) -> HamonSequence:
+    """rows: iterable of (onset, key, degree, quality, inversion, roman_label)."""
+    groups: List[HarmonyGroup] = []
+    regions: List[TonalRegion] = []
+    open_key: Optional[int] = None
+    last_key_str: Optional[str] = None
+
+    for onset, key_str, degree, quality, inversion, roman_label in rows:
+        key_str = (str(key_str) if key_str is not None else "").strip()
+        if key_str and key_str != last_key_str:
+            key = _parse_key(key_str)
+            if key is not None:
+                gi = len(groups)
+                if open_key is not None and gi > 0:
+                    regions[open_key].to_group = gi - 1
+                regions.append(TonalRegion(
+                    key=key, kind=("key" if open_key is None else "modulation"), from_group=gi,
+                ))
+                open_key = len(regions) - 1
+            last_key_str = key_str
+
+        parts = _row_to_roman_parts(str(degree), str(quality).strip(), int(inversion))
+        label = None
+        if parts is not None:
+            primary_surface, secondary = parts
+            parsed = parse_hamon_sequence("@rn\n" + primary_surface).groups
+            if parsed and parsed[0].primary[0].semantic.kind == "roman":
+                label = parsed[0].primary[0]
+                full = f"{primary_surface}/{secondary}" if secondary else primary_surface
+                label = replace(label, surface=full)
+                if secondary:
+                    label = replace(label, semantic=replace(label.semantic, secondary=secondary))
+        if label is None:  # a6 / unparseable: preserve the analysts' original label
+            label = HarmonyLabel(
+                surface=str(roman_label), semantic=TextSemantic(text=str(roman_label)),
+                rendering=RenderingHints(), detected_system="text", system="text",
+                sequence_system_hint="rn",
+            )
+        pos = _to_fraction(onset)
+        groups.append(HarmonyGroup(
+            primary=[label], position=Position(time=pos) if pos is not None else None,
+        ))
+
+    return HamonSequence(groups=groups, sequence_system_hint="rn", regions=regions or None)
+
+
+def bps_fh_chords_file_to_hamon(path: str) -> HamonSequence:
+    """Convert one BPS-FH ``chords.xlsx`` (7 unlabelled columns) into a HamonSequence."""
+    try:
+        import pandas as pd  # noqa: PLC0415 - optional, only needed for .xlsx
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError("Reading BPS-FH .xlsx needs pandas+openpyxl: "
+                          "pip install -e ./hamonpy[bps]") from exc
+    df = pd.read_excel(path, header=None)
+    rows = ((r[0], r[2], r[3], r[4], r[5], r[6]) for _, r in df.iterrows())
+    return _rows_to_hamon(rows)
+
+
+def bps_fh_movement_to_hamon(folder: str) -> HamonSequence:
+    """Convert a BPS-FH movement folder (uses ``<folder>/chords.xlsx``)."""
+    return bps_fh_chords_file_to_hamon(str(Path(folder) / "chords.xlsx"))

hamonpy/adapters/choro.py

@@ -0,0 +1,141 @@
+"""Adapter for the DCML *Choro Songbook Corpus* (github.com/DCMLab/choro).
+
+The corpus describes the same music **twice**, which is exactly why HAMON is useful
+here — it makes the two representations comparable:
+
+* ``choro.tsv`` — every piece merged into one table, **one row per chord onset**,
+  with the chord in three encodings (``chord`` absolute, ``rn_chord`` Roman, ``harte``
+  Harte) plus ``local_key``, ``bar_no`` and the form columns (``phrase``/``part``),
+  keyed by ``filename``.
+* ``transcriptions/<piece>.txt`` — a compact **form grammar**:
+
+  ``P<n>: bar | bar | …``   a *phrase*: bars split by ``|``; an empty bar or ``.``
+  holds the previous chord; a bar may hold several space-separated chords.
+  ``PartX[key]: $P1 $P2``   a *part*: a sequence of ``$``-references.
+  ``S[key, meter]: $Intro $PartA …``   the *song*: parts/phrases in order,
+  where ``$ref*N`` repeats a reference ``N`` times.
+
+Expanding the song grammar to its flat chord-onset sequence should reproduce the
+``chord`` column of the TSV — the consistency check in ``use-cases/choro/``.
+
+This adapter only parses; the cross-checks (transcription↔TSV, chord↔Harte↔Roman)
+live in the use-case, built on the parsed models.
+"""
+from __future__ import annotations
+
+import csv
+import io
+import re
+from collections import OrderedDict
+from typing import Dict, List
+
+from hamonpy.ast import HamonSequence, HarmonyGroup, Position
+from hamonpy.parse import parse_hamon_sequence
+from hamonpy.adapters.harte import harte_text_to_hamon
+
+
+# Brazilian songbook notation writes a major seventh as `7M` (e.g. `Bb7M`,
+# `C7M(#11)`); HAMON's chord grammar spells it `maj7`.
+def normalize_chord(chord: str) -> str:
+    """Map corpus chord glyphs to HAMON surface syntax (``7M`` → ``maj7``)."""
+    return re.sub(r"7M", "maj7", chord.strip())
+
+
+# ---------------------------------------------------------------------------
+# transcriptions/<piece>.txt — the form grammar
+# ---------------------------------------------------------------------------
+
+_REF = re.compile(r"^\$(\w+)(?:\*(\d+))?$")
+
+
+def _parse_definitions(text: str) -> "OrderedDict[str, str]":
+    """`LABEL[annot]: BODY` lines → {label: body} (the `[...]` annotation dropped)."""
+    defs: "OrderedDict[str, str]" = OrderedDict()
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or ":" not in line:
+            continue
+        label, body = line.split(":", 1)
+        label = re.sub(r"\[.*?\]", "", label).strip()
+        defs[label] = body.strip()
+    return defs
+
+
+def _expand(label: str, defs: Dict[str, str], seen: tuple = ()) -> List[str]:
+    if label in seen or label not in defs:  # guard against reference cycles
+        return []
+    body = defs[label]
+    out: List[str] = []
+    if "$" in body:  # a reference sequence (a Part, or the song S)
+        for token in body.split():
+            m = _REF.match(token)
+            if m:
+                out += _expand(m.group(1), defs, seen + (label,)) * int(m.group(2) or 1)
+    else:  # a phrase: bars split by "|", chords split by whitespace
+        for bar in body.split("|"):
+            out += bar.split()
+    return out
+
+
+def expand_transcription(text: str, top: str = "S") -> List[str]:
+    """Flat chord-onset surfaces of a `.txt` transcription (the song, expanded).
+
+    Empty bars and ``.`` hold the previous chord, so they are resolved to that
+    chord — giving one surface per onset, aligned with the TSV's ``chord`` column.
+    """
+    defs = _parse_definitions(text)
+    onsets = _expand(top, defs)
+    resolved: List[str] = []
+    prev = None
+    for chord in onsets:
+        chord = prev if chord == "." else chord
+        resolved.append(chord)
+        prev = chord
+    return resolved
+
+
+def transcription_to_hamon(text: str) -> HamonSequence:
+    """Parse a `.txt` transcription into a HamonSequence of chord symbols."""
+    surfaces = [normalize_chord(c) for c in expand_transcription(text)]
+    body = "\n".join(surfaces)
+    return parse_hamon_sequence("@cs\n" + body) if body else HamonSequence(groups=[])
+
+
+# ---------------------------------------------------------------------------
+# choro.tsv — the merged table
+# ---------------------------------------------------------------------------
+
+def read_tsv(text: str) -> "OrderedDict[str, List[dict]]":
+    """Group the merged ``choro.tsv`` rows by piece (``filename``), in file order."""
+    reader = csv.DictReader(io.StringIO(text), delimiter="\t")
+    pieces: "OrderedDict[str, List[dict]]" = OrderedDict()
+    for row in reader:
+        pieces.setdefault(row["filename"], []).append(row)
+    return pieces
+
+
+_COLUMN_SYSTEM = {"chord": "cs", "rn_chord": "rn", "harte": "harte"}
+
+
+def tsv_piece_to_hamon(rows: List[dict], column: str = "chord") -> HamonSequence:
+    """One piece's rows → HamonSequence, from the chosen encoding column.
+
+    ``column`` is ``chord`` (absolute chord symbols, the default), ``rn_chord``
+    (Roman numerals) or ``harte`` (Harte). Each group keeps the ``bar_no`` as its
+    position.
+    """
+    if column not in _COLUMN_SYSTEM:
+        raise ValueError(f"column must be one of {sorted(_COLUMN_SYSTEM)}; got {column!r}")
+    surfaces = [r[column].strip() for r in rows if r.get(column, "").strip()]
+    if column == "harte":
+        seq = harte_text_to_hamon("\n".join(surfaces))
+    else:
+        prefix = "@" + _COLUMN_SYSTEM[column]
+        norm = surfaces if column == "rn_chord" else [normalize_chord(s) for s in surfaces]
+        seq = parse_hamon_sequence(prefix + "\n" + "\n".join(norm)) if norm else HamonSequence(groups=[])
+    # attach bar positions (best-effort; some rows may lack a numeric bar_no)
+    for group, row in zip(seq.groups, rows):
+        bar = row.get("bar_no", "")
+        if bar and str(bar).strip().lstrip("-").isdigit():
+            group.position = Position(measure=int(float(bar)))
+    return seq