Github on Melabit

Il CNR è anche questo: un po' di codice

Tue, 01 Dec 2020 06:00:00 +0000

XKCD, Good code.

Per concludere nel miglior modo possibile questa serie di articoli (qui la prima e la seconda parte), cosa ci può essere di meglio di un po’ di codice?

Estrarre il testo da un file PDF

Cominciamo dallo script in R, pdf2csv.R, che estrae il testo da un file PDF, (che in questo caso specifico ho usato per estrarre i dati dalla domanda di partecipazione ad un concorso precedente). Qui sotto trovate l’immagine dello script, realizzata con Carbon (perché così è molto più bello), su GitHub c’è il sorgente vero e proprio, per chi voglia provare ad usarlo.

Per eseguire lo script è necessario aver installato sul proprio computer, non importa se è un Mac o un PC con Linux o Windows, l’ambiente R (in questo momento è disponibile la versione 4.0.3), meglio ancora se accompagnato da RStudio Desktop, che è di gran lunga il migliore sistema integrato di sviluppo (IDE) che abbia mai usato, oltre che uno strumento efficacissimo per affacciarsi all’uso di R.

Il codice è molto semplificato, ho tolto tutto ciò che non è strettamente necessario a far funzionare lo script. La chiave di tutto è la libreria pdftools per R. Di librerie per estrarre dati dai file PDF ne ho provate moltissime, sia per R che per Python, ma pdftools le batte tutte per potenza, semplicità e velocità. Ci sono dei tool che convertono un PDF in testo al ritmo di una pagina al minuto, pdftools riesce a convertire (molto bene, peraltro) un file di 400 pagine come questo in appena 5-6 secondi. C’è altro da aggiungere?

Lo script può essere utilizzato dalla linea di comando (per capirci, dal Terminale), lasciandolo esattamente com’è ed eseguendo il comando pdf2csv.R seguito dal nome dal file da convertire (se il nome del file contiene degli spazi va scritto fra virgolette),

	./pdf2csv.R file-da-convertire.pdf

che produrrà due file .csv contenenti il testo estratto dal file PDF. Il primo, con lo stesso nome del file di partenza, ha le righe numerate e cerca di riprodurre per quanto è possibile il layout del file originale. Nel secondo, salvato con il suffisso -clean, mancano i numeri di linea e vengono rimossi tutti gli spazi in eccesso, rendendolo più adatto ad una analisi automatica, in particolare quando il testo si estende per tutta la pagina (il primo file, invece, è molto più utile quando il testo è organizzato in colonne).

Prima di usare per la prima volta pdf2csv.R bisogna renderlo eseguibile tramite il comando chmod (ne ho già scritto diffusamente qui).

	chmod u+x pdf2csv.R

In alternativa si può lanciare lo script tramite il comando Rscript installato con R, senza che sia necessario renderlo eseguibile.

	Rscript ./pdf2csv.R file-da-convertire.pdf

È preferibile che il file PDF da convertire si trovi nella stessa cartella di pdf2csv.R. In caso contrario il testo estratto viene comunque salvato nella cartella dove si trova la script (ve l’avevo detto che lo script era molto semplificato!).

Per eseguire pdf2csv.R all’interno di RStudio bisogna commentare la linea 12 (basta aggiungere un # all’inizio della riga) e attivare la riga 14 o 15 (ma solo da una delle due) togliendo il # iniziale. Se si attiva la riga 14, si deve anche modificare la stringa file-da-convertire.pdf, sostituendola con il nome del file da convertire. Se invece si attiva la riga numero 15, al momento dell’esecuzione dello script comparirà una finestra grafica da cui selezionare il file PDF desiderato.

Nel repository su GitHub di questo articolo ho inserito dei file PDF di complessità crescente con cui fare qualche prova, fra cui un documento di quasi 1000 pagine (un vecchio manuale di riferimento del formato PDF, potevo scegliere qualcosa di diverso?), che può essere utile per valutare la velocità di conversione dello script. Non è necessario farlo a mano, il tempo di esecuzione di un qualunque programma o script si può misurare in modo preciso dal Terminale anteponendo il comando di sistema time, come mostrato qui sotto.¹

	time ./pdf2csv.R PDFReference.pdf

Come piccola chicca finale, ho aggiunto al repository su GitHub un file PDF contenente del testo (apparentemente) nascosto, provate a convertirlo e vi accorgerete di quanto sia banale recuperare il testo completo.

Generare automaticamente dei documenti con AWK

Tirar fuori il testo contenuto in un file PDF è quasi sempre solo il primo passo del lavoro, perché quello che vogliamo veramente è filtrare il contenuto del documento mantenendo solo le informazioni che ci interessano. Nel caso specifico, io avevo bisogno di selezionare dalla domanda di concorso precedente solo i dati relativi ad una specifica tipologia di attività (ad esempio tutti gli articoli scientifici pubblicati), salvandoli in un file ad hoc. E, già che c’ero, volevo anche costruire una tabella LaTeX per ciascun articolo. Una cosa abbastanza facile da fare con AWK.

Di AWK ho già parlato tempo fa e non mi ripeterò, dirò solo che è un linguaggio ideale per analizzare un file di testo una riga alla volta, verificando se si presentano determinate condizioni ed eseguendo le operazioni programmate corrispondenti.

Nonostante i suoi tanti pregi, AWK ha una limitazione piuttosto seria: per come è strutturato, AWK deve per forza di cose esaminare tutto il file senza poter tornare indietro, e quindi è piuttosto difficile fargli eseguire delle operazioni basate su condizioni multiple complesse. È molto meglio (quando è possibile) scrivere più script AWK, da eseguire in sequenza sullo stesso file di partenza o sull’output generato dallo script precedente, piuttosto che cercare di combattere con le limitazioni del linguaggio, complicando a dismisura il codice.

In una prima versione di questo articolo avevo pensato di utilizzare un breve estratto della mia domanda di concorso precedente per descrivere il funzionamento degli script in AWK. Ma mentre scrivevo mi sono accorto che il discorso sarebbe stato così specifico da essere quasi inutile. Ho preferito quindi preparare un piccolo file PDF tratto dagli ultimi post pubblicati su Melabit, con l’intestazione in YAML² di ciascun post seguita dalla prima frase del testo in Markdown e, quando c’è, dal link all’immagine iniziale. L’ho scelto perché la struttura di questo file assomiglia moltissimo a quella della mia domanda di concorso ma, allo stesso tempo, può essere uno schema di partenza applicabile a casi più generali.

Questo file PDF può essere considerato come la stampa di un piccolo _database_ di informazioni correlate, dove ogni post è un _record_, suddiviso a sua volta nei vari _campi_, rappresentati dalle righe di intestazione e dalla frase di testo.

Il file PDF si chiama Melabit ultimi post.pdf e, come gli altri file PDF, è disponibile nel repository su GitHub di questo articolo. Se lo aprite con Anteprima, noterete subito che ci sono delle righe vuote che separano chiaramente un post (nel linguaggio dei database, un record) dall’altro. Ma convertendo il file in testo,

	./pdf2csv.R "Melabit ultimi post.pdf"

(le virgolette sono necessarie perché il nome del file contiene degli spazi), le righe vuote scompaiono e le uniche interruzioni presenti nei due file CSV prodotti dallo script di conversione corrispondono al cambio pagina. Non so se questo sia un baco o una caratteristica voluta di pdftools, ma sta di fatto che è una particolarità con la quale dobbiamo fare i conti se vogliamo analizzare il testo con AWK.

Sembra una sciocchezza, ma senza le giuste interruzioni non è immediato riconoscere la fine di un record prima di iniziare ad esaminare quello successivo, in modo da chiudere correttamente la tabella LaTeX corrispondente al record appena esaminato e ad aprire quella relativa al record successivo. Inoltre, mentre in questo caso specifico la struttura del file PDF è volutamente molto semplice e ripetibile, nella maggior parte dei casi reali il documento da cui estrarre i dati può contenere informazioni strutturate in modi diversi, i campi da analizzare possono essere distribuiti in modo irregolare o mancare del tutto e ci possono essere incongruenze nella loro denominazione. Gestire tutti i casi possibili con un unico script lo renderebbe rapidamente troppo complesso.

Molto meglio affrontare il problema un pezzetto alla volta, utilizzando uno script specifico per ciascun tipo di informazione da estrarre (io ho avuto bisogno di 6 script AWK per eseguire tutto il lavoro di esportazione dei dati, o meglio quasi tutto il lavoro, perché per i casi meno frequenti ho preferito il buon vecchio copia-incolla manuale). In fondo è la stessa logica di Unix, che mette a disposizione un gran numero di strumenti semplici che messi insieme, come tanti mattoncini Lego, riescono a fare cose incredibili.

Un primo script, addblanklines.awk, può servire per inserire nel file CSV di partenza una riga vuota prima di ogni record (una cosa piuttosto semplice da fare in questo caso, dato che ogni post inizia sempre con la stringa “layout: post”). Lo script, appena quindici linee di codice, lo trovate “in bella” nell’immagine qui sotto (ma anche in questo caso il sorgente è su GitHub).

Bastano solo due linee di codice, la #4 e la #9, per aggiungere le righe vuote al posto giusto. Ma già che ci siamo, è conveniente dare anche una ripulita al file CSV togliendo le righe inutili, come quelle che contengono il numero di pagina o la stringa --- che segna l’inizio e la fine dell’intestazione in YAML (linee #5 e #12). Eseguendo lo script sul file CSV originale, si ottiene un nuovo file CSV con i vari record ben separati uno dall’altro.

	./addblanklines.awk "Melabit ultimi post-clean.csv" > file-con-righe-vuote.csv

Fatto questo, il passo successivo è semplice. Basta scansionare il file CSV appena generato, file-con-righe-vuote.csv, in cerca della stringa target layout: post e, ogni volta che se ne trova una, generare una nuova tabella LaTeX riempiendola con i dati tratti dalle voci (o più propriamente campi) successive. Il codice del secondo script, cvs2table.awk, è visibile nell’immagine qui sotto (mentre il sorgente è sempre su GitHub).

Lo script è relativamente lungo, sono più di 80 linee di codice, compresi commenti e righe vuote, ma una gran parte serve per implementare la funzione (linee #3-25) che riarrangia le informazioni presenti su più linee consecutive del file CSV in modo che vengano stampate su un’unica riga, e per generare la struttura di base del documento LaTeX (linee #35-42 e #83).

Tolte queste, il resto del codice è semplice, si tratta più che altro di scrivere le stringe giuste al momento giusto e di tenere conto dei casi in cui le informazioni si estendono su più linee consecutive (come succede ad esempio alle linee #61-62 e #66-73). Non entrerò nei dettagli di come funziona lo script, questo non è un corso di AWK (né tantomeno di R), basterà per ora dire che è scritto in modo da essere facilmente adattato a gestire esigenze analoghe. Per usarlo, si deve eseguire lo script usando come file di input file-con-righe-vuote.csv e salvando il risultato dell’elaborazione in un file LaTeX, che qui sotto ho chiamato (con la mia solita scarsa fantasia) lista-articoli.tex.

	./cvs2table.awk file-con-righe-vuote.csv > lista-articoli.tex

Mettere tutto insieme

Proviamo allora ad eseguire tutti insieme gli script presentati in questo articolo, in modo da ottenere il risultato finale desiderato. Dobbiamo prima di tutto convertire il file PDF in CSV con

	./pdf2csv.R "Melabit ultimi post.pdf"

che genera automaticamente il file “Melabit ultimi post-clean.csv”. Fatto questo, si eseguono in sequenza i due script AWK, salvando l’output del primo in un file intermedio.

	./addblanklines.awk "Melabit ultimi post-clean.csv" > file-con-righe-vuote.csv
	./cvs2table.awk file-con-righe-vuote.csv > lista-articoli.tex

Il risultato finale è un file LaTeX ben ordinato con una tabella per ogni articolo, come quello mostrato nella figura qui sotto la cui regolarità, messa in evidenza dai colori delle parole chiave, fa pensare ad uno spartito musicale.

Ma ha senso creare un file intermedio solo per trasferire l’output del primo script al secondo? Molto meglio usare il meccanismo di piping tipico in Unix, con il quale si può trasferire automaticamente il risultato dell’esecuzione di un comando all’ingresso di quello successivo, collegandoli con il carattere | (pipe)?³ Con il piping, i due comandi AWK precedenti possono essere eseguiti uno dopo l’altro in questo modo,

	./addblanklines.awk "Melabit ultimi post-clean.csv" | ./cvs2table.awk > lista-articoli.tex

evitando l’uso di un file intermedio. In questo caso non fa molta differenza, ma quando si devono trattare file molto grossi, il piping è molto più efficiente (con i velocissimi dischi SSD odierni non ce ne accorgiamo più, ma ai tempi dei dischi meccanici la scrittura di grossi file sul disco era un vero collo di bottiglia) e, cosa che non guasta mai, evita di intasare il disco rigido con un gran numero di file inutili.

E poi il piping è un meccanismo intrinsecamente elegante, che non a caso è stato adottato anche in alcuni linguaggi di programmazione odierni, come si può vedere nello script R mostrato nella prima parte di questo articolo (linee #24-25 e #35-37), dove il simbolo | usato in Unix è sostituito dalla strana combinazione di caratteri %>%, piuttosto fastidiosa da scrivere con una tastiera italiana (io almeno sbaglio sempre qualcosa).

Conclusioni

Chi ha l’occhio allenato si accorgerà facilmente che il file LaTeX risultante contiene alcuni errori piuttosto evidenti. Li ho lasciati apposta non solo per non complicare ulteriormente il codice, ma anche per mostrare quanto sia complicato il lavoro di estrazione automatica dei dati da file strutturati in modo non perfettamente regolare. Non è certo un caso che in questo campo ci sia una grossa attività di ricerca che prova a superare gli ostacoli e a rendere il tutto il più semplice e il più efficiente possibile.

Il comando time è presente di default nei sistemi operativi Unix come Linux e macOS. Su Windows time non esiste, ma si possono usare degli strumenti equivalenti. ↩︎
YAML è un linguaggio di markup particolarmente adatto per definire dei file di configurazione e, in generale, per rappresentare informazioni strutturate in modo semplice e leggibile, molto più facile da usare di strumenti più noti come XML e JSON. ↩︎
Il piping è uno dei meccanismi principali che rendono Unix una specie di Lego informatico. ↩︎

Sopravvivere al coronavirus: i dati

Tue, 14 Apr 2020 06:00:00 +0000

– Fonte: Edwin Hooper su Unsplash.

L’epidemia di coronavirus ha stravolto le nostre vite, costringendoci a tapparci in casa in attesa di tempi migliori. Da più di un mese le giornate sono scandite dalle conferenze stampa delle 18, veri e propri bollettini di guerra, con i numeri dei nuovi ricoverati, dei guariti e, purtroppo, dei troppi morti.

Ormai non si riesce più a parlare d’altro, sembra di essere in uno stato di animazione sospesa, di vivere al rallentatore in attesa di sapere se e quando questa tragedia finirà.

Anch’io non ho molta voglia di parlare d’altro. Non è che non ci abbia provato, di spunti ne ho fin troppi, ma ogni volta che mi metto al computer e provo a scrivere mi passa la voglia, mi sembra tutto troppo frivolo o poco appropriato.

E allora non è meglio togliersi il dente e decidersi ad affrontare l’argomento del giorno? Entro certi limiti. Non sono un virologo e non mi passa per l’anticamera del cervello atteggiarmi ad esperto di questo settore, come sembrano fare tanti frequentatori dei social. Per cui niente fatti del giorno, ipotesi fantasiose, cure mirabolanti, fake news ripetute allo sfinimento tanto a renderle quasi credibili.

Mi limiterò a guardare i dati e cercare di trarre qualche conclusione oppure a proporre qualche lettura che mi pare particolarmente interessante. E magari anche a presentare qualche strumento con cui sto provando ad affrontare al meglio questo lungo periodo di lavoro e di vita online.

Da dove cominciamo? Dai dati, dai numeri nudi e crudi, che sono in fondo le cose con le quali dovrei avere più dimestichezza.

Sin dai primi giorni della crisi, quando si credeva che il coronavirus fosse un problema esclusivamente cinese, la fonte di informazione con i dati globali più aggiornati e attendibili è stata la dashboard interattiva della Johns Hopkins University (in italiano si dovrebbe dire “cruscotto”, ma per favore lasciatemi usare il termine originale), che riceve un miliardo di accessi al giorno ma che è stata messa su in una giornata da un giovane laureato in Ingegneria Civile di origine cinese. Il gruppo aveva già sviluppato uno strumento simile per studiare la diffusione del morbillo, ma di sicuro quello che sono riusciti a fare dall’oggi al domani è semplicemente straordinario. Tutti i dati su cui si basa la dashboard sono facilmente scaricabili da GitHub, a disposizione di chi volesse analizzarli con i propri strumenti.

La Protezione Civile italiana ha messo online una dashboard molto simile, adattata alla realtà italiana. La grafica è la stessa, la fruibilità purtroppo un po’ meno. Ma quello che come al solito manca quando si ha a che fare con le realtà italiane (istituzionali e non) è la facilità di accesso ai dati:¹ le schede riepilogative giornaliere sono in pdf (che in questo caso specifico sembra archeologia informatica) e ci sono serie di dati separate per le province e le regioni, oltre che per l’intera nazione, mentre sarebbe molto più produttivo lavorare sui dati disaggregati (presentati cioè al livello più basso possibile, che per l’Italia potrebbe essere il comune, il CAP o in questo caso particolare l’ASL), da aggregare in un secondo momento in base al livello di dettaglio desiderato.

Altra dashboard interessante ma piuttosto complessa da utilizzare (oltre che estremamente lenta) è quella dell’European Centre for Disease Prevention and Control.

Molto più pratici sono il COVID-19 Tracker di Microsoft (bisogna ammettere che questa volta Microsoft ha messo su uno strumento molto ben fatto e facile da usare) e la dashboard di Edward Parker, sviluppata con Shiny (un package aggiuntivo di R che permette di costruire con facilità delle applicazioni web interattive). Di quest’ultima trovo particolarmente interessanti i grafici a livello regionale (Region Plots), dove è possibile selezionare con molta facilità un gran numero di visualizzazioni diverse, nonché la possibilità di confrontare i dati di questa pandemia con quelli di altre epidemie recenti come la SARS, l’influenza suina ed Ebola.

Grafico tratto dalla dashboard di Edward Parker, che mostra l’andamento nel tempo dell’infezione da COVID-19 per i principali paesi europei e per gli USA. Il tempo iniziale di ciascun grafico corrisponde con il giorno in cui si è verificato il 100-esimo caso confermato di infezione. Questa rappresentazione mostra che la velocità di diffusione dell’epidemia è identica in Italia, Germania e Francia, mentre Spagna e UK sono caratterizzata da una velocità di diffusione rispettivamente maggiore e minore (ma la velocità dell’UK tende ad avvicinare quella dei primi tre paesi). Gli USA fanno decisamente storia a sé.

Un’altra dashboard, quella di Weather.com sviluppata in collaborazione con IBM, sarebbe forse lo strumento più interessante in assoluto (e nei primi giorni lo era), ma ora è diventata così lenta e piena di errori da essere inusabile.

La pagina dedicata al COVID-19 di Our World in Data è molto più classica ma, anche se meno immediatamente fruibile di una dashboard, permette di visualizzare e analizzare i dati in un numero enorme di modi diversi. Da non perdere.

Semplicemente eccezionale, ma limitata ai soli Stati Uniti, è la mappa interattiva del New York Times, i cui dati sono verificati uno ad uno da un team di giornalisti del New York Times. I dati originali usati per preparare la mappa si trovano come al solito su GitHub e, analogamente all’Italia, sono aggregati a livello di contea e di stato. Ma se si tiene conto delle dimensioni e della maggiore omogeneità degli USA, l’aggregazione per contea, pur se non ideale, contiene già un buon livello di dettaglio, diciamo quasi come per noi quella a livello di comune.

Per finire torniamo alla situazione italiana, così come la presenta la pagina dedicata di Repubblica. Rispetto agli strumenti visti finora non è niente di particolarmente innovativo, ma i dati a livello regionale sono molto interessanti e sono presentati in modo graficamente ineccepibile. Peccato solo che la lettura delle scale dei grafici non sia così immediata come dovrebbe.

Un problema serio appena trattato persino dal Sole 24 Ore, del quale varrebbe la pena discutere più in dettaglio anche qui, prima o poi. ↩︎