Umanistica Digitale |

tei-mcp v0.3: codificare in TEI senza riscrivere la fonte

Tue, 05 May 2026 00:00:00 +0000

Quando ho , lo scopo era impedire agli assistenti IA di allucinare marcatura TEI. L’ancoraggio allo schema ha risolto una parte del problema: con un accesso diretto, per mezzo di strumenti, alla specifica P5, il modello non deve più indovinare che cosa significhi un elemento o quali attributi accetti. L’output passa la validazione.

Ma nella codifica TEI l’allucinazione ha due facce, e lo schema ne coglie una sola. Validare rispetto alla specifica vi dice che la marcatura è ben formata; non dice nulla del testo che quella marcatura racchiude. Ed è lì, nel testo, che si annidano le allucinazioni più dannose. La composizione span-locked, novità di punta della v0.3, è pensata apposta per impedirle.

Indice dei Contenuti

L’allucinazione che lo schema non vede

Chiedete a un modello di codificare una lettera francese del Cinquecento e otterrete spesso un documento TEI dall’aria impeccabile: header compilato, tag <persName> al posto giusto, <dateline> ben formata. Passatelo per validate_document, e passa.

Poi confrontate il corpo con la fonte.

mesme è diventato même. Una virgola è migrata. luy è stato modernizzato in lui senza dir niente a nessuno. Una frase ostica nel manoscritto è stata «corretta» in qualcosa di più pulito. Nessuna di queste modifiche era stata richiesta; nessuna viene segnalata. Il documento è valido per lo schema e sbagliato in silenzio.

In un flusso di lavoro archivistico – dove il testo codificato diventa il documento definitivo su cui contano lettori, indici di ricerca e citazioni – è questo il guasto che conta di più. Un tag malformato è una seccatura; una grafia modernizzata che nessuno nota per cinque anni è una corruzione.

La composizione span-locked

La nuova versione (v0.3) include un meccanismo di prevenzione delle allucinazioni mirato proprio a questo guasto. L’obiettivo di progetto è rendere le allucinazioni nel corpo del testo impossibili per costruzione, non semplicemente improbabili.

L’idea è semplice: il modello non batte mai il corpo del testo.

Il flusso di lavoro, invece, è questo:

Il modello chiama get_source("letter_001") e riceve il testo semplice di partenza come stringa immutabile.
Per ogni tag che vuole applicare, chiama tag_span("letter_001", start, end, element_path, attrs), registrando un elemento TEI su un intervallo di caratteri della fonte.
Quando ha finito, chiama compose("letter_001"). Il server intercala i tag registrati nel testo semplice originale, produce la TEI finale e poi verifica byte per byte che il contenuto testuale piatto del documento prodotto sia uguale alla fonte.

Se i byte coincidono, il documento viene restituito. Se non coincidono – se i tag del modello implicano in qualche modo un corpo che differisce dalla fonte anche di un solo carattere – compose() solleva un’eccezione invece di consegnare un documento corrotto.

Non esiste percorso, in questo flusso, che porti il modello a produrre un documento TEI con un corpo diverso dalla fonte. L’invariante è meccanico, non comportamentale: non dovete fidarvi del modello perché non allucini; dovete fidarvi di un == fra due stringhe di byte.

Che cos’è, e che cosa non è

La composizione span-locked è complementare all’ancoraggio allo schema, non lo sostituisce. Gli strumenti di ancoraggio (validate_document, lookup_element, valid_children e il resto dei sedici originali) aiutano il modello a produrre TEI valida; la composizione span-locked garantisce che il corpo del testo dentro quella TEI sia fedele alla fonte. Un flusso di codifica che si possa mettere in produzione deve soddisfare entrambi gli assi, e ora un solo server li copre tutti e due.

Non è nemmeno la panacea. compose() non verifica ancora che i tag registrati siano ammessi da una personalizzazione ODD caricata: arriverà. I tag registrati vivono nella memoria del processo e non sopravvivono a un riavvio. E i file di partenza devono essere leggibili da dove gira il server. Sono tutte cose risolvibili, e nessuna intacca l’invariante di fondo.

Perché conta, al di là della TEI

Lo schema si generalizza. Ogni volta che si chiede a un modello di annotare, trasformare o incapsulare un testo – e ogni volta che l’integrità di quel testo conta più della capacità del modello di «migliorarlo» – la soluzione ha la stessa forma. Non chiedete al modello di ribattere il testo; chiedetegli istruzioni sul testo, e lasciate che un compositore deterministico le applichi sotto un invariante di uguaglianza.

Per le edizioni digitali, in particolare, questo cambia ciò che si può affidare a un modello senza rimorsi. La codifica diventa d’un tratto un compito delegabile, senza dover confrontare a mano ogni output con la fonte. La macchina fa la parte noiosa; il curatore rivede la marcatura, non l’ortografia.

Come aggiornare

Se avete già tei-mcp:

uvx tei-mcp@latest

Oppure da zero:

pip install tei-mcp

Per usare la composizione span-locked, indicate al server una directory di file di testo semplice:

export TEI_MCP_SPAN_SOURCE_ROOT=/path/to/sources
uvx tei-mcp

Il nome di ogni file, senza estensione, diventa l’ID del documento (letter_001.txt → letter_001).

Codice sorgente, documentazione completa e note di progetto sull’invariante:

Un’edizione digitale d’altro genere

Tue, 24 Mar 2026 00:00:00 +0000

La maggior parte delle fonti primarie non vede mai la luce. Il modello a cui ci affidiamo per rimediare, l’edizione digitale finanziata a bando, è troppo caro, troppo accentrato e troppo fragile per reggere su larga scala. Ho appena pubblicato in cui spiego perché l’edizione critica delle lettere di Cavriana la sto costruendo in un altro modo: fonti primarie digitalizzate che crescono per accumulo, con un’infrastruttura minima e una manutenzione automatica, aperte alla collaborazione e così poco costose da non aver bisogno di alcun finanziamento. È un argomento a favore di un’umanistica digitale che stia in piedi anche senza il sostegno delle istituzioni.

tei-mcp

Sun, 15 Mar 2026 00:00:00 +0000

tei-mcp: la TEI P5 per gli agenti IA

tei-mcp è un server open source che dà agli assistenti IA per la programmazione un accesso diretto alla specifica . Invece di affidarsi a ciò che ricorda dell’addestramento – da cui esce spesso una marcatura plausibile ma sbagliata – l’IA interroga la specifica in tempo reale.

Funzionalità

Il server analizza l’ODD della TEI P5 ed espone 16 strumenti:

Ricerca di qualunque elemento, classe, macro o modulo per nome, senza distinguere maiuscole e minuscole e con suggerimenti in caso di refuso
Risoluzione degli attributi lungo l’intera gerarchia di classi TEI (locali ed ereditati)
Espansione dei modelli di contenuto in alberi strutturati, con risoluzione di classi e macro
Verifica dell’annidamento: rapporto diretto genitore-figlio, o raggiungibilità ricorsiva con tracciamento del percorso
Validazione dei documenti rispetto alla TEI P5: modelli di contenuto, attributi, liste chiuse di valori, integrità dei riferimenti e avvisi di deprecazione
Validazione di singoli elementi per chi lavora per ritocchi successivi
Caricamento di personalizzazioni ODD per restringere lo schema al sottoinsieme proprio di un progetto
Ricerca in tutti i tipi di entità con espressioni regolari

Installazione

pip install tei-mcp

Oppure si esegue direttamente con:

uvx tei-mcp

Uso

Si aggiunge a qualsiasi client compatibile con MCP (Claude, Cursor, Windsurf ecc.):

{
 "mcpServers": {
 "tei": {
 "command": "uvx",
 "args": ["tei-mcp"]
 }
 }
}

Il codice sorgente e la documentazione sono nel .

tei-mcp: la TEI P5 per gli agenti IA

Sun, 15 Mar 2026 00:00:00 +0000

Chi ha provato a far scrivere XML TEI a un assistente IA per la programmazione sa già come va a finire: sbaglia. Gli elementi spuntano dove non dovrebbero, gli attributi vengono inventati, le regole di annidamento ignorate. Il modello ha un’idea vaga dell’aspetto della TEI, ma nessuna conoscenza affidabile della specifica.

tei-mcp rimedia dando agli agenti IA un accesso diretto, per mezzo di strumenti, alle Guidelines della TEI P5.

Indice dei Contenuti

Che cos’è MCP?

Il (MCP) è uno standard aperto che permette alle applicazioni di IA di collegarsi a fonti di dati e strumenti esterni. Pensate a una porta USB per l’IA: un solo protocollo con cui qualunque client compatibile – Claude, Cursor, Windsurf e altri – si innesta su servizi specializzati.

Un server MCP espone degli strumenti che l’IA può chiamare nel corso di una conversazione. Invece di affidarsi a ciò che ricorda dell’addestramento, il modello interroga una fonte viva e autorevole.

Che cosa fa tei-mcp

tei-mcp analizza la specifica ODD della TEI P5 ed espone 16 strumenti, che rispondono alle domande più comuni di chi cura o codifica un’edizione:

Che cos’è questo elemento? Cerca qualunque elemento, classe, macro o modulo per nome, senza distinguere maiuscole e minuscole e con suggerimenti in caso di refuso.
Quali attributi accetta? Risolve gli attributi lungo l’intera gerarchia di classi: prima quelli locali, poi quelli ereditati, in ordine.
Che cosa può contenere? Espande i modelli di contenuto in alberi strutturati, oppure restituisce l’elenco piatto dei figli ammessi.
Questo elemento può stare qui? Verifica l’annidamento genitore-figlio, o segue la raggiungibilità lungo l’intera gerarchia degli elementi.
Il mio documento è valido? Valida un file XML TEI rispetto alla specifica: modelli di contenuto, valori degli attributi, liste chiuse di valori, integrità dei riferimenti e avvisi di deprecazione.
E lo schema del mio progetto? Carica un file di personalizzazione ODD per restringere tutto quanto sopra al sottoinsieme di TEI proprio del vostro progetto.

Perché conta

Codificare in TEI vuol dire consultare le Guidelines di continuo. I codificatori esperti hanno interiorizzato gli schemi più comuni, ma anche loro devono controllare la specifica per gli elementi meno familiari o per i modelli di contenuto più intricati. Per gli assistenti IA, che di quella conoscenza interiorizzata non hanno nulla, il problema è peggiore: allucinano una marcatura plausibile all’occhio e sbagliata nella sostanza.

Con tei-mcp l’IA non deve più tirare a indovinare: cerca la risposta nella specifica prima di scrivere una sola parentesi angolare. Il risultato è una marcatura conforme alla TEI P5, o alla personalizzazione ODD del vostro progetto.

Per cominciare

Si installa da PyPI:

pip install tei-mcp

Poi lo si aggiunge alla configurazione del client MCP:

{
 "mcpServers": {
 "tei": {
 "command": "uvx",
 "args": ["tei-mcp"]
 }
 }
}

Al primo avvio il server scarica la specifica TEI; funziona con qualsiasi client compatibile con MCP.

Codice sorgente e documentazione completa:

Multi-Saxon

Fri, 28 Mar 2025 00:00:00 +0000

Multi-Saxon: trasformazioni XSLT in parallelo per grandi corpora TEI

Multi-Saxon colma una lacuna seria fra gli strumenti di elaborazione XML: esegue in parallelo trasformazioni XSLT 2.0 e 3.0 che LXML, la diffusa libreria XML per Python, non sa gestire. Pensato per grandi collezioni di documenti XML TEI, abbatte i tempi di elaborazione grazie a un’esecuzione parallela efficiente.

Caratteristiche principali

XSLT avanzato: elabora trasformazioni XSLT 2.0 e 3.0, fuori dalla portata di LXML
Elaborazione parallela: la parallelizzazione riduce drasticamente i tempi di trasformazione delle grandi collezioni di documenti
Su misura per la TEI: progettato apposta per i documenti XML della Text Encoding Initiative (TEI)
Prestazioni scalabili: gestisce con efficienza corpora da centinaia a migliaia di documenti
Multipiattaforma: funziona su sistemi operativi e ambienti diversi

Il problema che Multi-Saxon risolve

Chi lavora con la TEI nell’umanistica digitale si scontra spesso con due ostacoli:

LXML (una comune libreria Python per l’elaborazione XML) sostiene soltanto XSLT 1.0, e preclude quindi le funzionalità più avanzate di XSLT 2.0/3.0
Elaborare in sequenza grandi corpora di documenti TEI può richiedere tempi proibitivi

Multi-Saxon risponde a entrambi sfruttando le capacità XSLT avanzate di Saxon e distribuendo l’elaborazione su più core, con guadagni di prestazioni notevoli.

Realizzazione

Multi-Saxon accoppia Python al processore Saxon per Java in una pipeline di trasformazione ad alte prestazioni:

usa la libreria Saxon per Java per un’elaborazione XSLT 2.0/3.0 robusta
ricorre al multiprocessing per distribuire le trasformazioni sui core disponibili
gestisce con efficienza i pool di processi per massimizzare il throughput
offre un’interfaccia semplice per l’elaborazione in batch dei documenti TEI

Esempio d’uso

from multi_saxon import MultiSaxon

# Initialize with your XSLT stylesheet
transformer = MultiSaxon("transform.xsl")

# Transform a single document
transformer.transform("input.xml", "output.xml")

# Transform an entire directory in parallel
transformer.transform_directory("input_dir", "output_dir")

Che cosa cambia per l’umanistica digitale

Per i progetti di umanistica digitale alle prese con grandi collezioni di documenti TEI, Multi-Saxon rende possibili:

trasformazioni complesse sull’intero corpus, impensabili con LXML
tempi di elaborazione drasticamente ridotti (spesso di 5-10 volte sui sistemi multi-core)
analisi più sofisticate grazie alle funzionalità avanzate di XSLT 2.0/3.0
un flusso di lavoro più semplice per elaborare intere collezioni di documenti

Il codice sorgente e la documentazione sono nel .

persNamer

Fri, 28 Mar 2025 00:00:00 +0000

persNamer: collegare la TEI al Virtual International Authority File

persNamer è uno strumento Python specializzato che facilita l’integrazione, nei documenti XML TEI, dei dati di autorità sulle persone forniti da VIAF (Virtual International Authority File). Convertendo gli identificatori VIAF in marcatura TEI pronta all’uso, riduce di molto il lavoro manuale necessario per creare voci di persona strutturate in un’edizione critica digitale.

Il controllo di autorità nella TEI

Le edizioni critiche digitali richiedono spesso di identificare con precisione i personaggi storici, con i nomi normalizzati e le date di nascita e di morte. Mantenere un controllo di autorità coerente in tutto un progetto richiede di:

identificare le persone nei testi storici
trovare dati autorevoli su di loro
creare voci TEI formattate a dovere
garantire riferimenti coerenti in tutto il progetto

Passaggi che, di norma, sono manuali, lenti e soggetti a incoerenze.

Come funziona persNamer

persNamer automatizza questo flusso di lavoro:

Recupero dei dati VIAF: dato un identificatore VIAF, lo strumento recupera i dati RDF tramite negoziazione del contenuto HTTP
Estrazione delle informazioni essenziali: analizza l’RDF per estrarre il nome preferito, la data di nascita e la data di morte
Generazione della marcatura TEI: crea due frammenti XML:
- una voce dell’authority file (elemento <person> con un xml:id generato, <persName>, <birth>, <death> e <idno type="VIAF">)
- un tag di annotazione a parte (<persName> con un attributo ref che rimanda alla voce di autorità)

Questo doppio output permette ai curatori di mantenere un authority file centralizzato e, insieme, di inserire con facilità i tag di annotazione nei loro testi TEI.

Caratteristiche principali

Generazione normalizzata degli ID: crea ID XML coerenti nella forma pers-[cognome]-[iniziale del nome] (per es. pers-deteligny-c)
Analisi RDF: usa rdflib per estrarre le informazioni da diverse proprietà RDF (per es. rdfs:label, schema:name, viaf:mainHead)
Interfaccia a riga di comando: si esegue con un numero VIAF come unico argomento obbligatorio
Output dettagliato: accompagna l’XML finale con informazioni dettagliate sull’elaborazione

Esempio d’uso

python persNamer.py 314802260

Questo comando produce:

<person xml:id="pers-deteligny-c">
 <persName>Charles deTéligny</persName>
 <birth>1535</birth>
 <death>1572-08-24</death>
 <idno type="VIAF">314802260</idno>
</person>

<persName ref="#pers-deteligny-c">Charles deTéligny</persName>

Applicazioni nell’umanistica digitale

persNamer torna particolarmente utile per:

le edizioni critiche digitali che richiedono un controllo di autorità
i progetti di codifica TEI che trattano personaggi storici
le iniziative di linked data che collegano documenti a record di autorità
garantire la coerenza in grandi corpora TEI
insegnare il controllo di autorità nei corsi di umanistica digitale

Realizzazione

persNamer è scritto in Python e dipende da:

requests per le richieste HTTP
rdflib per l’analisi RDF
lxml per la gestione dell’XML

Il codice sorgente e la documentazione sono nel .

Spoglio bibliografico su larga scala con i modelli linguistici pre-addestrati

Thu, 07 Jul 2022 19:04:14 +0200

L’automazione è la chiave per abbattere i costi dei progetti di umanistica digitale. Finora, le operazioni ripetitive e tediose del lavoro editoriale in ambito accademico sono state svolte a caro prezzo da studiosi già oberati, oppure «appaltate» agli studenti. In questa sostengo che la maggior parte di queste incombenze ingrate non solo può, ma deve essere automatizzata. Automatizzare le operazioni editoriali riduce il costo complessivo dei progetti; e soprattutto permette agli studiosi delle regioni meno ricche di pubblicare documenti di valore in fretta e con poca spesa.

Nel ho mostrato, per esempio, come i modelli linguistici pre-addestrati possano sbrigare gran parte dell’etichettatura XML di un’edizione digitale.

Qui presento un secondo esempio: la bibliografia.

Il problema

Ricavare una banca dati bibliografica dai riferimenti citati in un articolo scientifico è cosa abbastanza semplice: si cerca in un catalogo come , si scarica il riferimento nel formato voluto, oppure lo si importa da una banca dati locale. Con uno o due articoli funziona. Oltre un certo numero di riferimenti, però, il compito diventa ingrato e divora tempo. Per rimediare esistono algoritmi di analisi come , ma scalarli non è facile. Quando ho usato anystyle per convertire gli oltre 150 saggi della nostra , gli errori si sono accumulati fino a diventare ingestibili: molte fonti non venivano riconosciute, i lunghi titoli dei libri della prima età moderna venivano scambiati per chissà che, e i documenti meno convenzionali – una pagina web, un video in rete – restavano lettera morta. Gli analizzatori funzionano bene a patto che l’autore osservi religiosamente uno stile noto, Chicago, Turabian o MLA che sia; ogni scarto dalla norma si paga in errori.

La soluzione

È qui che i modelli linguistici pre-addestrati tornano utili: colgono in un attimo lo schema di qualunque stile bibliografico , anche di uno inventato da voi, e bastano pochi esempi perché convertano correttamente masse di bibliografia formattata in una .

All’inizio del 2021 ho avuto la fortuna di accedere in anteprima a di OpenAI, un modello che traduce il linguaggio naturale in codice e viceversa. OpenAI gli attribuisce la padronanza di più di una dozzina di linguaggi di programmazione; e sebbene la sua API sia ancora in versione beta mentre scrivo, alimenta già applicazioni popolari come di GitHub.

Dopo qualche prova con l’API mi sono reso conto che se la cavava benissimo anche con un codice più modesto come BibTeX.

E infatti sono bastati quattro esempi nel prompt di input perché funzionasse in modo affidabile.

Prompt di input

References: Bayle, Ariane. “Patients exemplaires: la correspondance médicale de Fioravanti.” In Vulgariser la médecine. Du style médical en France et en Italie, edited by Andrea Carlino and Michel Jeanneret, 181–212. Geneva: Droz, 2009.

Berns, Andrew D. The Bible and Natural Philosophy in Renaissance Italy: Jewish and Christian Physicians in Search of Truth. Cambridge: Cambridge University Press, 2015.

Gabler, Hans Walter. “Theorizing the Digital Scholarly Edition.” Literature Compass 7, no. 2 (2010): 43–56. .

Findlen, Paula. Possessing Nature: Museums, Collecting, and Scientific Culture in Early Modern Italy. Berkeley: University of California Press, 1994.

@incollection{bayle2009,
 author = {Bayle, Ariane},
 booktitle = {Vulgariser la médecine. Du style médical en France et en Italie},
 title = {Patients exemplaires: la correspondance médicale de Fioravanti},
 editor = {Carlino, Andrea and Michel Jeanneret},
 year = {2009},
 address = {Geneva},
 publisher = {Droz},
 langid = {french}
}
@book{berns2015,
 title = {The Bible and Natural Philosophy in Renaissance Italy: Jewish and Christian Physicians in Search of Truth},
 author = {Berns, Andrew D.},
 address = {Cambridge},
 publisher = {Cambridge University Press},
 langid = {english},
 date = {2015}
}
@article{gabler2010,
 author = {Gabler, Hans Walter},
 title = {Theorizing the Digital Scholarly Edition},
 journal = {Literature Compass},
 volume = {7},
 number = {2},
 pages = {43-56},
 doi = {10.1111/j.1741-4113.2009.00675.x},
 langid = {english},
 year = {2010}
}
@book{findlen1994,
 title = {Possessing Nature: Museums, Collecting, and Scientific Culture in Early Modern Italy},
 author = {Findlen, Paula},
 address = {Berkeley},
 publisher = {University of California Press},
 langid = {english},
 date = {1994}
}

Risultati

I sono impressionanti: più di 2.000 riferimenti bibliografici convertiti nel giro di pochi giorni. Non solo il modello ha riprodotto fedelmente lo schema del prompt, ma ha aggiunto, a ragion veduta, tipi di voce e di campo che nel prompt non c’erano: GPT-3, insomma, parla BibTeX correntemente. E, cosa forse più sorprendente per un modello addestrato per lo più sull’inglese, ha riconosciuto tutte le lingue (russo, francese, italiano, latino, greco, tedesco, spagnolo…) aggiungendo ogni volta il campo langid giusto.

Nota

GPT-3 ha per ora dimensioni limitate di input e di output: elabora al massimo 2048 token. Quando questo limite verrà rimosso, lo stesso lavoro richiederà probabilmente un’ora, o meno.

Un po’ a sorpresa, GPT-3 ha aggiunto anche informazioni che nei riferimenti originali non c’erano.

Baillot, Anne, and Anna Busch. “Editing for Man and Machine.” In Users of Scholarly Editions: Editorial Anticipations of Reading, Studying and Consulting, Vol. 13. Variants (Journal of the European Society for Textual Scholarship). Leicester, 2015.

In questo riferimento, per esempio, ha inserito il link permanente al repository ad accesso aperto ( ) dove l’articolo si può leggere, compresi i campi ad hoc HAL_ID e HAL_VERSION propri di HAL:

@inproceedings{baillot2015,
 title = {Editing for Man and Machine},
 author = {Baillot, Anne and Busch, Anna},
 year = 2015,
 booktitle = {Users of Scholarly Editions: Editorial Anticipations of Reading, Studying and Consulting},
 address = {Leicester},
 series = {Variants (Journal of the European Society for Textual Scholarship)},
 volume = 13,
 editor = {Bruhn, Siglinde and Schreiber, Manfred},
 langid = {english},
 hal_id = {halshs-01233380},
 hal_version = {v1}
}

Aggiunte del genere indicano che GPT-3 non si limita ad analizzare il riferimento bibliografico: lo completa con quello che ha imparato in origine. Sarebbe interessante, a questo proposito, vedere se si comporta allo stesso modo con riferimenti posteriori al suo addestramento…

Limiti

GPT-3 non è però infallibile, e va sorvegliato da un essere umano. Uno dei suoi limiti noti è l’ : ogni tanto inventa, e si lascia andare a supposizioni improbabili.

Nel mio esperimento, l’incoerenza di GPT-3 si è manifestata quando ha cambiato di sua iniziativa il cognome di un autore da «Ruscelli» in «Ruscello». A rigore non è un errore: nell’Italia della prima età moderna i cognomi si usavano indifferentemente al plurale e al singolare. La convenzione odierna, però, vuole che il cognome resti com’è, plurale o singolare che sia: nessuno oggi chiamerebbe Machiavelli «Machiavello», così come si dice Rossello e non Rosselli. GPT-3 ha ignorato la convenzione per difetto di coscienza cronologica? O ha tirato a indovinare sulla scorta dei cognomi vicini, che in questa parte della bibliografia sono per combinazione tutti al singolare (Bariletto, Cesano, Rossello)? Chi lo sa.

@book{rossello1565,
 title = {Della summa de’ secreti universali},
 author = {Rossello, Timoteo},
 address = {Venice},
 publisher = {Giovanni Bariletto},
 langid = {italian},
 date = {1565}
}
@book{ruscello1559,
 title = {La seconda parte de’ secreti del Reverendo Donno Alessio Piemontese},
 author = {Ruscello, Girolamo},
 address = {Pesaro},
 publisher = {Bartolomeo Cesano},
 langid = {italian},
 date = {1559}
}

Conclusione

Scritti nell’arco di quattro anni di intensa collaborazione, gli oltre 150 saggi non solo forniscono informazioni essenziali sul manoscritto che abbiamo curato e tradotto, ma racchiudono anche un patrimonio bibliografico prezioso.

Raccogliere quei riferimenti in una banca dati permette ai curatori di cambiare stile bibliografico in un batter d’occhio, e di presentare l’informazione come meglio credono. La banca dati dice inoltre molto sull’edizione e sul progetto che l’ha resa possibile, e apre agli studiosi nuove prospettive d’analisi. E la si può completare con grande precisione e in tempi record.

Qualche errore, certo, può insinuarsi, soprattutto per la propensione di GPT-3 ad allucinare. Ma le prossime generazioni di modelli linguistici pre-addestrati attenueranno il problema.

Avviso | Pubblicare le notizie che ci hanno fatto moderni (1537—1743)

Sun, 12 Dec 2021 00:00:00 +0000

L’obiettivo principale del progetto Avviso è digitalizzare, conservare, catalogare, curare, contestualizzare e diffondere i 35.000 notiziari manoscritti della prima età moderna – gli avvisi – che facevano parte della collezione medicea e sono oggi conservati all’Archivio di Stato di Firenze. La catalogazione, la digitalizzazione e la diffusione di circa 35.000 avvisi, i notiziari manoscritti della prima età moderna, passano per la piattaforma Medici Interactive Archive del Medici Archive Project.

Edizione efficiente

Sun, 12 Dec 2021 00:00:00 +0000

Le edizioni critiche digitali costano. Trascrivere, tradurre, annotare: un lavoro da personale altamente qualificato, che rappresenta migliaia di ore e richiede finanziamenti ingenti, oltre a un sostegno istituzionale di lungo periodo.

Per certi versi è una fortuna che i progetti più in vista dell’umanistica digitale riescano a raccogliere le somme enormi di cui hanno bisogno.

Ma una dipendenza così stretta dalla munificenza di fondazioni facoltose, università e agenzie governative, unita al bisogno prolungato di tante risorse umane, non è un modello economico su cui costruire il futuro. Se sempre più studiosi possono permettersi edizioni digitali ambiziose di fonti primarie, la pratica resta il privilegio di pochi paesi ricchi, e ne rafforza l’egemonia culturale.

Perché i documenti storici di tutto il mondo diventino accessibili a un pubblico più vasto, il costo delle edizioni critiche digitali dovrebbe scendere di parecchi ordini di grandezza .

In questa serie di post passo in rassegna gli approcci e i mattoni tecnologici con cui gli studiosi di ogni paese possono pubblicare fonti primarie più in fretta e con una spesa minima.

Valuterò in particolare tecnologie come l’apprendimento automatico, la blockchain e l’archiviazione decentralizzata.

Automatizzare la marcatura nelle edizioni critiche digitali

Mon, 22 Nov 2021 18:15:00 +0000

Introduzione

Come si producono edizioni critiche digitali senza svenarsi? Con questo post apro una serie dedicata all’edizione efficiente; qui valuto quale parte possano avere i modelli linguistici pre-addestrati nell’automazione delle operazioni editoriali, a cominciare dalla marcatura semantica.

Indice dei Contenuti

Il problema

Un lavoro d’amore

Quando c’è di mezzo l’amore non si bada a spese… o così, almeno, vuole il proverbio. E vale a maggior ragione per le edizioni critiche digitali: trascrivere, tradurre e annotare significa migliaia di ore di lavoro, che in un caso come quello di sono state prestate da centinaia di collaboratori di altissima qualificazione.

Per certi versi è una fortuna che i progetti più in vista dell’umanistica digitale riescano a raccogliere le somme enormi di cui hanno bisogno. Ma una dipendenza così stretta dalla munificenza di fondazioni facoltose, università e agenzie governative, unita al bisogno prolungato di tante risorse umane, non è un modello economico su cui costruire il futuro.

Anzi: se vogliamo che studiosi di ogni parte del mondo rendano i documenti storici accessibili a un pubblico più vasto, il costo delle edizioni critiche digitali dovrebbe scendere di parecchi ordini di grandezza .

Una soglia alta

Paradossalmente, la soluzione potrebbe venire proprio dai progetti più affamati di manodopera, come , che costituiscono un prezioso insieme di addestramento per automatizzare le operazioni più ingrate e ripetitive dell’edizione digitale, a cominciare dalla marcatura.

Non che la marcatura sia cosa da poco. Al contrario: la marcatura è ormai la componente irrinunciabile di ogni progetto digitale che si rispetti. Normalizzata dalla , permette di registrare del documento, e del testo che esso trasmette, quanti più aspetti si vogliano: struttura, note marginali, cancellature, varianti, tipo di carta, macchie, grafia… tutto quello che vi viene in mente.

L’esempio che segue, tratto da , mostra come la marcatura arricchisca il testo di informazioni ulteriori (categoria, struttura, campi semantici, cancellature e via dicendo), dando in definitiva alle edizioni digitali un vantaggio netto sui loro antenati di carta.

Testo semplice Marcatura XML

Testo semplice	Marcatura XML
`Pour rompre grenades et donner violence aux artifices de foeu Mects parmy la pouldre et la sixiesme partye dicelle de vif argent`	`<div id="p008r_2" categories="arms and armor"> <head>Pour rompre <wp>grenades</wp> et donner<lb/> violence aux <wp>artifices de foeu</wp></head> <ab>Mects parmy la <m>pouldre</m> <del><ms>six fois autant</ms> de <m>vif argent</m></del><lb/> <del>et</del> <ms>la sixiesme partye</ms> dicelle de <m>vif argent</m></ab> </div>`

Pour rompre grenades et donner
violence aux artifices de foeu

Mects parmy la pouldre et la sixiesme
partye dicelle de vif argent

<div id="p008r_2" categories="arms and armor">
<head>Pour rompre <wp>grenades</wp> et donner<lb/>
violence aux <wp>artifices de foeu</wp></head>
<ab>Mects parmy la <m>pouldre</m>
<del><ms>six fois autant</ms> de
<m>vif argent</m></del><lb/>
<del>et</del> <ms>la sixiesme partye</ms>
 dicelle de <m>vif argent</m></ab>
</div>

Informazioni preziose non soltanto a fini di conservazione, ma anche – come ho avuto modo di mostrare altrove – per la sintesi e l’analisi. Il guaio è che annotare in questo modo costa un tempo enorme, tanto più che lo stesso testo deve spesso esistere in più vesti: come traduzione, come trascrizione, come versione modernizzata e così via.

La soluzione

I transformer: la via più breve all’automazione?

Nel 2020 ha presentato in pompa magna la sua nuova famiglia di modelli linguistici generalisti su larga scala, GPT-3, sigla di «Generative Pre-trained Transformer 3». I transformer sono una svolta recente dell’intelligenza artificiale: imparano compiti nuovi con una rapidità sconcertante, semplicemente leggendo un prompt e guardando un pugno di esempi; e possono ricevere un addestramento supplementare su un insieme di dati ad hoc (il cosiddetto fine-tuning), che ne migliora latenza e precisione. Per questo si dice che GPT-3 e i transformer analoghi sono .

OpenAI dichiara per GPT-3 la cifra record di 175 miliardi di parametri e un addestramento su oltre 570 GB di testo, in massima parte documenti in inglese presumibilmente raccolti da . Per le sole dimensioni, GPT-3 ha fissato un nuovo metro di paragone nel settore: esegue fin da subito i compiti più diversi con un realismo che mette a disagio. Scrive plausibili, nelle chat, , , traduce documenti, spiega il gergo, e via dicendo.

Avendo accesso in anteprima all’API di OpenAI dal maggio 2021, ho potuto mettere alla prova il modello su una serie di compiti che passano per difficili: tradurre in inglese poesia francese e testi neolatini, spiegare analogie, perfino semplificare il quarto libro della Fondazione della metafisica dei costumi di Kant per un bambino di sette anni (con esiti, va detto, poco convincenti).

Codex

Uno degli ultimi sviluppi di GPT-3 riguarda i linguaggi di programmazione. Il modello, battezzato Codex, traduce il linguaggio naturale in linguaggio informatico e viceversa. Se cerco, poniamo, un’espressione regolare che «trovi soltanto le parole che iniziano con la maiuscola», GPT-3 me la restituisce subito, e funzionante: [A-Z]+\w+.

Secondo OpenAI, Codex sa lavorare con una dozzina di linguaggi, fra cui Python, JavaScript, Go, Perl, PHP, Ruby e Swift. Convertendo senza attriti lo pseudocodice in codice, permette di concentrarsi non sulla sintassi pignola di un linguaggio, ma sui passaggi logici e sulle strategie con cui un’applicazione risolve un problema.

Oltre OpenAI

OpenAI, si capisce, non è sola in campo. Come si è detto, nel 2021 la Beijing Academy of Artificial Intelligence ha annunciato un modello ancora più grande e più capace, Wu Dao 2. Nvidia e Microsoft hanno unito le forze per produrre Megatron-Turing NLG 530B, un nome che dice tutto. Start-up più piccole come e offrono anch’esse API al pubblico, e meritano una menzione le iniziative open source come . Il panorama, si sa, cambia in fretta: per seguire le novità del settore, tenete d’occhio .

Gli esperimenti

Nota

L’obiettivo di questi esperimenti è individuare la via più economica verso un’automazione affidabile delle operazioni editoriali. Si potrebbe obiettare che alcune di esse si prestano anche ad algoritmi di apprendimento supervisionato: è un’ipotesi che esploreremo in un prossimo post.

Un transformer come GPT-3 può imparare ad annotare, poniamo, un manoscritto tecnico-scientifico del Cinquecento?

Esperimento 1 – Categorizzazione dei testi

Partiamo da qualcosa di relativamente semplice. Da bravo «few-shot learner», GPT-3 dovrebbe capire in fretta secondo quali criteri il nostro gruppo di lavoro ha classificato le voci del Ms. Fr. 640.

Prompt engineering

Per addestrarlo mi sono servito di un prompt ridotto all’osso e di quattro brevi voci in testo semplice, scelte come esempi: fra queste, una di «medicina», una di «armi e armature» e una di «pittura».

Verifica

Ho poi incollato un altro passo, estraneo alla sequenza iniziale:

Working neatly
Never put down, if you can, two colors one on top of the other.
But next, having made your design carefully, keep the place of shadows for them alone,
& also separately that of lights & highlights, without layering one color all over & then highlighting or else shading on it.
And in this way, you further your work, economize your colors & work neatly.
Which is the reason that, the colors not being muddled nor mixed together, they do not die & you soften the colors better, since they are not so thick.

Il risultato è perfettamente in linea con il contenuto:

<categories="painting">

Se proviamo con una voce di una categoria che non figurava nemmeno fra i testi scelti per l’addestramento di GPT-3, la risposta sorprende.

<categories="jewelry">

Risultato

La categoria «jewelry» (gioielli) non esiste nella nostra edizione del Ms. Fr. 640: il gruppo di lavoro quella, più ampia, di «Stones» (pietre). L’intuizione di GPT-3 è però buona, e lascia pensare che con un po’ di addestramento in più saprebbe categorizzare qualunque voce del Ms. Fr. 640, e forse anche quelle di testi tecnici cinquecenteschi affini.

Esperimento 2 – Marcatura semantica

Alziamo l’asticella. Se un transformer come GPT-3 impara a categorizzare i testi secondo criteri editoriali specifici, saprà anche riconoscerne, almeno in parte, la marcatura?

Nota

Secrets of Craft and Nature adotta una di etichette semantiche e strutturali. Purtroppo GPT-3 non elabora immagini, a differenza di altri progetti come . È probabile che le prossime versioni di GPT acquisiscano questa capacità, indispensabile per riconoscere la maggior parte degli aspetti strutturali e materiali di un documento. Lasceremo dunque da parte quei tag e ci concentreremo sulla marcatura che non richiede il riconoscimento delle immagini.

Prompt engineering

I tag semantici segnalano animali, piante, toponimi, percezioni sensoriali e altro ancora. Nel prompt di addestramento ho raccolto qualche esempio tratto dall’edizione:

<!--Input prompt-->
The following is a list of words and their corresponding semantic tags

cannons: <wp>cannons</wp>
powder: <m>powder</m>
flasks: <tl>flasks</tl>
wooden: <m>wooden</m>
iron: <m>iron</m>
parchment: <m>parchment</m>
goats: <al>goats</al>
lambs: <al>lambs</al>
leather: <m>leather</m>
earth: <m>earth</m>
fine fatty earth: <m>fine fatty earth</m>
Venice: <pl>Venice</pl>
Flemish: <pl>Flemish</pl>
almond: <pa>almond</pa>
almond oil: <m><pa>almond</pa> oil</m>
walnuts skin: <m><pa>walnuts</pa> skin</m>
molten lead: <m>molten lead</m>
today: <tmp>today</tmp>
In the past: <tmp>In the past</tmp>
Clockmakers: <pro>Clockmakers</pro>
red copper: <m>red copper</m>
crucible: <tl>crucible</tl>
bellows: <tl>bellows</tl>
charcoal: <m>charcoal</m>
founders: <pro>founders</pro>

Verifica

Proviamo con il modello Davinci-codex qualche parola facile: Apothecary, smoke, glassmakers, latten e snake. Le risposte arrivano all’istante e sono impeccabili:

<!--Output-->
Apothecary: <pro>Apothecary</pro>
smoke: <m>smoke<m>
glassmakers: <pro>glassmakers</pro>
latten: <m>latten</m>
snake: <al>snake</al>

Una prova più severa richiede parole composte – copper plates, walnut oil, wood block – per vedere se GPT-3 se la cava con i tag annidati.

<!--Output-->
copper plates: <m>copper plates</m>
walnut oil: <m><pa>walnut</pa> oil</m>
wood block: <m>wood block</m>

Qui i risultati sono in chiaroscuro: Davinci-codex ha etichettato correttamente solo walnut oil, senza cogliere i tag tl e m annidati in copper plates e wood block. Ma, come mostra la prova successiva, basta un prompt di addestramento migliore per attenuare questi errori. Aggiunti altri cinque esempi di tag annidati, Davinci-codex ha restituito un risultato quasi perfetto, con un solo errore (oil paintbrushes):

<!--Output-->
cannon powder: <m><wp>cannon</wp> powder</m>
arquebus powder: <m><wp>arquebus</wp> powder</m>
oil paintbrushes: <m><al>oil</al> paintbrushes</m>
sheep footbones: <m><al>sheep</al> footbones</m>
bronze mortar: <tl><m>bronze</m> mortar</tl>

Conclusione

Va ricordato che queste prove sono state condotte su frammenti di testo molto brevi. Sospetto che, dando più contesto negli esempi e nel prompt, i modelli GPT-3 farebbero ancora meglio; e un fine-tuning su insiemi di dati ad hoc migliorerebbe senza dubbio la precisione dell’etichettatura.
Se per dimostrare l’affidabilità dei modelli linguistici pre-addestrati occorreranno ancora esperimenti su scala più ampia, si può nondimeno concludere che questo approccio permette a chi cura un’edizione di automatizzare parecchie operazioni di annotazione in pochi passaggi, con un risparmio potenzialmente enorme di tempo e di denaro.

Visualizzare i manoscritti 2 (aggiornamento)

Sat, 20 Nov 2021 16:00:00 +0000

Come promesso, ecco la nuova versione della treemap interattiva presentata in un : questa volta con due modalità di visualizzazione.

Nota

Per una resa migliore, impostate la pagina in modalità chiara (cliccate sull’icona della luna in alto a destra).

Group folios by category

Un navigatore visivo per l’archivio

Sun, 20 Jun 2021 16:00:00 +0000

Il problema

Le edizioni digitali vivono di un paradosso: rendono accessibili a un pubblico più ampio documenti reconditi, ma la perdita di stimoli sensoriali che accompagna la loro smaterializzazione tende a disorientare i lettori, e persino a distoglierli dal contenuto. Muoversi in vasti depositi di documenti diventa macchinoso, quando non intimidatorio; e non solo per chi è a digiuno di ricerca d’archivio, ma anche per i lettori con disabilità cognitive.

La soluzione

È qui che i metadati archivistici ci vengono in aiuto. Con essi si possono costruire astrazioni visive interattive che offrono al lettore uno stimolo sensoriale alternativo, a vantaggio insieme dell’ergonomia e dell’accessibilità. Per rendere l’archivio navigabile con gli occhi basta una treemap, o qualunque altro diagramma che scomponga con efficacia dati gerarchici.

L’esperimento

Il mio primo esperimento adatta il per D3.js, aggiungendovi i collegamenti ipertestuali. Rappresenta il manoscritto BnF Ms. Fr. 640, i suoi fogli e le voci di ciascun foglio; i colori indicano la categoria dominante, e passando il cursore su una voce compaiono altri dati, compreso il collegamento al manoscritto.
La treemap diventa così un indice visivo interattivo, che dà al lettore, in un colpo d’occhio, una panoramica non solo dei contenuti del manoscritto ma anche delle dimensioni di ciascun foglio e di ciascuna voce.
~~Nei prossimi mesi continuerò a sperimentare con questa idea, provando altri diagrammi e altre gerarchie… A presto!~~ Una nuova versione della treemap è .

Nota

Per una resa migliore, impostate la pagina in modalità chiara (cliccate sull’icona della luna in alto a destra).

Click any cell to zoom in, or the top to zoom out.

L’archivio a colpo d’occhio

Mon, 24 May 2021 16:00:00 +0000

Il problema

Gli archivi storici possono essere di un disordine che scoraggia. Il Mediceo del Principato dell’ ne è l’esempio perfetto: solo una piccola parte del fondo è inventariata, e molti documenti sono sparsi senza ragione apparente in più di 6.500 volumi. Come se non bastasse, l’archivio consente di consultare soltanto un numero limitato di volumi – o filze, come si dice a Firenze. In tempi normali il limite è di 4 filze al giorno; in tempo di pandemia è sceso a 4 ogni due settimane. In mancanza di inventari dettagliati, la mole dell’archivio obbliga chi vi fa ricerca a escogitare strategie per arrivare in fretta ai documenti che cerca.

La soluzione

C’è chi si affida al caso, e chi prova a fare congetture ragionate su cronologia, destinatari, autori, provenienza del fondo, lingua e via dicendo. Ma guardare tutte queste variabili insieme può far emergere regolarità inattese nella struttura dell’archivio e affinare le congetture. La mia esperienza dice che i metadati che i ricercatori raccolgono di solito in un foglio di calcolo, una volta messi in grafico, aiutano sensibilmente a orientarsi in archivio: si sa dove si è, e che cosa si sta cercando.

L’esperimento

La mia ricerca attuale verte sulla corrispondenza di una spia del Cinquecento. Le sue lettere sono disperse in centinaia di filze: scritte sotto identità diverse, a destinatari diversi e talvolta inaspettati, da luoghi diversi, e così via. Per individuare le filze in cui è più probabile trovarle, ho messo in piedi una dashboard, cioè un’applicazione web di visualizzazione interattiva dei dati ( ) che collega informazioni di ogni genere – geografiche, cronologiche – a un diagramma gerarchico ( ) del fondo archivistico. A colpo d’occhio la dashboard mi dice che cosa è già stato trovato, quanto pesa sul totale, e mi dà un’idea approssimativa di dove potrei cercare lettere nuove. Cliccando su una variabile, poi, tutti i diagrammi si aggiornano e mostrano le correlazioni corrispondenti.

Prossimi passi

Ma forse la cosa più importante è che la dashboard può trasformarsi in un indice visivo. Quando l’edizione critica delle lettere sarà online, farà da porta d’ingresso alternativa, da cui i lettori potranno esplorare i dati. Per ragioni di riservatezza al momento posso mostrare soltanto una schermata parzialmente oscurata, ma l’anno prossimo pubblicherò la dashboard completa; nel frattempo sarà presto disponibile un prototipo. A presto!

Making & Knowing Project

Sun, 27 Dec 2020 00:00:00 +0000

Il , fondato nel 2014 da Pamela H. Smith e animato da centinaia di collaboratori, è un’iniziativa di ricerca e di didattica del della Columbia University.

Vi ho preso parte come ricercatore post-dottorato, lavorando fra l’altro all’ del BnF Ms. Fr. 640: un manoscritto francese del Cinquecento, unico nel suo genere, che apre uno spiraglio di prima mano sul fare e sui materiali di un’epoca in cui gli artisti erano scienziati.

L’edizione digitale mette liberamente a disposizione una gran quantità di dati sul suo . Nel corso del prossimo anno intendo pubblicare una serie di post sull’edizione e sui suoi dati, per mostrare con quanta facilità si possa scaricare e analizzare il testo con Python o R. A presto!

Visualizzare la marcatura semantica del BnF Ms. Fr. 640

Sun, 20 Dec 2020 18:15:00 +0000

Panoramica

Le edizioni critiche ricche di dati contengono annotazioni editoriali preziose, che si possono estrarre, analizzare e visualizzare per gli scopi più diversi. È il caso di , uscita nel 2020, che mette a disposizione il proprio file di metadati sul suo repository GitHub. In questo post mostro come raccogliere tutte quelle variabili in una matrice di correlazione e visualizzarle in più modi.

I dati

Il Making and Knowing Project produce un foglio di calcolo con informazioni aggiornate sul contenuto del manoscritto: entry_metadata.csv. Il file si scarica dal del Making & Knowing; in alternativa, si possono generare file .csv su misura, con più marcatura, grazie all’eccellente di Matthew Kumar, una versione Python del BnF Ms. Fr. 640.

Preparare Python

Useremo Pandas per la manipolazione dei dati, Matplotlib e seaborn per le heatmap, e infine NetworkX per costruire reti basate sulle correlazioni.
Con variabili di questo tipo eviteremo il metodo di Pearson e useremo invece il metodo 𝜙𝐾. Vi conviene su questo metodo di correlazione e su PhiK, la libreria corrispondente.

#install packages
pip install phik

# import modules
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns
import networkx as nx

Preparare i dati

Per prima cosa scarichiamo dal dell’edizione, nella cartella metadata, l’ultimo file di metadati. Terremo solo le colonne che ci servono. Per questa dimostrazione prendo tutti i tag semantici della traduzione inglese tl, ma potete scegliere anche quelli della trascrizione francese tc o della versione normalizzata tcn. I dati arrivano come valori separati da punto e virgola, e dobbiamo farli contare a Python: useremo il metodo stack-unstack con l’espressione regolare [^;\s][^\;]*[^;\s]*. Per rendere la matrice più leggibile rinominiamo ogni colonna. Se avete fretta potete saltare questo passaggio; tenete solo a mente che a questo punto il nostro dataframe si chiama tagsrn.

# load the edition's metadata
df = pd.read_csv('entry_metadata.csv')

# select the tags you want to correlate
dftags = df[['al_tl', 'bp_tl', 'cn_tl', 'df_tl', 'env_tl', 'm_tl', 'md_tl', 'ms_tl', 'mu_tl', 'pa_tl', 'pl_tl', 'pn_tl', 'pro_tl', 'sn_tl', 'tl_tl', 'tmp_tl', 'wp_tl', 'de_tl', 'el_tl', 'it_tl', 'la_tl', 'oc_tl', 'po_tl']]

# count comma separated values
tagcount = dftags.stack(dropna=False).str.count(r'[^;\s][^\;]*[^;\s]*').unstack()

# rename columns
tagsrn = tagcount.rename(columns={'al_tl': 'animals', 'bp_tl': 'body parts', 'cn_tl': 'currency', 'df_tl': 'definitions', 'env_tl': 'environment', 'm_tl': 'material', 'md_tl': 'medical', 'ms_tl': 'measurement', 'mu_tl': 'music', 'pa_tl': 'plant', 'pl_tl': 'toponym', 'pn_tl': 'person', 'pro_tl': 'profession', 'sn_tl': 'sensory', 'tl_tl': 'tool', 'tmp_tl': 'temporal', 'wp_tl': 'weapons', 'de_tl': 'German', 'el_tl': 'Greek', 'it_tl': 'Italian', 'la_tl': 'Italian', 'oc_tl': 'Occitan', 'po_tl': 'Poitevin'})

Correlare

Pulito il dataframe, si passa a calcolare i coefficienti di correlazione fra le variabili. A questo punto è essenziale conoscere i propri dati e scegliere il metodo di correlazione più adatto; il pacchetto pandas-profiling è di grande aiuto.

# calculate correlation coefficient with the phi k method
cortag = tagsrn.phik_matrix()

cortag è la nostra matrice di correlazione. Possiamo ora provare vari tipi di visualizzazione.

Visualizzare

La prima cosa da provare è visualizzarla come matrice a colori, con il di seaborn.

Heatmap di correlazione

f, ax = plt.subplots(figsize=(16, 14))
ax = sns.heatmap(cortag, linewidths=.03, vmin=0, cmap="Oranges", square=True)

Se conoscete bene il testo, vedrete subito che la heatmap torna. I nomi di persona, per esempio, sono fortemente correlati al latino: era consuetudine, soprattutto fra gli umanisti del Cinquecento, latinizzarli.

Qualcuno obietterà che la heatmap non fa che dire l’ovvio. Non ha tutti i torti; e a prima vista i tag medici sembrano dargli ragione, dato che si correlano, com’era prevedibile, con parti del corpo, misure e piante.

Ma a leggere la heatmap con più attenzione, riga per riga, saltano fuori correlazioni interessanti e inattese. Che i tag medici siano correlati con le parole italiane e latine, per esempio, dice qualcosa sull’origine delle ricette mediche del Ms. Fr. 640. Allo stesso modo, la correlazione fra professioni, definizioni e misure mostra quanto l’identità professionale strutturi il discorso tecnico del Cinquecento.

Clustermap di correlazione

Le heatmap servono in fase «esplorativa», ma al vostro pubblico possono sembrare confuse, soprattutto se state discutendo – o ancora cercando – raggruppamenti semantici precisi nel manoscritto. Il modulo clustermap di seaborn può dare risultati interessanti.

clustermap = sns.clustermap(cortag, figsize=(12, 13), dendrogram_ratio=(.1, .2), vmin=0, cmap="Oranges", cbar_pos=(-.06, .12, .03, .68))

Oltre a somigliare a un insetto pixelato (sì, la parola è nell’OED), la clustermap separa nettamente i tag isolati (in alto e a sinistra) da quelli più interconnessi. Si distinguono anche raggruppamenti isolati, come musica e poitevino (chi l’avrebbe detto!), da altri più centrali come misure, materiali, definizioni e armi. Le professioni sono più interconnesse, ma non appartengono, almeno in questa matrice, a un raggruppamento particolare.

Rete di correlazione

Se vogliamo condensare ancora di più le correlazioni della matrice, i grafi offrono una soluzione elegante, soprattutto quando si tratta di comunicare il contenuto del manoscritto.
Occorre trasformare la matrice in una lista di archi e nodi, e fissare una soglia per escludere dal grafo le correlazioni più deboli.

# transform the data
links = cortag.stack().reset_index()
links.columns = ['var1', 'var2','value']

# threshold 
links_filtered = links.loc[(links['value'] > .6) & (links['var1'] != links['var2'])]
links_filtered

# create edges
G = nx.from_pandas_edgelist(links_filtered, 'var1', 'var2')

# draw network using Kamada & Kawai's algorithm 
plt.figure(3,figsize = (12,12))
nx.draw_kamada_kawai(G, with_labels = True, node_color = 'red', node_size = 400, edge_color = 'black', linewidths = 1, font_size = 14)

Se archi e nodi sono troppi, si può sempre ritoccare la soglia per un risultato più pulito. Altrimenti si esporta il grafo per lavorarci in Gephi, con la funzione .write_gexf().

nx.write_gexf(G, 'graph.gexf')

Il risultato lo vedete in apertura di questo post.

Aggiornamento: rete circolare pesata

Cercavo un modo di rappresentare le matrici di correlazione come reti pesate, e ho trovato questo approccio interessante , che adatto qui al nostro insieme di dati.

# create graph weighted by correlation coefficients (unfiltered)
Gx = nx.from_pandas_edgelist(links, 'var1', 'var2', edge_attr=['value'])

# determine a threshold to remove some edges
threshold = 0.4

# list to store edges to remove
remove = []

# loop through edges in Gx and find correlations which are below the threshold
for var1, var2 in Gx.edges():
 corr = Gx[var1][var2]['value']
 #add to remove node list if abs(corr) < threshold
 if abs(corr) < threshold:
 remove.append((var1, var2))

# remove edges contained in the remove list
Gx.remove_edges_from(remove)

print(str(len(remove)) + ' edges removed')

Tolti alcuni archi, possiamo stabilirne colore e spessore.

# determine the colors of edges
def assign_colour(correlation):
 if correlation <= 0.8:
 return '#ff872c' # orange
 else:
 return '#f11d28' # red


def assign_thickness(correlation, benchmark_thickness=3, scaling_factor=3):
 return benchmark_thickness * abs(correlation)**scaling_factor


def assign_node_size(degree, scaling_factor=50):
 return degree * scaling_factor

Diamo inoltre ai nodi una dimensione proporzionale al numero di connessioni.

# assign node size depending on number of connections (degree)
node_size = []
for key, value in dict(Gx.degree).items():
 node_size.append(assign_node_size(value))

Il risultato è un grafo pesato che ammette più nodi e molti più archi, restando leggibile e informativo.

La corrispondenza segreta di Filippo Cavriana, 1568—1589.

Fri, 27 Dec 2019 00:00:00 +0000

Le lettere segrete di Filippo Cavriana sono una testimonianza senza pari sulle guerre di religione francesi: per più di vent’anni seguono gli intrighi, le battaglie, i negoziati e le congiure che scandivano la vita alla corte di Francia, e non solo.

Conservate all’ , le lettere sono in gran parte disperse in centinaia di fasci non inventariati – le filze, come si chiamano a Firenze. Negli ultimi anni ne ho scoperte decine di nuove, ma questo genere di ricerca d’archivio si fa sempre più arduo: la distanza da Firenze, il degrado di alcuni servizi pubblici in Italia e la pandemia di Covid-19 concorrono a fare di un progetto di pubblicazione come questo un’impresa lunga e incerta.

Pubblicare fonti primarie dovrebbe restare, nonostante tutto, parte del mestiere dello storico. La forma di queste pubblicazioni, però, dovrebbe probabilmente cambiare: non solo adattarsi alle condizioni che ho appena descritto, ma rispecchiare meglio la natura incrementale di questa ricerca, e permettere a qualcun altro di continuarla.

Da qui l’idea di un nuovo tipo di pubblicazione digitale: scalabile, sostenibile, affidabile, indipendente dalla piattaforma e, potenzialmente, collaborativa.

L’edizione è ora in rete: . Raccoglie le lettere trascritte finora, dagli Archivi di Stato di Firenze e di Mantova e dalla BnF, e cresce man mano che ne affiorano di nuove. Le ragioni della sua architettura le ho spiegate in .