Come usare Tométo Tomato

Introduzione

tometo_tomato è un’utilità a riga di comando progettata per eseguire “fuzzy join” tra due file CSV. In altre parole, permette di collegare due tabelle basandosi su colonne i cui valori non sono identici, ma semplicemente “simili”, gestendo errori di battitura, abbreviazioni o differenze di formattazione.

Il Concetto di Base

L’idea è semplice: 1. Hai un file di input con dati “sporchi” o incompleti. 2. Hai un file di riferimento (anagrafica) che contiene i dati “puliti” e corretti. 3. Vuoi arricchire il file di input aggiungendo colonne prese dal file di riferimento, trovando le corrispondenze migliori anche quando non sono perfette.

I Nostri File di Esempio

Per questa guida, useremo due file:

1. File di input (docs/files/input.csv)

Un file con un elenco di comuni e regioni, ma con nomi imprecisi e problemi di case.

city,region
Cefalu',Sicilia
Reggio Calabria,CALABRIA
RODENGO-SAIANO,Lombardia

2. File di riferimento (docs/files/ref.csv)

Un’anagrafica pulita che contiene anche il codice ISTAT (city_code) che vogliamo aggiungere al nostro file di input.

city,region,city_code
Cefalù,Sicilia,082027
Reggio di Calabria,Calabria,080063
Rodengo Saiano,Lombardia,017164

Uso Fondamentale

Per collegare questi due file, useremo il seguente comando:

tometo_tomato docs/files/input.csv docs/files/ref.csv \
  -j "city,city" \
  -j "region,region" \
  -a "city_code" \
  -s \
  -o "output/clean_matches.csv"

Analizziamo il comando pezzo per pezzo:

  • tometo_tomato docs/files/input.csv docs/files/ref.csv: Indichiamo il programma da eseguire, seguito dal file di input e da quello di riferimento.
  • -j "city,city": Specifichiamo la prima coppia di colonne da usare per il join. In questo caso i nomi delle colonne sono identici.
  • -j "region,region": Specifichiamo la seconda coppia di colonne. Il programma calcolerà un punteggio di somiglianza medio basato su tutte le coppie fornite.
  • -a "city_code": Indichiamo quale colonna del file di riferimento (ref.csv) vogliamo aggiungere al nostro file di output.
  • -s: Chiediamo di includere anche una colonna con il punteggio di somiglianza (avg_score) nell’output.
  • -o "output/clean_matches.csv": Specifichiamo il percorso del file CSV di output in cui salvare i risultati.

Il Risultato

Dopo aver eseguito il comando, il file output/clean_matches.csv conterrà i dati del file di input, arricchiti con le colonne del file di riferimento per le righe che hanno trovato una corrispondenza con un punteggio sufficientemente alto. Ad esempio, la riga RODENGO-SAIANO,Lombardia verrà collegata a Rodengo Saiano,Lombardia, e il city_code 017164 verrà aggiunto alla riga di output.

Opzioni Avanzate Utili

L’utilità offre molte altre opzioni per personalizzare il processo:

  • --threshold o -t: Permette di modificare la soglia di somiglianza minima (default: 85) per considerare una corrispondenza valida.
  • --infer-pairs: Tenta di indovinare automaticamente le coppie di colonne da usare per il join, basandosi sulla somiglianza dei nomi delle colonne.
  • --latinize: Normalizza i caratteri, rimuovendo accenti e simboli speciali prima del confronto, come abbiamo visto nei nostri esempi con strip_accents.
  • --keep-alphanumeric o -k: Mantiene solo lettere, numeri e spazi nelle colonne di join, rimuovendo punteggiatura e caratteri speciali. Utile per dati con apostrofi, trattini, punti, ecc.

Esempio: bash tometo_tomato input.csv ref.csv -j "name,ref_name" --keep-alphanumeric -o output.csv # oppure versione breve tometo_tomato input.csv ref.csv -j "name,ref_name" -k -o output.csv Questo permette di far corrispondere, ad esempio, John O'Connor con John OConnor, oppure Anna & Co. con Anna Co.

  • --raw-case e --raw-whitespace: Disabilitano la normalizzazione di maiuscole/minuscole e degli spazi, per un controllo più fine.

Ambiguità e comportamento degli output

Lo strumento segnala e gestisce in modo esplicito i casi ambigui per evitare di inserire dati potenzialmente errati nell’output “pulito”.

  • Definizione di ambiguità: una riga di input è considerata “ambigua” quando due o più righe del file di riferimento ottengono lo stesso punteggio massimo medio (avg_score) per quell’input, e tale punteggio soddisfa la soglia --threshold.
  • Comportamento: le righe ambigue NON vengono incluse nell’--output-clean. In questo modo il file “pulito” contiene solo corrispondenze non ambigue (una sola migliore corrispondenza con punteggio >= soglia).
  • Esportazione ambigui: per salvare le righe candidate ambigue, usare l’opzione --output-ambiguous ambiguous.csv. Il file conterrà le righe di riferimento che hanno ottenuto il punteggio massimo (uguale) per ciascun input ambiguo.
  • Avviso: lo strumento rileva sempre la presenza di record ambigui e mostra un avviso quando ne trova uno; l’avviso suggerisce di usare --output-ambiguous per salvare i dettagli.

Esempio: se per l’input "Reggio Calabria" due righe di riferimento diverse ottengono entrambe 95.45 e la soglia è 85, l’input risulterà ambiguo, non comparirà in --output-clean e potrai ispezionare entrambe le righe candidate con --output-ambiguous.