Upload 7 files

README.md

@@ -1,13 +1,47 @@
 ---
-title: Language Attrition Speech Variables
-emoji: 📈
-colorFrom: red
-colorTo: red
+title: Language Attrition - derive & model
+emoji: 📊
+colorFrom: indigo
+colorTo: pink
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: 4.44.1
+python_version: "3.10"
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Language Attrition: derive the numbers, then model them
+
+A point-and-click tool for the *Bye-lingual* seminar. No transcribing, no
+Spanish, no Praat, no code. Runs on CPU (it does **not** transcribe audio).
+
+**Tab 1 - Derive.** Upload a recording **and its transcript** (the existing
+word-timestamped `.json`). The app derives ~25 linguistic factors: disfluency
+(filled / empty pauses, repetitions, retractions), fluency (speech /
+articulation rate, phonation %), complexity (MLU, TTR, MTLD), and acoustics (F0,
+jitter, shimmer, HNR, spectral tilt, MFCCs). Stack several speakers and download
+the table.
+
+**Tab 2 - Model.** Use the table you built (or upload a CSV joined with your
+questionnaire predictors), pick two variables, and get the scatter, the
+correlation (Pearson or Spearman), and the regression line. A correlation
+heatmap shows all variables at once.
+
+The numbers are identical to the course pipeline (same `markers.py` /
+`acoustic_markers.py`). Transcription is **not** done here: this Space consumes an
+existing transcript. Phase-2 markers (VOT, vowel space, rhythm) need forced
+alignment (MFA) and are not produced.
+
+## Transcript format
+A JSON file, either a bare list or `{"chunks": [...]}`, where each chunk is:
+```json
+{"text": "Pues", "timestamp": {"start": 2.94, "end": 3.08}}
+```
+The `[*]` disfluency markers must be kept. Per-speaker transcripts can be
+exported from the pipeline with `pipeline/export_transcripts_json.py`.
+
+## Files
+- `app.py` - Gradio UI (Derive + Model tabs)
+- `features.py` - parse transcript → extract_markers → flat feature row
+- `markers.py`, `acoustic_markers.py`, `alignment_markers.py` - vendored from `pipeline/`

acoustic_markers.py

@@ -0,0 +1,258 @@
+"""Phase 1 acoustic markers: F0, voice quality, spectral tilt, and MFCCs.
+
+Extracts features directly from the audio waveform using parselmouth (Praat)
+and librosa.  No forced alignment required — operates on the full recording
+or on voiced segments detected by Praat's pitch algorithm.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import parselmouth
+from parselmouth.praat import call
+import librosa
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _load_sound(audio_path: str) -> parselmouth.Sound:
+    """Load audio as a parselmouth Sound object."""
+    return parselmouth.Sound(audio_path)
+
+
+def _voiced_f0(pitch: parselmouth.Pitch) -> np.ndarray:
+    """Return only the voiced (non-zero) F0 values from a Pitch object."""
+    f0 = pitch.selected_array["frequency"]
+    return f0[f0 > 0]
+
+
+# ---------------------------------------------------------------------------
+# F0 / pitch markers
+# ---------------------------------------------------------------------------
+
+def extract_f0(sound: parselmouth.Sound,
+               time_step: float = 0.01,
+               floor: float = 75.0,
+               ceiling: float = 600.0) -> dict:
+    """Extract fundamental frequency statistics.
+
+    Returns mean, median, SD, min, max, range, slope (Hz/s), and
+    the coefficient of variation for voiced frames.
+    """
+    pitch = sound.to_pitch_cc(time_step=time_step,
+                              pitch_floor=floor,
+                              pitch_ceiling=ceiling)
+    f0 = _voiced_f0(pitch)
+
+    if len(f0) < 2:
+        return {
+            "f0_mean_hz": None, "f0_median_hz": None,
+            "f0_sd_hz": None, "f0_min_hz": None,
+            "f0_max_hz": None, "f0_range_hz": None,
+            "f0_cv": None, "f0_slope_hz_per_s": None,
+            "voiced_frames": int(len(f0)),
+        }
+
+    # F0 slope: linear regression over voiced frames
+    times = np.arange(len(f0)) * time_step
+    slope = float(np.polyfit(times, f0, 1)[0])
+
+    return {
+        "f0_mean_hz": round(float(np.mean(f0)), 2),
+        "f0_median_hz": round(float(np.median(f0)), 2),
+        "f0_sd_hz": round(float(np.std(f0, ddof=1)), 2),
+        "f0_min_hz": round(float(np.min(f0)), 2),
+        "f0_max_hz": round(float(np.max(f0)), 2),
+        "f0_range_hz": round(float(np.max(f0) - np.min(f0)), 2),
+        "f0_cv": round(float(np.std(f0, ddof=1) / np.mean(f0)), 4),
+        "f0_slope_hz_per_s": round(slope, 4),
+        "voiced_frames": int(len(f0)),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Voice quality markers (jitter, shimmer, HNR)
+# ---------------------------------------------------------------------------
+
+def extract_voice_quality(sound: parselmouth.Sound,
+                          floor: float = 75.0,
+                          ceiling: float = 600.0) -> dict:
+    """Extract jitter, shimmer, and harmonics-to-noise ratio.
+
+    Uses Praat's standard algorithms via parselmouth.
+    """
+    pitch = sound.to_pitch_cc(pitch_floor=floor, pitch_ceiling=ceiling)
+    point_process = call(sound, "To PointProcess (periodic, cc)",
+                         floor, ceiling)
+
+    # Duration bounds for the measurements
+    t_start = sound.xmin
+    t_end = sound.xmax
+
+    # --- Jitter ---
+    jitter_local = call(point_process, "Get jitter (local)",
+                        t_start, t_end, 0.0001, 0.02, 1.3)
+    jitter_rap = call(point_process, "Get jitter (rap)",
+                      t_start, t_end, 0.0001, 0.02, 1.3)
+
+    # --- Shimmer ---
+    shimmer_local = call([sound, point_process], "Get shimmer (local)",
+                         t_start, t_end, 0.0001, 0.02, 1.3, 1.6)
+    shimmer_local_db = call([sound, point_process], "Get shimmer (local_dB)",
+                            t_start, t_end, 0.0001, 0.02, 1.3, 1.6)
+
+    # --- HNR ---
+    harmonicity = call(sound, "To Harmonicity (cc)",
+                       0.01, floor, 0.1, 1.0)
+    hnr_mean = call(harmonicity, "Get mean", t_start, t_end)
+
+    def _safe_round(v, n=4):
+        if v is None or (isinstance(v, float) and np.isnan(v)):
+            return None
+        return round(v, n)
+
+    return {
+        "jitter_local_pct": _safe_round(jitter_local * 100 if jitter_local else None),
+        "jitter_rap_pct": _safe_round(jitter_rap * 100 if jitter_rap else None),
+        "shimmer_local_pct": _safe_round(shimmer_local * 100 if shimmer_local else None),
+        "shimmer_local_db": _safe_round(shimmer_local_db),
+        "hnr_mean_db": _safe_round(hnr_mean, 2),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Spectral tilt (H1-H2)
+# ---------------------------------------------------------------------------
+
+def extract_spectral_tilt(sound: parselmouth.Sound,
+                          floor: float = 75.0,
+                          ceiling: float = 600.0,
+                          time_step: float = 0.01) -> dict:
+    """Estimate H1-H2 (difference between first and second harmonic amplitudes).
+
+    Measured at each voiced frame using the spectrum; returns the mean
+    across the recording.  H1-H2 > 0 indicates breathier phonation.
+    """
+    pitch = sound.to_pitch_cc(time_step=time_step,
+                              pitch_floor=floor,
+                              pitch_ceiling=ceiling)
+
+    h1_h2_values = []
+    n_frames = pitch.get_number_of_frames()
+
+    for i in range(1, n_frames + 1):
+        f0_val = pitch.get_value_in_frame(i)
+        if f0_val == 0 or np.isnan(f0_val):
+            continue
+
+        t = pitch.get_time_from_frame_number(i)
+        # Extract a short window around this frame
+        win_start = max(sound.xmin, t - 0.025)
+        win_end = min(sound.xmax, t + 0.025)
+        if win_end - win_start < 0.02:
+            continue
+
+        try:
+            segment = sound.extract_part(win_start, win_end,
+                                         parselmouth.WindowShape.HANNING, 1.0, False)
+            spectrum = segment.to_spectrum()
+
+            # H1: amplitude at F0, H2: amplitude at 2*F0
+            h1_freq = f0_val
+            h2_freq = 2 * f0_val
+            # Get bin indices closest to H1 and H2
+            bin_h1 = max(1, round(h1_freq / spectrum.dx))
+            bin_h2 = max(1, round(h2_freq / spectrum.dx))
+            n_bins = spectrum.get_number_of_bins()
+
+            if bin_h1 > n_bins or bin_h2 > n_bins:
+                continue
+
+            amp_h1 = abs(spectrum.get_value_in_bin(bin_h1))
+            amp_h2 = abs(spectrum.get_value_in_bin(bin_h2))
+
+            if amp_h1 > 0 and amp_h2 > 0:
+                h1_db = 20 * np.log10(amp_h1)
+                h2_db = 20 * np.log10(amp_h2)
+                h1_h2_values.append(h1_db - h2_db)
+        except Exception:
+            continue
+
+    if not h1_h2_values:
+        return {"h1_h2_mean_db": None, "h1_h2_sd_db": None}
+
+    return {
+        "h1_h2_mean_db": round(float(np.mean(h1_h2_values)), 2),
+        "h1_h2_sd_db": round(float(np.std(h1_h2_values, ddof=1)), 2)
+            if len(h1_h2_values) > 1 else None,
+    }
+
+
+# ---------------------------------------------------------------------------
+# MFCCs (via librosa — already a project dependency)
+# ---------------------------------------------------------------------------
+
+def extract_mfccs(audio_path: str,
+                  sr: int = 22050,
+                  n_mfcc: int = 13,
+                  n_fft: int = 2048,
+                  hop_length: int = 512) -> dict:
+    """Extract MFCC summary statistics from the full recording.
+
+    Returns per-coefficient mean and SD, plus the overall mean of
+    delta and delta-delta MFCCs.
+    """
+    y, sr_actual = librosa.load(audio_path, sr=sr)
+
+    mfccs = librosa.feature.mfcc(y=y, sr=sr_actual,
+                                 n_mfcc=n_mfcc,
+                                 n_fft=n_fft,
+                                 hop_length=hop_length)
+    delta = librosa.feature.delta(mfccs)
+    delta2 = librosa.feature.delta(mfccs, order=2)
+
+    # Per-coefficient statistics (mean across time)
+    mfcc_means = np.mean(mfccs, axis=1)
+    mfcc_sds = np.std(mfccs, axis=1, ddof=1)
+
+    result: dict = {}
+
+    # Individual coefficient means (MFCC-1 through MFCC-13)
+    for i in range(n_mfcc):
+        result[f"mfcc_{i+1}_mean"] = round(float(mfcc_means[i]), 4)
+        result[f"mfcc_{i+1}_sd"] = round(float(mfcc_sds[i]), 4)
+
+    # Summary across all coefficients for delta and delta-delta
+    result["mfcc_delta_mean"] = round(float(np.mean(delta)), 6)
+    result["mfcc_delta_sd"] = round(float(np.std(delta, ddof=1)), 6)
+    result["mfcc_delta2_mean"] = round(float(np.mean(delta2)), 6)
+    result["mfcc_delta2_sd"] = round(float(np.std(delta2, ddof=1)), 6)
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def extract_acoustic_markers(audio_path: str) -> dict:
+    """Extract all Phase-1 acoustic markers from an audio file.
+
+    Returns a dict with sub-keys: "f0", "voice_quality", "spectral_tilt",
+    and "mfcc".
+    """
+    sound = _load_sound(audio_path)
+
+    f0 = extract_f0(sound)
+    vq = extract_voice_quality(sound)
+    tilt = extract_spectral_tilt(sound)
+    mfcc = extract_mfccs(audio_path)
+
+    return {
+        "f0": f0,
+        "voice_quality": vq,
+        "spectral_tilt": tilt,
+        "mfcc": mfcc,
+    }

alignment_markers.py

@@ -0,0 +1,643 @@
+"""Phase 2 alignment-based markers: VOT, vowel formants, rhythm metrics.
+
+Requires:
+  - Montreal Forced Aligner (``mfa``) on PATH — install via conda:
+        conda install -c conda-forge montreal-forced-aligner
+        mfa model download acoustic spanish_mfa
+        mfa model download dictionary spanish_mfa
+  - praatio for TextGrid parsing (pip install praatio)
+  - parselmouth (already installed in Phase 1)
+
+Workflow:
+  1. ``prepare_corpus``  — write .lab files from Whisper transcripts
+  2. ``run_mfa_alignment`` — call ``mfa align`` via subprocess
+  3. ``extract_alignment_markers`` — read TextGrid + audio → features
+"""
+
+from __future__ import annotations
+
+import math
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+import numpy as np
+import parselmouth
+from parselmouth.praat import call
+from praatio import textgrid as tgio
+
+# ---------------------------------------------------------------------------
+# Phone‐set definitions  (MFA Spanish IPA inventory)
+# ---------------------------------------------------------------------------
+
+VOWELS = {"a", "e", "i", "o", "u",
+           "a\u02D0", "e\u02D0", "i\u02D0", "o\u02D0", "u\u02D0"}  # long variants
+
+# Voiceless stops — primary VOT targets (Spanish short-lag → German long-lag)
+# MFA Spanish uses dental t̪ and palatal c alongside plain p, k
+VOICELESS_STOPS = {"p", "t", "k", "t\u032A", "c"}  # t̪ = dental t
+# Voiced stops — secondary VOT targets (Spanish lead voicing)
+# MFA Spanish uses dental d̪ alongside plain b, ɡ/g, and palatal ɟʝ
+VOICED_STOPS = {"b", "d", "d\u032A", "\u0261", "g", "\u025F\u02DD"}  # d̪, ɡ, ɟʝ
+# Voiced stop approximant allophones (excluded from VOT)
+APPROXIMANTS = {"\u03B2", "\u00F0", "\u0263",       # β ð ɣ
+                "\u0279"}                             # ɹ (if present)
+
+# Corner vowels for Vowel Space Area
+CORNER_VOWELS = {"a", "i", "u"}
+
+# All consonant-like phones (anything not a vowel and not silence)
+_SILENCE_LABELS = {"", "sil", "sp", "spn", "<eps>"}
+
+
+def _is_vowel(phone: str) -> bool:
+    """True if *phone* is a vowel (including long variants)."""
+    return phone.lower().strip() in VOWELS
+
+
+def _is_silence(phone: str) -> bool:
+    return phone.lower().strip() in _SILENCE_LABELS
+
+
+# ---------------------------------------------------------------------------
+# 1.  Corpus preparation  (Whisper transcript → .lab files)
+# ---------------------------------------------------------------------------
+
+def prepare_corpus(
+    transcripts: dict[str, dict],
+    corpus_dir: str | Path,
+    audio_dir: str | Path,
+) -> Path:
+    """Create an MFA-compatible corpus from Whisper transcripts.
+
+    Parameters
+    ----------
+    transcripts : dict
+        Mapping ``{speaker_id: transcript_dict}`` where each
+        ``transcript_dict`` is the output of ``transcribe.transcribe()``.
+    corpus_dir : path
+        Directory to write the corpus into (created if needed).
+    audio_dir : path
+        Directory containing the original WAV files.
+
+    Returns
+    -------
+    Path to the corpus directory.
+    """
+    corpus_dir = Path(corpus_dir)
+    corpus_dir.mkdir(parents=True, exist_ok=True)
+    audio_dir = Path(audio_dir)
+
+    for speaker_id, transcript in transcripts.items():
+        # Get clean text (strip disfluency markers, keep real words)
+        words = []
+        for chunk in transcript["chunks"]:
+            text = chunk["text"].strip()
+            if text and text != "[*]":
+                # Strip brackets from CrisperWhisper tokens like [UH]
+                clean = text.strip("[]")
+                if clean:
+                    words.append(clean)
+        lab_text = " ".join(words)
+
+        # Resolve audio file
+        audio_path = Path(transcript["audio_path"])
+        if not audio_path.is_absolute():
+            audio_path = audio_dir / audio_path.name
+        if not audio_path.exists():
+            # Try matching by speaker ID
+            candidates = list(audio_dir.glob(f"{speaker_id}*.[Ww][Aa][Vv]"))
+            if candidates:
+                audio_path = candidates[0]
+
+        # Write symlink to audio + .lab file
+        dest_wav = corpus_dir / f"{speaker_id}.wav"
+        dest_lab = corpus_dir / f"{speaker_id}.lab"
+
+        if not dest_wav.exists():
+            # Symlink so we don't copy large files
+            dest_wav.symlink_to(audio_path.resolve())
+
+        dest_lab.write_text(lab_text, encoding="utf-8")
+
+    return corpus_dir
+
+
+# ---------------------------------------------------------------------------
+# 2.  MFA alignment
+# ---------------------------------------------------------------------------
+
+def run_mfa_alignment(
+    corpus_dir: str | Path,
+    output_dir: str | Path,
+    dictionary: str = "spanish_mfa",
+    acoustic_model: str = "spanish_mfa",
+    num_jobs: int = 4,
+    clean: bool = True,
+) -> Path:
+    """Run ``mfa align`` on a prepared corpus.
+
+    Returns the output directory containing TextGrid files.
+    Raises RuntimeError if ``mfa`` is not found or alignment fails.
+    """
+    corpus_dir = Path(corpus_dir)
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    mfa_bin = shutil.which("mfa")
+    if mfa_bin is None:
+        raise RuntimeError(
+            "Montreal Forced Aligner (mfa) not found on PATH.\n"
+            "Install via conda:\n"
+            "  conda install -c conda-forge montreal-forced-aligner\n"
+            "  mfa model download acoustic spanish_mfa\n"
+            "  mfa model download dictionary spanish_mfa"
+        )
+
+    cmd = [
+        mfa_bin, "align",
+        str(corpus_dir),
+        dictionary,
+        acoustic_model,
+        str(output_dir),
+        "--output_format", "long_textgrid",
+        "--num_jobs", str(num_jobs),
+        "--single_speaker",
+    ]
+    if clean:
+        cmd.append("--clean")
+
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"MFA alignment failed (exit {result.returncode}):\n"
+            f"STDOUT:\n{result.stdout[-2000:]}\n"
+            f"STDERR:\n{result.stderr[-2000:]}"
+        )
+
+    return output_dir
+
+
+# ---------------------------------------------------------------------------
+# 3.  TextGrid parsing
+# ---------------------------------------------------------------------------
+
+def parse_textgrid(tg_path: str | Path) -> dict:
+    """Parse an MFA TextGrid into word and phone interval lists.
+
+    Returns
+    -------
+    dict with keys ``"words"`` and ``"phones"``, each a list of
+    ``(start, end, label)`` tuples.
+    """
+    tg = tgio.openTextgrid(str(tg_path), includeEmptyIntervals=False)
+
+    phones = []
+    words = []
+
+    for tier_name in tg.tierNames:
+        tier = tg.getTier(tier_name)
+        lower = tier_name.lower()
+        entries = [(float(s), float(e), label)
+                   for s, e, label in tier.entries]
+        if "phone" in lower:
+            phones = entries
+        elif "word" in lower:
+            words = entries
+
+    return {"words": words, "phones": phones}
+
+
+# ---------------------------------------------------------------------------
+# 4a.  VOT extraction
+# ---------------------------------------------------------------------------
+
+def _detect_burst_time(
+    sound: parselmouth.Sound,
+    start: float,
+    end: float,
+) -> float | None:
+    """Detect the burst release within a stop-consonant interval.
+
+    Uses the intensity contour: the burst is the sharpest intensity
+    rise within the stop interval.  Returns the absolute time of the
+    burst, or None if detection fails.
+    """
+    duration = end - start
+    if duration < 0.010:
+        return None
+
+    try:
+        segment = sound.extract_part(start, end,
+                                     parselmouth.WindowShape.RECTANGULAR,
+                                     1.0, False)
+        intensity = segment.to_intensity(minimum_pitch=400, time_step=0.0005)
+    except Exception:
+        return None
+
+    n = intensity.get_number_of_frames()
+    if n < 3:
+        return None
+
+    # Find the frame with the largest intensity rise (derivative)
+    best_rise = -np.inf
+    best_time = None
+    for i in range(2, n + 1):
+        t_prev = intensity.get_time_from_frame_number(i - 1)
+        t_cur = intensity.get_time_from_frame_number(i)
+        val_prev = intensity.get_value(t_prev)
+        val_cur = intensity.get_value(t_cur)
+
+        if np.isnan(val_prev) or np.isnan(val_cur):
+            continue
+
+        rise = val_cur - val_prev
+        if rise > best_rise:
+            best_rise = rise
+            best_time = t_cur
+
+    if best_time is None or best_rise < 1.0:  # minimum 1 dB rise
+        return None
+
+    # Convert back to absolute time
+    return start + best_time
+
+
+def extract_vot(
+    phones: list[tuple[float, float, str]],
+    sound: parselmouth.Sound,
+) -> dict:
+    """Measure Voice Onset Time for voiceless and voiced stops.
+
+    MFA places stop and vowel boundaries contiguously (no gap), so the
+    stop interval itself contains both closure and release/aspiration.
+
+    For voiceless stops /p, t, k/:
+      VOT = stop_end − burst_time  (positive: time from burst to vowel onset).
+    For voiced stops /b, d, g/:
+      VOT = stop_end − burst_time  (may be short if voicing starts early).
+
+    When burst detection fails, VOT is estimated as a fraction of the
+    stop duration (the release portion, typically the final ~40%).
+
+    Returns per-phone-type mean VOT and individual measurements.
+    """
+    measurements: list[dict] = []
+
+    for i, (start, end, label) in enumerate(phones):
+        phone = label.lower().strip()
+
+        # Only measure stops followed by a vowel
+        if phone not in VOICELESS_STOPS and phone not in VOICED_STOPS:
+            continue
+
+        # Find the next non-silence phone
+        next_phone = None
+        for j in range(i + 1, len(phones)):
+            _, _, nlabel = phones[j]
+            if not _is_silence(nlabel):
+                next_phone = phones[j]
+                break
+
+        if next_phone is None or not _is_vowel(next_phone[2]):
+            continue
+
+        vowel_start = next_phone[0]
+        stop_type = "voiceless" if phone in VOICELESS_STOPS else "voiced"
+        stop_dur_ms = (end - start) * 1000
+
+        # Detect burst within the stop interval
+        burst_time = _detect_burst_time(sound, start, end)
+
+        if burst_time is not None:
+            # VOT = time from burst to stop/vowel boundary
+            vot_ms = (end - burst_time) * 1000
+        else:
+            # Fallback: estimate VOT as the final 40% of the stop
+            # (closure is ~60%, release+aspiration is ~40%)
+            vot_ms = stop_dur_ms * 0.4
+            burst_time = start + (end - start) * 0.6
+
+        # Sanity: VOT shouldn't exceed the stop duration
+        vot_ms = min(vot_ms, stop_dur_ms)
+        vot_ms = max(vot_ms, 0.0)
+
+        measurements.append({
+            "phone": phone,
+            "type": stop_type,
+            "position_s": round(start, 3),
+            "stop_dur_ms": round(stop_dur_ms, 2),
+            "vot_ms": round(vot_ms, 2),
+            "burst_time_s": round(burst_time, 4),
+            "vowel_onset_s": round(vowel_start, 4),
+        })
+
+    # Aggregate by phone and type
+    voiceless_vots = [m["vot_ms"] for m in measurements
+                      if m["type"] == "voiceless"]
+    voiced_vots = [m["vot_ms"] for m in measurements
+                   if m["type"] == "voiced"]
+
+    per_phone: dict[str, list[float]] = {}
+    for m in measurements:
+        per_phone.setdefault(m["phone"], []).append(m["vot_ms"])
+
+    phone_means = {p: round(float(np.mean(vs)), 2)
+                   for p, vs in per_phone.items()}
+
+    return {
+        "voiceless_mean_vot_ms": round(float(np.mean(voiceless_vots)), 2)
+            if voiceless_vots else None,
+        "voiceless_sd_vot_ms": round(float(np.std(voiceless_vots, ddof=1)), 2)
+            if len(voiceless_vots) > 1 else None,
+        "voiced_mean_vot_ms": round(float(np.mean(voiced_vots)), 2)
+            if voiced_vots else None,
+        "voiced_sd_vot_ms": round(float(np.std(voiced_vots, ddof=1)), 2)
+            if len(voiced_vots) > 1 else None,
+        "per_phone_mean_ms": phone_means,
+        "n_voiceless": len(voiceless_vots),
+        "n_voiced": len(voiced_vots),
+        "measurements": measurements,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 4b.  Vowel formant extraction + Vowel Space Area
+# ---------------------------------------------------------------------------
+
+def extract_vowel_formants(
+    phones: list[tuple[float, float, str]],
+    sound: parselmouth.Sound,
+    max_formant: float = 5500.0,
+    n_formants: int = 5,
+) -> dict:
+    """Extract F1/F2/F3 at the temporal midpoint of each vowel.
+
+    Parameters
+    ----------
+    max_formant : float
+        Maximum formant frequency for Burg analysis.
+        Use 5500 for female speakers, 5000 for male speakers.
+        Default 5500 (conservative for mixed/unknown gender).
+
+    Returns per-vowel-type mean formants, all individual measurements,
+    and Vowel Space Area computed from corner vowels /a, i, u/.
+    """
+    formant_obj = call(sound, "To Formant (burg)",
+                       0.025, n_formants, max_formant, 0.025, 50.0)
+
+    measurements: list[dict] = []
+
+    for start, end, label in phones:
+        phone = label.lower().strip()
+        if not _is_vowel(phone):
+            continue
+
+        # Strip length marks for grouping
+        vowel_id = phone.replace("\u02D0", "")
+        duration = end - start
+        if duration < 0.02:
+            continue
+
+        midpoint = (start + end) / 2
+
+        f1 = call(formant_obj, "Get value at time", 1, midpoint, "Hertz", "Linear")
+        f2 = call(formant_obj, "Get value at time", 2, midpoint, "Hertz", "Linear")
+        f3 = call(formant_obj, "Get value at time", 3, midpoint, "Hertz", "Linear")
+
+        if np.isnan(f1) or np.isnan(f2):
+            continue
+
+        measurements.append({
+            "vowel": vowel_id,
+            "midpoint_s": round(midpoint, 4),
+            "duration_ms": round(duration * 1000, 1),
+            "f1_hz": round(f1, 1),
+            "f2_hz": round(f2, 1),
+            "f3_hz": round(f3, 1) if not np.isnan(f3) else None,
+        })
+
+    # Per-vowel means
+    vowel_data: dict[str, list[dict]] = {}
+    for m in measurements:
+        vowel_data.setdefault(m["vowel"], []).append(m)
+
+    per_vowel: dict[str, dict] = {}
+    for v, items in vowel_data.items():
+        f1s = [it["f1_hz"] for it in items]
+        f2s = [it["f2_hz"] for it in items]
+        per_vowel[v] = {
+            "n": len(items),
+            "f1_mean_hz": round(float(np.mean(f1s)), 1),
+            "f1_sd_hz": round(float(np.std(f1s, ddof=1)), 1) if len(f1s) > 1 else None,
+            "f2_mean_hz": round(float(np.mean(f2s)), 1),
+            "f2_sd_hz": round(float(np.std(f2s, ddof=1)), 1) if len(f2s) > 1 else None,
+        }
+
+    # Vowel Space Area (triangle: /a/, /i/, /u/)
+    vsa = _compute_vsa(per_vowel)
+
+    # Vowel Formant Dispersion
+    vfd = _compute_vfd(per_vowel)
+
+    return {
+        "per_vowel": per_vowel,
+        "vowel_space_area": vsa,
+        "vowel_formant_dispersion": vfd,
+        "n_total": len(measurements),
+        "measurements": measurements,
+    }
+
+
+def _compute_vsa(per_vowel: dict[str, dict]) -> float | None:
+    """Vowel Space Area — triangle formed by /a/, /i/, /u/ in F1×F2 space.
+
+    Uses the Shoelace formula for the area of a triangle:
+      VSA = 0.5 * |F1a(F2i - F2u) + F1i(F2u - F2a) + F1u(F2a - F2i)|
+    """
+    corners = {}
+    for v in CORNER_VOWELS:
+        if v in per_vowel:
+            corners[v] = (per_vowel[v]["f1_mean_hz"],
+                          per_vowel[v]["f2_mean_hz"])
+
+    if len(corners) < 3:
+        return None
+
+    a = corners["a"]
+    i = corners["i"]
+    u = corners["u"]
+
+    area = 0.5 * abs(
+        a[0] * (i[1] - u[1]) +
+        i[0] * (u[1] - a[1]) +
+        u[0] * (a[1] - i[1])
+    )
+    return round(area, 1)
+
+
+def _compute_vfd(per_vowel: dict[str, dict]) -> float | None:
+    """Vowel Formant Dispersion — mean Euclidean distance from centroid."""
+    if not per_vowel:
+        return None
+
+    f1_all = [v["f1_mean_hz"] for v in per_vowel.values()]
+    f2_all = [v["f2_mean_hz"] for v in per_vowel.values()]
+
+    centroid_f1 = np.mean(f1_all)
+    centroid_f2 = np.mean(f2_all)
+
+    distances = []
+    for v in per_vowel.values():
+        d = math.sqrt((v["f1_mean_hz"] - centroid_f1) ** 2 +
+                      (v["f2_mean_hz"] - centroid_f2) ** 2)
+        distances.append(d)
+
+    return round(float(np.mean(distances)), 1)
+
+
+# ---------------------------------------------------------------------------
+# 4c.  Rhythm metrics
+# ---------------------------------------------------------------------------
+
+def extract_rhythm_metrics(
+    phones: list[tuple[float, float, str]],
+) -> dict:
+    """Compute rhythm metrics from phone-level intervals.
+
+    Returns %V, deltaC, deltaV, VarcoC, VarcoV, rPVI-C, nPVI-V.
+    """
+    # Step 1: classify each phone as C or V, skip silence
+    cv_intervals: list[tuple[float, float, str]] = []
+    for start, end, label in phones:
+        if _is_silence(label):
+            continue
+        category = "V" if _is_vowel(label) else "C"
+        cv_intervals.append((start, end, category))
+
+    if not cv_intervals:
+        return _empty_rhythm()
+
+    # Step 2: merge adjacent same-type intervals
+    merged: list[tuple[float, float, str]] = [cv_intervals[0]]
+    for start, end, cat in cv_intervals[1:]:
+        prev_start, prev_end, prev_cat = merged[-1]
+        if cat == prev_cat and abs(start - prev_end) < 0.001:
+            # Merge
+            merged[-1] = (prev_start, end, cat)
+        else:
+            merged.append((start, end, cat))
+
+    # Step 3: compute durations
+    c_durations = [(e - s) * 1000 for s, e, cat in merged if cat == "C"]
+    v_durations = [(e - s) * 1000 for s, e, cat in merged if cat == "V"]
+
+    if len(c_durations) < 2 or len(v_durations) < 2:
+        return _empty_rhythm()
+
+    c_arr = np.array(c_durations)
+    v_arr = np.array(v_durations)
+    total_dur = sum(c_durations) + sum(v_durations)
+
+    # %V  — proportion of vocalic intervals
+    pct_v = (sum(v_durations) / total_dur) * 100 if total_dur > 0 else 0
+
+    # deltaC, deltaV  — standard deviations
+    delta_c = float(np.std(c_arr, ddof=1))
+    delta_v = float(np.std(v_arr, ddof=1))
+
+    # VarcoC, VarcoV  — variation coefficients (rate-normalized)
+    mean_c = float(np.mean(c_arr))
+    mean_v = float(np.mean(v_arr))
+    varco_c = (delta_c / mean_c) * 100 if mean_c > 0 else 0
+    varco_v = (delta_v / mean_v) * 100 if mean_v > 0 else 0
+
+    # rPVI-C  — raw Pairwise Variability Index for consonants
+    rpvi_c = float(np.mean(np.abs(np.diff(c_arr))))
+
+    # nPVI-V  — normalized PVI for vowels
+    npvi_v = _npvi(v_arr)
+
+    return {
+        "pct_v": round(pct_v, 2),
+        "delta_c_ms": round(delta_c, 2),
+        "delta_v_ms": round(delta_v, 2),
+        "varco_c": round(varco_c, 2),
+        "varco_v": round(varco_v, 2),
+        "rpvi_c": round(rpvi_c, 2),
+        "npvi_v": round(npvi_v, 2),
+        "n_c_intervals": len(c_durations),
+        "n_v_intervals": len(v_durations),
+        "mean_c_ms": round(mean_c, 2),
+        "mean_v_ms": round(mean_v, 2),
+    }
+
+
+def _npvi(durations: np.ndarray) -> float:
+    """Normalized Pairwise Variability Index.
+
+    nPVI = 100 * (1/(n-1)) * Σ |d_k - d_{k+1}| / ((d_k + d_{k+1}) / 2)
+    """
+    n = len(durations)
+    if n < 2:
+        return 0.0
+    total = 0.0
+    for k in range(n - 1):
+        avg = (durations[k] + durations[k + 1]) / 2
+        if avg > 0:
+            total += abs(durations[k] - durations[k + 1]) / avg
+    return 100.0 * total / (n - 1)
+
+
+def _empty_rhythm() -> dict:
+    return {
+        "pct_v": None, "delta_c_ms": None, "delta_v_ms": None,
+        "varco_c": None, "varco_v": None,
+        "rpvi_c": None, "npvi_v": None,
+        "n_c_intervals": 0, "n_v_intervals": 0,
+        "mean_c_ms": None, "mean_v_ms": None,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 5.  Public entry point
+# ---------------------------------------------------------------------------
+
+def extract_alignment_markers(
+    audio_path: str | Path,
+    textgrid_path: str | Path,
+    max_formant: float = 5500.0,
+) -> dict:
+    """Extract all Phase-2 alignment-based markers.
+
+    Parameters
+    ----------
+    audio_path : path
+        Path to the WAV file.
+    textgrid_path : path
+        Path to the MFA-produced TextGrid.
+    max_formant : float
+        Maximum formant frequency for Burg analysis (5500 for female,
+        5000 for male, default 5500).
+
+    Returns
+    -------
+    dict with keys ``"vot"``, ``"vowel_formants"``, ``"rhythm"``.
+    """
+    sound = parselmouth.Sound(str(audio_path))
+    tg_data = parse_textgrid(textgrid_path)
+    phones = tg_data["phones"]
+
+    if not phones:
+        return {"vot": {}, "vowel_formants": {}, "rhythm": _empty_rhythm()}
+
+    vot = extract_vot(phones, sound)
+    formants = extract_vowel_formants(phones, sound, max_formant=max_formant)
+    rhythm = extract_rhythm_metrics(phones)
+
+    return {
+        "vot": vot,
+        "vowel_formants": formants,
+        "rhythm": rhythm,
+    }

app.py

@@ -0,0 +1,221 @@
+"""Language Attrition: derive linguistic factors, then model them.
+
+Two tabs, both point-and-click (no Spanish, no Praat, no code needed):
+  1. Derive   — upload a recording, get its ~25 linguistic factors, stack them.
+  2. Model    — pick two variables, see the scatter, correlation and regression.
+
+The numbers are identical to the course pipeline (same code under the hood).
+Phase-2 markers (VOT, vowel space, rhythm) need forced alignment and are not
+produced here.
+"""
+import os
+import tempfile
+
+import gradio as gr
+import librosa
+import numpy as np
+import pandas as pd
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from scipy import stats
+
+from features import derive_features_with_text, FEATURE_COLUMNS
+
+MAX_AUDIO_SECONDS = 600
+PRIMARY, ACCENT = "#004782", "#d1495b"
+ALL_COLS = ["Speaker"] + FEATURE_COLUMNS
+
+
+# ----------------------------------------------------------------------------
+# Tab 1: Derive
+# ----------------------------------------------------------------------------
+def _to_df(rows):
+    if not rows:
+        return pd.DataFrame(columns=ALL_COLS)
+    return pd.DataFrame(rows)[ALL_COLS]
+
+
+def _save_csv(df, prefix="features"):
+    f = tempfile.NamedTemporaryFile(mode="w", suffix=".csv", prefix=f"{prefix}_", delete=False)
+    df.to_csv(f.name, index=False)
+    f.close()
+    return f.name
+
+
+def add_recording(audio_path, transcript_path, label, rows):
+    rows = rows or []
+    if audio_path is None:
+        return rows, _to_df(rows), None, "", "Please upload an audio file first."
+    if transcript_path is None:
+        return rows, _to_df(rows), None, "", "Please upload the transcript (.json) for this speaker."
+    dur = librosa.get_duration(path=audio_path)
+    if dur > MAX_AUDIO_SECONDS:
+        return rows, _to_df(rows), None, "", f"Audio too long ({dur:.0f}s). Max is {MAX_AUDIO_SECONDS}s."
+    try:
+        row, text = derive_features_with_text(audio_path, transcript_path, (label or "").strip() or None)
+    except Exception as e:  # noqa: BLE001
+        return rows, _to_df(rows), None, "", f"Error while processing: {e}"
+    rows = [r for r in rows if r["Speaker"] != row["Speaker"]] + [row]
+    df = _to_df(rows)
+    return rows, df, _save_csv(df), text, (
+        f"Added **{row['Speaker']}**. Table now has {len(rows)} recording(s). "
+        "Switch to the *Model* tab when you have a few."
+    )
+
+
+def clear_table():
+    return [], _to_df([]), None, "", "Table cleared."
+
+
+# ----------------------------------------------------------------------------
+# Tab 2: Model
+# ----------------------------------------------------------------------------
+def load_for_modeling(rows, uploaded, source):
+    if source.startswith("Upload") and uploaded is not None:
+        try:
+            df = pd.read_csv(uploaded)
+        except Exception as e:  # noqa: BLE001
+            return None, gr.update(choices=[]), gr.update(choices=[]), f"Could not read CSV: {e}"
+    else:
+        df = _to_df(rows or [])
+    num = [c for c in df.columns if pd.api.types.is_numeric_dtype(df[c])]
+    if len(num) < 2:
+        return df, gr.update(choices=num), gr.update(choices=num), (
+            "Need at least two numeric columns. Derive a few recordings first, "
+            "or upload a CSV that includes your predictor columns."
+        )
+    return (df,
+            gr.update(choices=num, value=num[0]),
+            gr.update(choices=num, value=num[1]),
+            f"Loaded {len(df)} rows and {len(num)} numeric variables. Pick two to compare.")
+
+
+def _interpret(r, p, n):
+    strength = "weak" if abs(r) < 0.3 else "moderate" if abs(r) < 0.6 else "strong"
+    direction = "positive" if r > 0 else "negative"
+    sig = ("**statistically significant** (p < 0.05)" if p < 0.05
+           else "**not significant** (p ≥ 0.05) — could be chance, especially with few speakers")
+    return (f"_Reading: a {strength} {direction} relationship, {sig}._\n\n"
+            "With a small number of speakers this is a **hypothesis, not a finding**.")
+
+
+def model_pair(df, x, y, method):
+    if df is None or not len(df) or x is None or y is None:
+        return None, "Load a table and pick two variables."
+    if x == y:
+        return None, "Pick two *different* variables."
+    sub = df[[x, y]].apply(pd.to_numeric, errors="coerce").dropna()
+    n = len(sub)
+    if n < 3:
+        return None, "Need at least 3 speakers with both values present."
+    pear = stats.pearsonr(sub[x], sub[y])
+    spear = stats.spearmanr(sub[x], sub[y])
+    b, a = np.polyfit(sub[x], sub[y], 1)
+    use_pear = method.startswith("Pearson")
+    r, p = (pear if use_pear else spear)
+
+    fig, ax = plt.subplots(figsize=(6.2, 4.6))
+    ax.scatter(sub[x], sub[y], s=85, color=PRIMARY, edgecolor="white", zorder=3)
+    xs = np.array([sub[x].min(), sub[x].max()])
+    ax.plot(xs, a + b * xs, color=ACCENT, lw=2)
+    ax.set_xlabel(x); ax.set_ylabel(y); ax.grid(alpha=0.3)
+    ax.set_title(f"{method.split()[0]} = {r:+.2f}   (p = {p:.3f}, n = {n})", color=PRIMARY)
+    fig.tight_layout()
+
+    md = (f"### {x}  vs  {y}\n\n"
+          f"- **{method.split()[0]} correlation** = {r:+.3f}  ·  p = {p:.3f}  ·  n = {n}\n"
+          f"- **Regression line**: `{y} = {a:.2f} + {b:.3f} × {x}`\n"
+          f"- Pearson r = {pear[0]:+.3f} (p={pear[1]:.3f}) · Spearman ρ = {spear[0]:+.3f} (p={spear[1]:.3f})\n\n"
+          + _interpret(r, p, n))
+    return fig, md
+
+
+def corr_heatmap(df, method):
+    if df is None or not len(df):
+        return None, "Load a table first."
+    num = df.select_dtypes("number")
+    if num.shape[1] < 2:
+        return None, "Need at least two numeric columns."
+    C = num.corr(method="spearman" if method.startswith("Spearman") else "pearson")
+    sz = min(1.2 + 0.5 * len(C), 13)
+    fig, ax = plt.subplots(figsize=(sz, sz))
+    im = ax.imshow(C, vmin=-1, vmax=1, cmap="RdBu_r")
+    ax.set_xticks(range(len(C))); ax.set_xticklabels(C.columns, rotation=90, fontsize=7)
+    ax.set_yticks(range(len(C))); ax.set_yticklabels(C.columns, fontsize=7)
+    ax.set_title(f"{method.split()[0]} correlations across all variables", color=PRIMARY)
+    fig.colorbar(im, shrink=0.7, label="r")
+    fig.tight_layout()
+    return fig, f"Heatmap of {num.shape[1]} variables. Blue = move together, red = move apart."
+
+
+# ----------------------------------------------------------------------------
+# UI
+# ----------------------------------------------------------------------------
+with gr.Blocks(title="Language Attrition: derive & model") as demo:
+    gr.Markdown(
+        "# Language Attrition: derive the numbers, then model them\n"
+        "Upload a recording **and its transcript** and the app derives the linguistic "
+        "factors (disfluency, fluency, complexity, pitch and voice quality). Then compare "
+        "any two of them. No transcribing, no Spanish, no Praat, no code."
+    )
+    table_state = gr.State([])     # derived rows
+    model_df_state = gr.State()    # dataframe loaded into the Model tab
+
+    with gr.Tab("1 · Derive features"):
+        with gr.Row():
+            with gr.Column():
+                audio = gr.Audio(type="filepath", label="Recording (≤ 10 min)")
+                transcript_in = gr.File(label="Transcript (.json, word-timestamped)",
+                                        file_types=[".json"])
+                label = gr.Textbox(label="Speaker label", placeholder="e.g. A014 (optional)")
+                with gr.Row():
+                    add_btn = gr.Button("Derive features → add to table", variant="primary")
+                    clear_btn = gr.Button("Clear table")
+                status = gr.Markdown()
+            with gr.Column():
+                transcript_box = gr.Textbox(label="Transcript (from your upload)", lines=6)
+        table = gr.Dataframe(label="Your feature table", interactive=False, wrap=True)
+        csv_out = gr.File(label="Download feature table (.csv)")
+        add_btn.click(add_recording, [audio, transcript_in, label, table_state],
+                      [table_state, table, csv_out, transcript_box, status])
+        clear_btn.click(clear_table, None,
+                        [table_state, table, csv_out, transcript_box, status])
+
+    with gr.Tab("2 · Model"):
+        gr.Markdown(
+            "Model the table you built in tab 1, **or** upload a CSV "
+            "(e.g. the features joined with your questionnaire predictors)."
+        )
+        with gr.Row():
+            source = gr.Radio(["Use table from tab 1", "Upload a CSV"],
+                              value="Use table from tab 1", label="Data source")
+            uploaded = gr.File(label="CSV (if uploading)", file_types=[".csv"])
+        load_btn = gr.Button("Load data", variant="primary")
+        load_status = gr.Markdown()
+        with gr.Row():
+            x_var = gr.Dropdown(label="X variable", choices=[])
+            y_var = gr.Dropdown(label="Y variable", choices=[])
+            method = gr.Radio(["Pearson (straight-line)", "Spearman (rank)"],
+                              value="Spearman (rank)", label="Correlation type")
+        with gr.Row():
+            plot_btn = gr.Button("Plot & correlate", variant="primary")
+            heat_btn = gr.Button("Correlation heatmap (all variables)")
+        with gr.Row():
+            plot_out = gr.Plot(label="Scatter + regression line")
+            result_md = gr.Markdown()
+        heat_out = gr.Plot(label="Correlation heatmap")
+
+        load_btn.click(load_for_modeling, [table_state, uploaded, source],
+                       [model_df_state, x_var, y_var, load_status])
+        plot_btn.click(model_pair, [model_df_state, x_var, y_var, method],
+                       [plot_out, result_md])
+        heat_btn.click(corr_heatmap, [model_df_state, method], [heat_out, load_status])
+
+    gr.Markdown(
+        "---\n*Phase-2 markers (VOT, vowel space, rhythm) need forced alignment and "
+        "are not produced here. Numbers match the course pipeline exactly.*"
+    )
+
+if __name__ == "__main__":
+    demo.queue(max_size=60, default_concurrency_limit=2).launch(share=True)

features.py

@@ -0,0 +1,119 @@
+"""Derive the Phase-1 linguistic factors from an audio file + its transcript.
+
+No transcription happens here: the student uploads the existing word-timestamped
+transcript (JSON), and we run markers.extract_markers (disfluency, fluency,
+complexity + Phase-1 acoustic). No MFA / forced alignment, so Phase-2 markers
+(VOT, vowel space, rhythm) are not produced.
+
+The output is one flat dict per recording, ready to stack into a table for
+modeling. Column names are kept short and spreadsheet-friendly.
+"""
+from __future__ import annotations
+
+import json
+import os
+
+import librosa
+
+from markers import extract_markers
+
+# (column label, dotted path into extract_markers() output, decimals)
+FLATTEN = [
+    ("Words", "word_count_clean", 0),
+    ("Duration_s", "duration_s", 1),
+    # disfluency (per 100 words)
+    ("FP_per_100w", "filled_pauses.per_100_words", 2),
+    ("EP_per_100w", "empty_pauses.per_100_words", 2),
+    ("RP_per_100w", "repetitions.per_100_words", 2),
+    ("RT_per_100w", "retractions.per_100_words", 2),
+    ("PauseMean_ms", "temporal.pause_mean_ms", 1),
+    # fluency
+    ("SpeechRate_spm", "temporal.speech_rate_spm", 2),
+    ("ArticRate_spm", "temporal.articulation_rate_spm", 2),
+    ("Phonation_pct", "temporal.phonation_time_ratio_pct", 2),
+    # complexity
+    ("MLU", "temporal.mlu_words", 2),
+    ("TTR", "lexical_diversity.ttr", 4),
+    ("MTLD", "lexical_diversity.mtld", 2),
+    ("CodeSwitch", "code_switching.count", 0),
+    # acoustic: pitch
+    ("F0_Mean", "acoustic.f0.f0_mean_hz", 2),
+    ("F0_SD", "acoustic.f0.f0_sd_hz", 2),
+    ("F0_Range", "acoustic.f0.f0_range_hz", 2),
+    ("F0_CV", "acoustic.f0.f0_cv", 4),
+    ("F0_Slope", "acoustic.f0.f0_slope_hz_per_s", 4),
+    # acoustic: voice quality
+    ("Jitter_pct", "acoustic.voice_quality.jitter_local_pct", 4),
+    ("Shimmer_pct", "acoustic.voice_quality.shimmer_local_pct", 4),
+    ("HNR_dB", "acoustic.voice_quality.hnr_mean_db", 2),
+    ("H1H2_dB", "acoustic.spectral_tilt.h1_h2_mean_db", 2),
+    # acoustic: spectral shape
+    ("MFCC1", "acoustic.mfcc.mfcc_1_mean", 2),
+    ("MFCC2", "acoustic.mfcc.mfcc_2_mean", 2),
+    ("MFCC5", "acoustic.mfcc.mfcc_5_mean", 2),
+]
+
+FEATURE_COLUMNS = [c for c, _, _ in FLATTEN]
+
+
+def _dig(d: dict, dotted: str):
+    cur = d
+    for part in dotted.split("."):
+        if not isinstance(cur, dict):
+            return None
+        cur = cur.get(part)
+    return cur
+
+
+def flatten_markers(markers: dict, label: str) -> dict:
+    """Turn the nested extract_markers() output into one flat row."""
+    row = {"Speaker": label}
+    for col, path, nd in FLATTEN:
+        v = _dig(markers, path)
+        if isinstance(v, (int, float)):
+            v = round(v, nd) if nd else int(round(v))
+        row[col] = v
+    return row
+
+
+def load_chunks(transcript_path: str) -> list[dict]:
+    """Read an uploaded transcript JSON into the chunk format extract_markers wants.
+
+    Accepts either ``{"chunks": [...]}`` or a bare list. Each chunk needs a
+    ``text`` and a ``timestamp`` with ``start`` / ``end`` (seconds). The ``[*]``
+    disfluency markers must be kept: filled-pause and pause markers depend on them.
+    """
+    with open(transcript_path, encoding="utf-8") as f:
+        data = json.load(f)
+    raw = data.get("chunks", data) if isinstance(data, dict) else data
+    if not isinstance(raw, list):
+        raise ValueError("Transcript JSON must be a list of chunks or have a 'chunks' key.")
+    chunks = []
+    for c in raw:
+        ts = c.get("timestamp") or {}
+        chunks.append({
+            "text": c["text"],
+            "timestamp": {"start": ts.get("start"), "end": ts.get("end")},
+            "confidence": c.get("confidence"),
+        })
+    return chunks
+
+
+def derive_features_with_text(audio_path: str, transcript_path: str, label: str | None = None):
+    """Derive features from (audio, transcript); return (flat row, transcript text)."""
+    if not label:
+        label = os.path.splitext(os.path.basename(audio_path))[0]
+    chunks = load_chunks(transcript_path)
+    duration_s = round(librosa.get_duration(path=audio_path), 3)
+    transcript = {"chunks": chunks, "duration_s": duration_s, "audio_path": audio_path}
+    markers = extract_markers(transcript)
+    full_text = " ".join(
+        c["text"].strip() for c in chunks if c["text"].strip() and c["text"] != "[*]"
+    )
+    return flatten_markers(markers, label), full_text
+
+
+def derive_features(audio_path: str, transcript_path: str, label: str | None = None) -> dict:
+    """Derive features from (audio, transcript) and return the flat feature row."""
+    row, _text = derive_features_with_text(audio_path, transcript_path, label)
+    return row

markers.py

@@ -0,0 +1,515 @@
+"""Extract language attrition markers from a whisper-timestamped transcript.
+
+Covers the original 13 Schmid-style + temporal + lexical markers, plus
+Phase-1 acoustic markers (F0, voice quality, spectral tilt, MFCCs).
+"""
+
+from __future__ import annotations
+
+import re
+import statistics
+from collections import Counter
+
+import pyphen
+from lexical_diversity import lex_div
+
+from acoustic_markers import extract_acoustic_markers
+from alignment_markers import extract_alignment_markers
+
+# ---------------------------------------------------------------------------
+# Word lists
+# ---------------------------------------------------------------------------
+
+SPANISH_FILLERS = {
+    "eh", "ah", "um", "uh", "este", "em", "mmm", "pues", "bueno",
+    "mm", "hm", "ehm", "uhm",
+}
+
+# Bracket tokens for filled pauses: CrisperWhisper [UH]/[UM] or
+# whisper-timestamped [*] disfluency markers
+_BRACKET_FP = re.compile(r"^\[U[HM]\]$", re.IGNORECASE)
+_DISFLUENCY_MARKER = re.compile(r"^\[\*\]$")
+
+SPANISH_ARTICLES = {"el", "la", "los", "las", "un", "una", "unos", "unas"}
+SPANISH_PREPOSITIONS = {
+    "de", "en", "a", "con", "por", "para", "sin", "sobre",
+    "entre", "hacia", "hasta", "desde", "según", "durante",
+}
+SPANISH_PRONOUNS = {
+    "yo", "tú", "él", "ella", "nosotros", "nosotras",
+    "ellos", "ellas", "usted", "ustedes",
+    "me", "te", "se", "nos", "le", "les", "lo", "la",
+    "mí", "ti", "sí", "conmigo", "contigo", "consigo",
+    "que", "quien", "cual", "donde", "como",
+    "este", "ese", "aquel", "esto", "eso", "aquello",
+}
+
+FUNCTION_WORD_SETS: dict[str, set[str]] = {
+    "article": SPANISH_ARTICLES,
+    "preposition": SPANISH_PREPOSITIONS,
+    "pronoun": SPANISH_PRONOUNS,
+}
+
+# Common Spanish verbs (high-frequency) for word-class tagging
+SPANISH_VERBS = {
+    "es", "era", "fue", "ser", "estar", "está", "estaba", "estuvo",
+    "tiene", "tenía", "tuvo", "tener", "hacer", "hace", "hizo",
+    "ir", "va", "iba", "fue", "viene", "venir", "dar", "dio",
+    "decir", "dice", "dijo", "saber", "sabe", "sabía",
+    "poder", "puede", "podía", "pudo", "querer", "quiere", "quería",
+    "ver", "ve", "vio", "veía", "poner", "pone", "puso",
+    "salir", "sale", "salió", "llegar", "llega", "llegó",
+    "pasar", "pasa", "pasó", "quedar", "queda", "quedó",
+    "creer", "cree", "pensaba", "pensar", "piensa",
+    "hay", "había", "haber", "han", "ha",
+    "entrar", "entra", "entró", "caer", "cae", "cayó",
+    "llevar", "lleva", "llevó", "seguir", "sigue", "siguió",
+    "encontrar", "encuentra", "encontró",
+    "empezar", "empieza", "empezó", "intentar", "intenta", "intentó",
+    "sentir", "siente", "sintió",
+}
+
+# German words unlikely to appear in Spanish — for code-switching detection
+GERMAN_WORDS = {
+    "und", "aber", "auch", "schon", "jetzt", "dann", "nicht", "oder",
+    "weil", "dass", "noch", "hier", "dort", "halt", "genau",
+    "eigentlich", "vielleicht", "natürlich", "wirklich", "immer",
+    "wieder", "heute", "morgen", "gestern", "gerade", "trotzdem",
+    "deswegen", "deshalb", "allerdings", "übrigens", "sozusagen",
+    "naja", "eben", "doch", "mal", "nur", "sehr", "ganz", "etwas",
+    "alles", "nichts", "niemand", "jemand", "etwas", "irgendwie",
+    "auf", "aus", "bei", "mit", "nach", "seit", "von", "zu",
+    "über", "unter", "vor", "hinter", "neben", "zwischen",
+    "ich", "du", "wir", "ihr", "sie", "mein", "dein", "sein",
+    "kein", "diese", "jede", "welche", "solche",
+    "können", "müssen", "sollen", "wollen", "dürfen", "mögen",
+    "machen", "gehen", "kommen", "sagen", "wissen", "sehen",
+    "geben", "nehmen", "finden", "denken", "stehen", "lassen",
+    "sprechen", "halten", "bringen", "leben", "fahren", "arbeiten",
+    "spielen", "laufen", "schreiben", "lesen", "essen", "trinken",
+    "schlafen", "kaufen", "verkaufen", "helfen", "lernen",
+    "arbeit", "schule", "kindergarten", "ausbildung", "beruf",
+    "wohnung", "straße", "stadt", "kirche",
+    "ja", "nein", "bitte", "danke", "stimmt", "klar", "richtig",
+}
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_pyphen_dic = pyphen.Pyphen(lang="es_ES")
+
+
+def _clean_word(w: str) -> str:
+    """Lowercase and strip punctuation for comparison."""
+    return re.sub(r"[^\w]", "", w.lower())
+
+
+def _is_disfluency_marker(word: str) -> bool:
+    """Check if word is a whisper-timestamped [*] disfluency marker."""
+    return bool(_DISFLUENCY_MARKER.match(word.strip()))
+
+
+def _is_filler(word: str) -> bool:
+    """Check if word is a filled pause (bracket token, [*] marker, or Spanish filler)."""
+    w = word.strip()
+    if _BRACKET_FP.match(w):
+        return True
+    if _is_disfluency_marker(w):
+        return True
+    return _clean_word(w) in SPANISH_FILLERS
+
+
+def _clean_tokens(chunks) -> list[str]:
+    """Return lowered, punctuation-stripped tokens excluding fillers and [*] markers."""
+    out = []
+    for c in chunks:
+        if _is_disfluency_marker(c["text"]):
+            continue
+        w = _clean_word(c["text"])
+        if w and not _is_filler(c["text"]):
+            out.append(w)
+    return out
+
+
+def _syllable_count(word: str) -> int:
+    """Count syllables using pyphen Spanish dictionary."""
+    parts = _pyphen_dic.inserted(word).split("-")
+    return max(len(parts), 1)
+
+
+def _word_class(word: str) -> str:
+    """Simple rule-based word-class tagger for Spanish."""
+    w = _clean_word(word)
+    if not w:
+        return "other"
+    if w in SPANISH_ARTICLES:
+        return "article"
+    if w in SPANISH_PREPOSITIONS:
+        return "preposition"
+    if w in SPANISH_PRONOUNS:
+        return "pronoun"
+    if w in SPANISH_VERBS:
+        return "verb"
+    # heuristic: treat remaining content words as nouns (open class)
+    return "noun"
+
+
+def _function_word_category(word: str) -> str | None:
+    """Return function-word category or None if content word."""
+    w = _clean_word(word)
+    for cat, wordset in FUNCTION_WORD_SETS.items():
+        if w in wordset:
+            return cat
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Marker extractors
+# ---------------------------------------------------------------------------
+
+def _filled_pauses(chunks) -> list[dict]:
+    """SDM-1: Filled pauses (Spanish fillers + [*] disfluency markers)."""
+    fps = []
+    for i, c in enumerate(chunks):
+        if _is_disfluency_marker(c["text"]):
+            fps.append({
+                "index": i,
+                "text": "[*]",
+                "source": "whisper-disfluency",
+                **c["timestamp"],
+            })
+        elif _is_filler(c["text"]):
+            fps.append({
+                "index": i,
+                "text": c["text"].strip(),
+                "source": "filler-word",
+                **c["timestamp"],
+            })
+    return fps
+
+
+def _empty_pauses(chunks, threshold_ms: float = 300) -> list[dict]:
+    """CDM-2: Empty pauses (inter-word gaps >= threshold).
+
+    Gaps between real words are measured by looking through [*] markers —
+    the gap from the last real word's end to the next real word's start
+    captures the full silence including any [*] span.
+    """
+    eps = []
+    # Collect indices of real (non-[*]) words
+    real_indices = [
+        i for i, c in enumerate(chunks) if not _is_disfluency_marker(c["text"])
+    ]
+    for j in range(1, len(real_indices)):
+        prev_i = real_indices[j - 1]
+        cur_i = real_indices[j]
+        prev_end = chunks[prev_i]["timestamp"]["end"]
+        cur_start = chunks[cur_i]["timestamp"]["start"]
+        gap_ms = (cur_start - prev_end) * 1000
+        if gap_ms >= threshold_ms:
+            eps.append({
+                "after_index": prev_i,
+                "gap_ms": round(gap_ms, 1),
+                "start": prev_end,
+                "end": cur_start,
+            })
+    return eps
+
+
+def _empty_pauses_real(chunks, threshold_ms: float = 300) -> list[dict]:
+    """Like _empty_pauses but for temporal calculations (same logic)."""
+    return _empty_pauses(chunks, threshold_ms)
+
+
+def _repetitions(chunks) -> list[dict]:
+    """CDM-3: Consecutive identical words (1–3 word spans)."""
+    words = [_clean_word(c["text"]) for c in chunks]
+    reps = []
+    i = 0
+    while i < len(words):
+        if not words[i] or _is_filler(chunks[i]["text"]):
+            i += 1
+            continue
+        # check spans of length 1, 2, 3
+        found = False
+        for span in (3, 2, 1):
+            if i + 2 * span > len(words):
+                continue
+            pattern = words[i:i + span]
+            if all(pattern):
+                candidate = words[i + span:i + 2 * span]
+                if pattern == candidate:
+                    reps.append({
+                        "index": i,
+                        "span": span,
+                        "words": " ".join(pattern),
+                    })
+                    i += 2 * span
+                    found = True
+                    break
+        if not found:
+            i += 1
+    return reps
+
+
+def _retractions(chunks) -> list[dict]:
+    """CDM-4: Consecutive same-category function words (heuristic)."""
+    rts = []
+    for i in range(1, len(chunks)):
+        if _is_filler(chunks[i]["text"]) or _is_filler(chunks[i - 1]["text"]):
+            continue
+        cat_prev = _function_word_category(chunks[i - 1]["text"])
+        cat_cur = _function_word_category(chunks[i]["text"])
+        if cat_prev and cat_cur and cat_prev == cat_cur:
+            w_prev = _clean_word(chunks[i - 1]["text"])
+            w_cur = _clean_word(chunks[i]["text"])
+            if w_prev != w_cur:  # same word = repetition, not retraction
+                rts.append({
+                    "index": i - 1,
+                    "word1": w_prev,
+                    "word2": w_cur,
+                    "category": cat_prev,
+                    "confidence": "medium",
+                })
+    return rts
+
+
+def _temporal_markers(chunks, duration_s: float, clean_word_count: int):
+    """Markers 5–9: speech rate, articulation rate, phonation ratio, pause stats, MLU."""
+    # speaking segments (from first word start to last word end)
+    if not chunks:
+        return {}
+
+    total_speaking_time = 0.0
+    for c in chunks:
+        # Exclude [*] disfluency markers from speaking time — they span
+        # silence/hesitation gaps, not actual articulation
+        if _is_disfluency_marker(c["text"]):
+            continue
+        ts = c["timestamp"]
+        total_speaking_time += ts["end"] - ts["start"]
+
+    # empty pauses for pause stats — use gaps between real words,
+    # skipping over [*] markers to find true inter-word silences
+    eps = _empty_pauses_real(chunks)
+    pause_durations = [ep["gap_ms"] for ep in eps]
+
+    # utterance segmentation: split at pauses >= 1000ms between real words
+    utterances: list[list[str]] = []
+    current_utt: list[str] = []
+    prev_real_end: float | None = None
+    for i, c in enumerate(chunks):
+        if _is_disfluency_marker(c["text"]) or _is_filler(c["text"]):
+            continue
+        w = _clean_word(c["text"])
+        if not w:
+            continue
+        # check if there's a long pause before this word (from last real word)
+        if prev_real_end is not None:
+            gap_ms = (c["timestamp"]["start"] - prev_real_end) * 1000
+            if gap_ms >= 1000 and current_utt:
+                utterances.append(current_utt)
+                current_utt = []
+        current_utt.append(w)
+        prev_real_end = c["timestamp"]["end"]
+    if current_utt:
+        utterances.append(current_utt)
+
+    # syllable count for syllable-based rates
+    clean_words = _clean_tokens(chunks)
+    total_syllables = sum(_syllable_count(w) for w in clean_words)
+
+    speech_rate_wpm = (clean_word_count / duration_s) * 60 if duration_s > 0 else 0
+    speech_rate_spm = (total_syllables / duration_s) * 60 if duration_s > 0 else 0
+    art_rate_wpm = (
+        (clean_word_count / total_speaking_time) * 60
+        if total_speaking_time > 0 else 0
+    )
+    art_rate_spm = (
+        (total_syllables / total_speaking_time) * 60
+        if total_speaking_time > 0 else 0
+    )
+    phonation_ratio = (total_speaking_time / duration_s) * 100 if duration_s > 0 else 0
+
+    utt_lengths = [len(u) for u in utterances]
+    mlu = statistics.mean(utt_lengths) if utt_lengths else 0
+
+    return {
+        "speech_rate_wpm": round(speech_rate_wpm, 2),
+        "speech_rate_spm": round(speech_rate_spm, 2),
+        "articulation_rate_wpm": round(art_rate_wpm, 2),
+        "articulation_rate_spm": round(art_rate_spm, 2),
+        "phonation_time_ratio_pct": round(phonation_ratio, 2),
+        "pause_mean_ms": round(statistics.mean(pause_durations), 1) if pause_durations else None,
+        "pause_median_ms": round(statistics.median(pause_durations), 1) if pause_durations else None,
+        "pause_std_ms": round(statistics.stdev(pause_durations), 1) if len(pause_durations) > 1 else None,
+        "pause_count": len(pause_durations),
+        "mlu_words": round(mlu, 2),
+        "utterance_count": len(utterances),
+        "total_syllables": total_syllables,
+    }
+
+
+def _lexical_diversity(chunks) -> dict:
+    """Markers 10–11: TTR and MTLD."""
+    tokens = _clean_tokens(chunks)
+    if not tokens:
+        return {"ttr": None, "mtld": None}
+    types = set(tokens)
+    ttr = len(types) / len(tokens)
+    try:
+        mtld = lex_div.mtld(tokens)
+    except Exception:
+        mtld = None
+    return {"ttr": round(ttr, 4), "mtld": round(mtld, 2) if mtld is not None else None}
+
+
+def _code_switching(chunks) -> list[dict]:
+    """Marker 12: German words detected in Spanish speech."""
+    switches = []
+    for i, c in enumerate(chunks):
+        w = _clean_word(c["text"])
+        if w in GERMAN_WORDS:
+            switches.append({"index": i, "word": w, **c["timestamp"]})
+    return switches
+
+
+def _disfluency_following(chunks, filled_pauses, empty_pauses) -> list[dict]:
+    """Marker 13: Word class of the word following each filled/empty pause."""
+    results = []
+    for fp in filled_pauses:
+        idx = fp["index"]
+        if idx + 1 < len(chunks):
+            next_word = chunks[idx + 1]["text"]
+            results.append({
+                "disfluency_type": "FP",
+                "disfluency": fp["text"],
+                "following_word": next_word.strip(),
+                "following_class": _word_class(next_word),
+            })
+    for ep in empty_pauses:
+        idx = ep["after_index"]
+        if idx + 1 < len(chunks):
+            next_word = chunks[idx + 1]["text"]
+            results.append({
+                "disfluency_type": "EP",
+                "disfluency": f"[pause {ep['gap_ms']:.0f}ms]",
+                "following_word": next_word.strip(),
+                "following_class": _word_class(next_word),
+            })
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+def extract_markers(
+    transcript: dict,
+    duration_s: float | None = None,
+    textgrid_path: str | None = None,
+) -> dict:
+    """Extract all markers from a transcript dict.
+
+    Includes the original Schmid-style + temporal + lexical markers,
+    Phase-1 acoustic markers (F0, voice quality, spectral tilt, MFCCs),
+    and — when a TextGrid is provided — Phase-2 alignment-based markers
+    (VOT, vowel formants, rhythm metrics).
+
+    Parameters
+    ----------
+    transcript : dict
+        Output of ``transcribe.transcribe()``.
+    duration_s : float, optional
+        Override audio duration (defaults to ``transcript["duration_s"]``).
+    textgrid_path : str, optional
+        Path to an MFA-produced TextGrid.  When provided, alignment-based
+        markers (VOT, vowel formants/VSA, rhythm metrics) are extracted.
+
+    Returns
+    -------
+    dict with keys for every marker group.
+    """
+    chunks = transcript["chunks"]
+    if duration_s is None:
+        duration_s = transcript["duration_s"]
+
+    clean_words = _clean_tokens(chunks)
+    word_count = len(clean_words)
+
+    # A. Schmid disfluency markers
+    fps = _filled_pauses(chunks)
+    eps = _empty_pauses(chunks)
+    rps = _repetitions(chunks)
+    rts = _retractions(chunks)
+
+    per100 = lambda n: round((n / word_count) * 100, 2) if word_count else 0
+
+    # B. Temporal / fluency
+    temporal = _temporal_markers(chunks, duration_s, word_count)
+
+    # C. Lexical
+    lex = _lexical_diversity(chunks)
+    cs = _code_switching(chunks)
+
+    # D. Disfluency context
+    df_context = _disfluency_following(chunks, fps, eps)
+    class_counts = Counter(d["following_class"] for d in df_context)
+
+    # E. Acoustic markers (Phase 1)
+    audio_path = transcript.get("audio_path")
+    if audio_path:
+        acoustic = extract_acoustic_markers(audio_path)
+    else:
+        acoustic = {}
+
+    # F. Alignment-based markers (Phase 2) — requires MFA TextGrid
+    if textgrid_path and audio_path:
+        alignment = extract_alignment_markers(audio_path, textgrid_path)
+    else:
+        alignment = {}
+
+    return {
+        "word_count_clean": word_count,
+        "duration_s": duration_s,
+        # A — Schmid disfluency markers
+        "filled_pauses": {
+            "count": len(fps),
+            "per_100_words": per100(len(fps)),
+            "items": fps,
+        },
+        "empty_pauses": {
+            "count": len(eps),
+            "per_100_words": per100(len(eps)),
+            "threshold_ms": 300,
+            "items": eps,
+        },
+        "repetitions": {
+            "count": len(rps),
+            "per_100_words": per100(len(rps)),
+            "items": rps,
+        },
+        "retractions": {
+            "count": len(rts),
+            "per_100_words": per100(len(rts)),
+            "items": rts,
+        },
+        # B — Temporal / fluency
+        "temporal": temporal,
+        # C — Lexical
+        "lexical_diversity": lex,
+        "code_switching": {
+            "count": len(cs),
+            "items": cs,
+        },
+        # D — Disfluency context
+        "disfluency_following": {
+            "items": df_context,
+            "class_distribution": dict(class_counts),
+        },
+        # E — Acoustic markers (Phase 1)
+        "acoustic": acoustic,
+        # F — Alignment-based markers (Phase 2)
+        "alignment": alignment,
+    }

requirements.txt

@@ -0,0 +1,11 @@
+gradio>=4.0
+librosa>=0.10
+soundfile>=0.12
+praat-parselmouth>=0.4.3
+praatio>=6.0
+pyphen>=0.14
+lexical-diversity>=0.1.1
+pandas>=2.0
+numpy>=1.24
+scipy>=1.10
+matplotlib>=3.6