Correzioni alla trascrizione originale: generare e applicare patch

Durante il lavoro di lemmatizzazione può capitare di individuare errori nella trascrizione originale (forme errate, notazione Jefferson scorretta, tokenizzazione sbagliata). Questa guida descrive il workflow per riportare tali correzioni nel file sorgente del corpus, senza interrompere il lavoro di lemmatizzazione.

Concetto generale

Il file di lavoro (.csv nella cartella wip/) è l’unico punto in cui si modificano i dati. Le correzioni alla trascrizione non vengono applicate direttamente al repository del corpus: viene invece generato un file .patch (diff unificato) che può essere applicato sul branch dev del modulo corrispondente con un semplice git apply.

In questo modo:

il lavoro di lemmatizzazione procede in modo autonomo;
le correzioni alla trascrizione vengono proposte in modo tracciabile e revisionabile;
è sempre possibile aggiornare la patch se il file sorgente viene nel frattempo modificato.

Struttura delle cartelle

lemmatization-project/
├── wip/
│   └── KIP/
│       └── BOA1007.csv          ← file di lavoro con lemma/upos + correzioni
├── patches/
│   └── KIP/
│       ├── BOA1007.vert.tsv.patch       ← patch da applicare al corpus
│       └── BOA1007.vert.tsv.recap.md    ← riepilogo delle modifiche
└── make_patch.py                ← script per generare la patch

Cosa si può correggere nel CSV

Nel file di lavoro .csv le seguenti colonne vengono propagate nella patch:

Colonna Descrizione

Colonna	Descrizione
`span`	La forma trascritta in notazione Jefferson (es. `[s:ì].` al posto di `[ssì].`)
`form`	La forma ortografica normalizzata (es. `sostituire` al posto di `sostiuire`)
`jefferson_feats`	Le feature prosodiche (es. `Intonation=Falling`, `{P}` per le pause brevi)

span

La forma trascritta in notazione Jefferson (es. [s:ì]. al posto di [ssì].)

form

La forma ortografica normalizzata (es. sostituire al posto di sostiuire)

jefferson_feats

Le feature prosodiche (es. Intonation=Falling, {P} per le pause brevi)

Le colonne lemma e upos non vengono incluse nella patch: appartengono all’annotazione linguistica, non alla trascrizione.

Modifiche strutturali: unire token

Se durante la lemmatizzazione si stabilisce che due token vanno uniti (es. elle + due. → elledue.), è sufficiente:

Nel CSV, eliminare la riga del secondo token e aggiornare span e form del primo.
Lo script rileva automaticamente l’assenza del secondo token nel CSV e lo elimina dalla patch.
Il timestamp End= del token eliminato viene trasferito automaticamente al token risultante.

In caso di eliminazione, lo script produce un file .recap.md con tutte le informazioni del token rimosso. Controlla sempre il recap per verificare se ci sono colonne come overlaps o prolongations che richiedono un aggiustamento manuale.

Generare la patch

Lo script make_patch.py si trova nella cartella tools/ del progetto KIParla.

Dalla cartella lemmatization-project/, eseguire:

python3 ../tools/make_patch.py wip/KIP/BOA1007.csv ../KIP/tsv/BOA1007.vert.tsv

Lo script produce:

patches/KIP/BOA1007.vert.tsv.patch — il file di patch
patches/KIP/BOA1007.vert.tsv.recap.md — riepilogo delle modifiche strutturali (se presenti)

L’output indica quante righe vengono aggiunte/modificate/rimosse:

Patch written: patches/KIP/BOA1007.vert.tsv.patch  (+6 / -9 lines)
Recap written: patches/KIP/BOA1007.vert.tsv.recap.md  (3 items)

Per un file di un corpus diverso (es. KIPasti), il percorso del TSV cambia di conseguenza:

python3 ../tools/make_patch.py wip/KIPasti/TOA1001.csv ../KIPasti/tsv/TOA1001.vert.tsv

Leggere il recap

Prima di applicare la patch, leggere il file .recap.md. Ogni voce indica cosa è successo ai token eliminati o aggiunti:

Marcatore Significato

Marcatore	Significato
✅ auto-transferred	Il timestamp `Begin=` o `End=` del token rimosso è stato trasferito automaticamente al token adiacente.
⚠️ manual check needed	Una colonna come `overlaps` o `prolongations` del token rimosso conteneva un valore non vuoto. Va verificato manualmente nel file sorgente dopo aver applicato la patch.
❌ conflict	Si è verificato un conflitto nel trasferimento dei timestamp. Richiede intervento manuale prima di applicare la patch.
ADD	Un token presente nel CSV non esiste nel TSV. L’inserimento non può essere automatizzato: va fatto a mano nel sorgente.

✅ auto-transferred

Il timestamp Begin= o End= del token rimosso è stato trasferito automaticamente al token adiacente.

⚠️ manual check needed

Una colonna come overlaps o prolongations del token rimosso conteneva un valore non vuoto. Va verificato manualmente nel file sorgente dopo aver applicato la patch.

❌ conflict

Si è verificato un conflitto nel trasferimento dei timestamp. Richiede intervento manuale prima di applicare la patch.

ADD

Un token presente nel CSV non esiste nel TSV. L’inserimento non può essere automatizzato: va fatto a mano nel sorgente.

Verificare la patch

Prima di applicarla, verificare che la patch sia valida:

cd /path/to/KIP
git checkout dev
git apply --check ../lemmatization-project/patches/KIP/BOA1007.vert.tsv.patch

Se non viene restituito nessun errore, la patch è applicabile.

Se il file sorgente è stato modificato dopo la generazione della patch (es. un’altra patch è già stata applicata), il controllo potrebbe fallire con un errore di contesto. In questo caso, rigenerare la patch dallo stesso CSV aggiornato:

python3 ../tools/make_patch.py wip/KIP/BOA1007.csv ../KIP/tsv/BOA1007.vert.tsv

Applicare la patch

cd /path/to/KIP
git checkout dev
git apply ../lemmatization-project/patches/KIP/BOA1007.vert.tsv.patch

Dopo l’applicazione, fare il commit sul branch dev:

git add tsv/BOA1007.vert.tsv
git commit -m "fix: transcription corrections from lemmatization of BOA1007"

Se il recap segnalava voci con ⚠️, applicare prima la patch, poi correggere manualmente le colonne interessate, e includere tutto nello stesso commit.