# Hagerman & Olofsson 4 phases - RSB en sortie d'aide auditive (MATLAB)
# ==================== VERSION MATLAB PARALLELE (diffusion) ====================

Portage MATLAB de l'app R de reference HAtest/HO_4phases_R_parallel : memes
formules, memes reglages, memes colonnes de resultats. Les RSB des deux mesures
(jusqu'a 5 RSB x 2 mesures = 10 taches independantes) sont calcules en
PARALLELE sur plusieurs coeurs (parfor / Parallel Computing Toolbox) ;
"Coeurs = 1" (ou toolbox absente) donne le mode sequentiel, strictement
equivalent.

Prerequis : MATLAB R2020a ou plus recent, avec Signal Processing Toolbox.
La Parallel Computing Toolbox est OPTIONNELLE (sans elle : mode sequentiel).
Aucune autre dependance ; aucun fichier compile.

# Lancement
-------------------------------------------------------------------------------
Dans MATLAB, se placer dans ce dossier puis :
    HO4PhasesApp

Pilotage par script (sans interface, ou pour l'automatisation) :
    p    = ho_params();
    cal  = ho_calibrate('cal.wav', 92.1);
    opts = struct('method', 'envelope_sub', 'nWorkers', 5, ...
                  'out_root', 'results_HO');
    R    = ho_process_all(struct('m1', 'mesure1.wav'), cal, p, opts);
    R.m1.table

# Principe de la mesure (Hagerman & Olofsson, 4 phases)
-------------------------------------------------------------------------------
But : mesurer le RSB REEL en SORTIE d'aide auditive et le comparer au RSB
d'ENTREE. Pattern .wav STEREO : piste 1 = micro de reference (RSB d'entree),
piste 2 = sortie d'aide auditive (RSB de sortie). Pour chaque RSB (+10, +5,
0, -5, -10 dB), la meme scene est rejouee 4 fois en inversant la polarite de
la parole (S/mS) et du bruit (N/mN) :
    Speech = (SpN + SmN - mSpN - mSmN) / 4      -> le bruit s'annule
    Noise  = (SpN - SmN + mSpN - mSmN) / 4      -> la parole s'annule
    Error  = (SpN + SmN + mSpN + mSmN) / 4      -> doit tendre vers 0
    RSB    = 20*log10(rms(Speech)) - 20*log10(rms(Noise))

Qualite d'extraction : marge = min(Speech, Noise) - Error [dB], verdict
OK >= 20 dB | Moyen 15-20 | Mediocre 10-15 | Mauvais < 10 (critere des
20 dB : Miller et al. 2017, d'apres Naylor & Johannesson 2009). Colonnes
in_residu / in_marge / in_qualite (acquisition) et out_* (sortie AA, inclut
la variabilite propre de l'aide).

Deroulement : clap de depart (decoupage), calibration stereo (defaut
92,1 dB SPL : pistonphone B&K 4230 a 94 dB via reducteur 1/2" + PA 100),
passe-haut 125 Hz, alignement double (debut + fin, sur SpN), fenetre de
mesure qui retire le lead-in (40 s) et la queue (10 s).

# Alignement : methode + raffinement sous-echantillon
-------------------------------------------------------------------------------
Menu "Alignement" (Enveloppe de Hilbert / Structure fine / Aucun) + case
"Raffinement sous-echantillon (precision de phase)".

L'annulation H&O exige une coherence de PHASE. Un alignement a l'echantillon
ENTIER laisse un residu jusqu'a +/-0,5 ech. ; l'annulation residuelle vaut
2*sin(pi*f*dt) -> ~5 dB seulement a 8 kHz a 44,1 kHz. La case affine le
recalage SOUS l'echantillon (pic parabolique + retard fractionnaire de
Lagrange) : mesure ici (decalage vrai 3,4 ech.) : 12 dB -> 38 dB
d'annulation large bande. A privilegier : Enveloppe + case cochee.

# RSB pondere SII et audibilite SII
-------------------------------------------------------------------------------
- RSB pondere SII (ANSI S3.5-1997, 21 bandes critiques, comme l'equipe de
  Nancy, Cahiers de l'Audition 35(3) 2022) : calcule TOUJOURS, colonnes
  in_snr_sii / out_snr_sii ; la case "Afficher le RSB pondere SII" ne pilote
  que l'affichage (serie pointillee + triangles sur le graphe RSB).
- Audibilite ponderee SII a DYNAMIQUE REELLE (IEC 60118-15 : trames 125 ms,
  centiles L99/L30) : onglet "Audibilite SII". Panneau "Audiogramme" :
  standards IEC 60118-15 N1-N7 / S1-S3 (Bisgaard 2010) ou personnalise
  (10 HL aux frequences 250-6000 Hz) ; seuils au tympan = HL + RETSPL(HA-1)
  + RECD adulte ; canal de reference transpose par le REUG (Bentler &
  Pavlovic 1989). Avec audiogramme, le graphe montre 4 conditions : sortie
  AA m1/m2, malentendant oreille nue, normo-entendant oreille nue.

# Sorties (dossier results_HO/ a cote de l'enregistrement 1)
-------------------------------------------------------------------------------
  m1_off/ , m2_on/  CSV des RSB (*_outSNR.csv, toutes colonnes : RSB, SII,
                    audibilites, residu/marge/qualite), CSV de l'audibilite
                    par bande (*_audibilite_bandes.csv), .wav des composantes
                    extraites (in_/out_ speech/noise).
  PNG des planches (RSB_sortie, Gains, EDI, Audibilite_SII) auto-exportes.

# Tests
-------------------------------------------------------------------------------
    matlab -batch "test_moteur_synthetique"   % moteur : RSB exacts, sous-ech.,
                                              % parallele == sequentiel
    matlab -batch "test_moteur_synthetique; test_app_headless"  % app complete

# Fichiers
-------------------------------------------------------------------------------
  HO4PhasesApp.m        interface (uifigure), pilotable par script
  ho_process_all.m      orchestrateur (taches mesure x RSB, parfor/sequentiel)
  ho_worker_snr.m       traitement d'UN RSB (decoupe, extraction, gains, EDI)
  ho_extract.m          extraction 4 phases + SII + audibilite
  ho_align.m            alignement xcorr + raffinement sous-echantillon
  ho_snr_sii.m          RSB pondere SII         ho_sii_critical.m  bandes ANSI
  ho_audibility_sii.m   audibilite dynamique    ho_quality_rating.m verdict
  ho_std_audiograms.m   Bisgaard 2010           ho_seuil_tympan.m  HL->SPL
  ho_reug_ansi.m        REUG B&P 1989           ho_gain_thirdoctave.m
  ho_params.m ho_calibrate.m ho_detect_clap.m ho_cut_segment.m
  ho_read_range.m ho_edi.m ho_envelope.m ho_gain_spectrum.m

# Correspondance avec la version R
-------------------------------------------------------------------------------
La reference fonctionnelle est HAtest/HO_4phases_R_parallel (R/Shiny). Ce
dossier en est le portage MATLAB a parite de fonctionnalites (alignement
sous-echantillon, RSB pondere SII, audibilite SII, qualite d'extraction,
parallele). Toute evolution validee d'un cote est a reporter de l'autre.

# References
-------------------------------------------------------------------------------
Hagerman, B. & Olofsson, A. (2004), Acta Acustica united with Acustica 90(2),
356-361. | Miller, C.W. et al. (2017), Int J Audiol 56(8), 568-579. |
ANSI S3.5-1997. | Bisgaard, Vlaming & Dahlquist (2010), Trends Amplif 14(2). |
Bentler & Pavlovic (1989). | IEC 60118-15.

# Note de version - 2026-09-05 (validation croisee R <-> MATLAB)
-------------------------------------------------------------------------------
Valide sur enregistrements reels (Phonak L90-R, 2 mesures x 5 RSB, 96 kHz)
contre l'app R HO_4phases_R_parallel : TOUTES les colonnes identiques a
l'arrondi d'affichage pres (RSB, niveaux, marges, RSB pondere SII,
audibilites). Le pwelch en puissance de ce paquet a ete pris comme reference
pour corriger le RSB pondere SII de la version R (biais d'amplitude de
seewave::meanspec sur la parole modulee).
