Humanidades Digitais |

tei-mcp v0.3: codificar em TEI sem reescrever a fonte

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

Quando , o objetivo era impedir os assistentes de IA de alucinar marcação TEI. A ancoragem no esquema resolveu parte do problema: com acesso direto, por ferramentas, à especificação P5, o modelo já não tem de adivinhar o que um elemento significa nem que atributos aceita. O resultado valida.

Mas a alucinação tem duas faces na codificação TEI, e o esquema só apanha uma delas. Validar contra a especificação diz-nos que a marcação está bem formada. Nada diz sobre o texto que essa marcação envolve. E é aí – no próprio texto – que vivem as alucinações mais nocivas. A composição por intervalos bloqueados, a grande novidade da v0.3, foi concebida especificamente para as impedir.

Lista de Conteúdos

A alucinação que o esquema não apanha

Peça-se a um modelo que codifique uma carta francesa do século XVI e receber-se-á muitas vezes um documento TEI de aspeto impecável. O cabeçalho está preenchido, as etiquetas <persName> estão bem colocadas, o <dateline> está bem formado. Passe-se pelo validate_document e ele passa.

Compare-se depois o corpo com a fonte.

mesme passou a même. Uma vírgula mudou de sítio. luy foi silenciosamente modernizado em lui. Uma oração de leitura difícil no manuscrito foi «corrigida» para algo mais limpo. Nenhuma destas alterações foi pedida. Nenhuma é assinalada. O documento é válido segundo o esquema e está discretamente errado.

Para um fluxo de trabalho de arquivo – em que o texto codificado se torna o registo permanente de que dependem leitores, índices de pesquisa e citações – é este o modo de falha que mais importa. Uma etiqueta malformada é um incómodo. Uma grafia modernizada de que ninguém dá conta durante cinco anos é uma corrupção.

A composição por intervalos bloqueados

A nova versão (v0.3) traz um mecanismo de prevenção de alucinações apontado diretamente a este modo de falha. O objetivo de design é tornar as alucinações no corpo do texto impossíveis por construção, e não apenas improváveis.

A ideia é simples: o modelo nunca escreve texto de corpo.

Em vez disso, o fluxo de trabalho é o seguinte:

O modelo chama get_source("letter_001") e recebe o texto simples da fonte como cadeia imutável.
Para cada etiqueta que queira aplicar, chama tag_span("letter_001", start, end, element_path, attrs) – registando um elemento TEI sobre um intervalo de caracteres da fonte.
Quando termina, chama compose("letter_001"). O servidor intercala as etiquetas registadas com o texto simples original, gera o TEI final e verifica depois, byte a byte, que o conteúdo textual plano do documento gerado é igual à fonte.

Se os bytes coincidem, o documento é devolvido. Se não coincidem – se as etiquetas do modelo implicarem de algum modo um corpo que difere da fonte num único caráter que seja –, compose() lança uma exceção em vez de devolver um documento corrompido.

Não há caminho, neste fluxo de trabalho, em que o modelo produza um documento TEI cujo corpo difira da fonte. O invariante é mecânico, não comportamental. Não é preciso confiar que o modelo não alucina; basta confiar numa comparação == entre duas cadeias de bytes.

O que isto é, e o que não é

A composição por intervalos bloqueados é complementar da ancoragem no esquema; não a substitui. As ferramentas de ancoragem no esquema (validate_document, lookup_element, valid_children e as restantes das dezasseis originais) ajudam o modelo a produzir TEI válida. A composição por intervalos bloqueados garante que o corpo do texto dentro dessa TEI é fiel à fonte. Um fluxo de codificação que se possa pôr em produção tem de satisfazer os dois eixos, e agora ambos ficam cobertos por um único servidor.

Também não é uma varinha mágica para tudo. compose() ainda não verifica se as etiquetas registadas são admissíveis segundo uma personalização ODD carregada – fica para uma próxima versão. As etiquetas registadas vivem na memória do processo e não sobrevivem a um reinício. E os ficheiros-fonte têm de ser legíveis a partir de onde quer que o servidor corra. Tudo isto tem solução; nada disto abala o invariante central.

Porque é que isto importa para lá da TEI

O padrão generaliza-se. Sempre que se pede a um modelo que anote, transforme ou envolva um pedaço de texto – e sempre que a integridade do texto subjacente importa mais do que a capacidade do modelo para o «melhorar» –, aplica-se a mesma forma de solução. Não peça ao modelo que reescreva o texto. Peça-lhe que produza instruções sobre o texto, e deixe que um compositor determinista as aplique sob um invariante de igualdade.

Para as edições digitais em particular, isto muda o que se pode pedir a um modelo com responsabilidade. A codificação torna-se de repente uma tarefa delegável sem ter de comparar à mão cada resultado com a fonte. A máquina faz o caminho enfadonho; o editor revê a marcação, não a ortografia.

Obter a atualização

Se já tem o tei-mcp instalado:

uvx tei-mcp@latest

Ou de raiz:

pip install tei-mcp

Para usar a composição por intervalos bloqueados, aponte o servidor para uma diretoria de ficheiros-fonte em texto simples:

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

O radical do nome de cada ficheiro passa a ser o seu identificador de documento (letter_001.txt → letter_001).

Código-fonte, documentação completa e notas de design do invariante:

Uma edição digital de outro tipo

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

A maior parte das fontes primárias nunca chega a ser publicada. O modelo em que confiamos para remediar isso, a edição digital financiada por bolsas, é demasiado caro, demasiado centralizado e demasiado frágil para funcionar em escala. Acabo de publicar em que explico por que estou a construir de outra maneira a edição crítica das cartas de Cavriana: fontes primárias digitalizadas que crescem organicamente, com infraestrutura mínima, manutenção automatizada, abertas à colaboração e tão baratas que nem sequer precisam de bolsas. É um argumento a favor de umas humanidades digitais que funcionam com ou sem apoio institucional.

tei-mcp

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

tei-mcp: a TEI P5 ao alcance dos agentes de IA

O tei-mcp é um servidor de código aberto que dá aos assistentes de programação por IA acesso direto à especificação . Em vez de se fiar em dados de treino memorizados – o que produz muitas vezes marcação plausível, mas incorreta –, a IA pode consultar a especificação em tempo real.

Funcionalidades

O servidor analisa a ODD da TEI P5 e expõe 16 ferramentas:

Consultar qualquer elemento, classe, macro ou módulo pelo nome, sem distinção de maiúsculas e com sugestões em caso de gralha
Resolver atributos ao longo de toda a hierarquia de classes da TEI (locais + herdados)
Expandir modelos de conteúdo em árvores estruturadas, com resolução de classes e macros
Validar o aninhamento – relação direta pai-filho ou acessibilidade recursiva, com registo do caminho
Validar documentos contra a TEI P5: modelos de conteúdo, atributos, listas fechadas de valores, integridade das referências e avisos de depreciação
Validar elementos isolados para fluxos de edição incremental
Carregar personalizações ODD para restringir o esquema a um subconjunto específico do projeto
Pesquisar em todos os tipos de entidade com expressões regulares

Instalação

pip install tei-mcp

Ou executar diretamente com:

uvx tei-mcp

Utilização

Acrescente-o a qualquer cliente compatível com MCP (Claude, Cursor, Windsurf, etc.):

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

O código-fonte e a documentação estão no .

tei-mcp: a TEI P5 ao alcance dos agentes de IA

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

Quem já tenha usado um assistente de programação por IA para escrever XML TEI terá reparado que ele se engana. Aparecem elementos onde não deviam. Inventam-se atributos. Ignoram-se as regras de aninhamento. O modelo tem uma ideia vaga do aspeto da TEI, mas nenhum conhecimento fiável da especificação.

O tei-mcp resolve o problema dando aos agentes de IA acesso direto, por meio de ferramentas, às Guidelines da TEI P5.

Lista de Conteúdos

O que é o MCP?

O (MCP) é uma norma aberta que permite às aplicações de IA ligar-se a fontes de dados e ferramentas externas. Pense-se nele como uma porta USB para a IA: um protocolo único que permite a qualquer cliente compatível – Claude, Cursor, Windsurf e outros – ligar-se a serviços especializados.

Um servidor MCP expõe ferramentas que a IA pode invocar durante uma conversa. Em vez de se fiar em dados de treino memorizados, o modelo pode consultar uma fonte viva e autorizada.

O que faz o tei-mcp

O tei-mcp analisa a especificação ODD da TEI P5 e expõe 16 ferramentas que cobrem as perguntas mais frequentes de um editor ou codificador:

O que é este elemento? Consultar qualquer elemento, classe, macro ou módulo pelo nome, sem distinção de maiúsculas e com sugestões em caso de gralha.
Que atributos aceita? Resolver os atributos ao longo de toda a hierarquia de classes – primeiro os locais, depois os herdados, por ordem.
O que pode conter? Expandir os modelos de conteúdo em árvores estruturadas, ou obter uma lista simples dos filhos válidos.
Este elemento pode ir aqui? Verificar o aninhamento pai-filho, ou seguir a acessibilidade através de toda a hierarquia de elementos.
O meu documento é válido? Validar um ficheiro XML TEI contra a especificação: modelos de conteúdo, valores de atributos, listas fechadas de valores, integridade das referências e avisos de depreciação.
E o esquema do meu projeto? Carregar um ficheiro de personalização ODD para restringir tudo o que precede ao subconjunto de TEI próprio do seu projeto.

Porque é que isto importa

Codificar em TEI exige consultar as Guidelines a toda a hora. Os codificadores experientes interiorizam os padrões mais comuns, mas até eles têm de verificar a especificação quando se trata de elementos menos familiares ou de modelos de conteúdo complexos. Para os assistentes de IA, que não têm esse conhecimento interiorizado, o problema é pior: alucinam marcação de aspeto plausível, mas incorreta.

Com o tei-mcp, a IA não tem de adivinhar. Pode procurar a resposta na especificação antes de escrever um único parêntese angular. O resultado é marcação conforme à TEI P5 – ou à personalização ODD do seu projeto.

Primeiros passos

Instale a partir do PyPI:

pip install tei-mcp

Depois, acrescente-o à configuração do seu cliente MCP:

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

O servidor descarrega a especificação TEI na primeira execução e funciona com qualquer cliente compatível com MCP.

Código-fonte e documentação completa:

Multi-Saxon

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

Multi-Saxon: processamento XSLT em paralelo para grandes corpora TEI

O Multi-Saxon colmata uma lacuna crítica das ferramentas de processamento de XML: permite executar em paralelo transformações XSLT 2.0 e 3.0 que o LXML (uma biblioteca Python de XML muito usada) não consegue processar. Concebido especificamente para grandes coleções de documentos XML TEI, o Multi-Saxon acelera consideravelmente o processamento graças a uma execução paralela eficiente.

Características principais

XSLT avançado: processa transformações XSLT 2.0 e 3.0, para lá das capacidades do LXML
Processamento paralelo: reduz drasticamente o tempo de transformação de grandes coleções de documentos graças à paralelização
Otimizado para TEI: concebido especificamente para documentos XML da Text Encoding Initiative (TEI)
Desempenho escalável: lida eficientemente com corpora de centenas a milhares de documentos
Multiplataforma: funciona em diferentes sistemas operativos e ambientes

O problema que o Multi-Saxon resolve

Os investigadores em humanidades digitais que trabalham com TEI deparam-se muitas vezes com dois obstáculos importantes:

O LXML (biblioteca Python corrente para o processamento de XML) só aceita XSLT 1.0, o que impede o uso das funcionalidades mais avançadas do XSLT 2.0/3.0
Processar sequencialmente grandes corpora de documentos TEI pode levar um tempo proibitivo

O Multi-Saxon responde a ambos os problemas tirando partido das capacidades XSLT avançadas do Saxon e distribuindo o processamento por vários núcleos, com ganhos de desempenho significativos.

Implementação

O Multi-Saxon combina Python com o processador Saxon, em Java, para criar um pipeline de transformação de alto desempenho:

Usa a biblioteca Java Saxon para um processamento robusto de XSLT 2.0/3.0
Implementa multiprocessamento para distribuir as transformações pelos núcleos de CPU disponíveis
Gere eficientemente os pools de processadores para maximizar o débito
Oferece uma interface simples para o processamento em lote de documentos TEI

Exemplo de utilização

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")

Impacto para as humanidades digitais

Para os projetos de humanidades digitais que lidam com grandes coleções de documentos TEI, o Multi-Saxon permite:

Transformações complexas à escala do corpus, impossíveis com o LXML
Tempos de processamento drasticamente reduzidos (muitas vezes por fatores de 5 a 10 em sistemas multinúcleo)
Análises mais sofisticadas graças às funcionalidades avançadas do XSLT 2.0/3.0
Um fluxo de trabalho simplificado para processar coleções inteiras de documentos

O código-fonte e a documentação estão no .

persNamer

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

persNamer: ligar a TEI ao Virtual International Authority File

O persNamer é uma ferramenta especializada em Python que simplifica a integração de dados de autoridade sobre pessoas, provenientes do VIAF (Virtual International Authority File), em documentos XML TEI. Ao converter identificadores VIAF em marcação TEI pronta a usar, o persNamer reduz consideravelmente o trabalho manual de criação de entradas estruturadas de pessoas para as edições académicas digitais.

O desafio do controlo de autoridade em TEI

As edições académicas digitais exigem muitas vezes a identificação precisa de personagens históricas, com os seus nomes normalizados e datas de vida. Manter um controlo de autoridade coerente ao longo de um projeto obriga a:

Identificar as pessoas nos textos históricos
Encontrar dados de autoridade a seu respeito
Criar entradas TEI corretamente formatadas
Garantir referências coerentes em todo o projeto

Estes passos são, por norma, manuais, demorados e propensos a incoerências.

Como funciona o persNamer

O persNamer automatiza este fluxo de trabalho:

Obtenção dos dados VIAF: a partir de um identificador VIAF, a ferramenta recupera os dados RDF por negociação de conteúdo HTTP
Extração da informação essencial: analisa o RDF para extrair o nome preferido, a data de nascimento e a data de morte
Geração da marcação TEI: cria dois fragmentos XML essenciais:
- Uma entrada de ficheiro de autoridade (elemento <person> com um xml:id gerado, <persName>, <birth>, <death> e <idno type="VIAF">)
- Uma etiqueta de anotação separada (<persName> com um atributo ref que remete para a entrada de autoridade)

Esta dupla saída permite aos editores manter um ficheiro de autoridade centralizado e, ao mesmo tempo, inserir facilmente etiquetas de anotação nos seus textos TEI.

Características principais

Geração normalizada de identificadores: cria IDs XML coerentes no formato pers-[familyname]-[givenname initial] (p. ex., pers-deteligny-c)
Análise de RDF: usa o rdflib para extrair informação de várias propriedades RDF (p. ex., rdfs:label, schema:name, viaf:mainHead)
Interface de linha de comandos: execução simples, com o número VIAF como único argumento obrigatório
Saída detalhada: fornece informação pormenorizada sobre o processamento, a par do XML final

Exemplo de utilização

python persNamer.py 314802260

Este comando produz:

<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>

Aplicações nas humanidades digitais

O persNamer é particularmente útil para:

Edições académicas digitais que exijam controlo de autoridade
Projetos de codificação TEI que trabalhem com figuras históricas
Iniciativas de dados ligados que liguem documentos a registos de autoridade
Garantir a coerência em grandes corpora TEI
Ensinar os conceitos do controlo de autoridade em cursos de humanidades digitais

Implementação

O persNamer está escrito em Python e depende de:

requests para os pedidos HTTP
rdflib para a análise de RDF
lxml para o tratamento de XML

O código-fonte e a documentação estão no .

Análise bibliográfica em grande escala com modelos de linguagem pré-treinados

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

A automatização é a chave para reduzir o custo dos projetos de humanidades digitais. Até hoje, as tarefas repetitivas e fastidiosas do trabalho editorial em meio académico ou foram executadas a grande custo por investigadores sobrecarregados, ou «subcontratadas» a estudantes. Nesta , defendo que a maior parte destas tarefas ingratas pode ser automatizada – e, mais do que isso, deve sê-lo. Automatizar o trabalho editorial reduz o custo global dos projetos de humanidades digitais; e, sobretudo, permite a investigadores de regiões com poucos recursos publicar documentos valiosos com rapidez e a preço acessível.

No , mostrei, por exemplo, como os modelos de linguagem pré-treinados são capazes de assumir a maior parte do trabalho de etiquetagem XML de uma edição digital.

Neste, apresento um segundo exemplo, desta vez com bibliografia.

O problema

Criar uma base de dados bibliográfica a partir das referências citadas num artigo académico é coisa bastante simples: faz-se uma pesquisa rápida num catálogo como o , descarrega-se a referência num formato à escolha, ou importa-se automaticamente de uma base de dados local. Com um ou dois artigos, funciona bem. A partir de um certo número de referências, porém, a tarefa torna-se ingrata e demorada. Para lhe dar remédio, pode recorrer-se a algoritmos de análise sintática (parsing) como o . Só que estes algoritmos podem ser difíceis de escalar. Quando usei o anystyle para converter os mais de 150 ensaios académicos incluídos na nossa , os erros acumularam-se a um ponto simplesmente impossível de gerir. Não reconheceu devidamente muitas das nossas fontes, confundindo por exemplo os longos títulos dos livros do início da Idade Moderna com outra coisa qualquer, e falhou nos documentos menos típicos, como certas páginas web, vídeos em linha, etc. Os analisadores funcionam bem desde que o autor siga religiosamente as regras de uma convenção consagrada, como a Chicago, a Turabian ou a MLA. Qualquer desvio da norma produz erros.

A solução

É aqui que os modelos de linguagem pré-treinados podem ajudar: apreendem depressa os padrões de qualquer estilo bibliográfico , mesmo um inventado por si, e bastam-lhes alguns exemplos para converter corretamente grandes quantidades de bibliografia formatada numa .

No início de 2021, tive a sorte de obter acesso antecipado ao da OpenAI. O Codex é um modelo que permite traduzir linguagem natural em código e vice-versa. A OpenAI afirma que domina mais de uma dúzia de linguagens de programação e, embora a sua API continue, no momento em que escrevo, acessível apenas em versão beta, já alimenta aplicações populares como o do GitHub.

Depois de brincar um pouco com a API, percebi que também funcionava muito bem com código mais simples, como o BibTeX.

E, de facto, bastaram-me quatro exemplos no prompt de entrada para que funcionasse com fiabilidade.

Prompt de entrada

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}
}

Resultados

Os são impressionantes: mais de 2000 referências bibliográficas convertidas em questão de dias. Esta abordagem reproduziu com exatidão o padrão exposto no meu prompt de entrada, e acrescentou ainda, corretamente, tipos de entrada e de campo que dele não constavam. O GPT-3, por outras palavras, fala BibTeX na perfeição. Mais surpreendente talvez, para um modelo treinado essencialmente em inglês, reconheceu todas as línguas (russo, francês, italiano, latim, grego, alemão, espanhol, etc.), acrescentando de cada vez o campo langid correto.

Nota

O GPT-3 tem, por enquanto, limites de entrada e de saída: processa no máximo 2048 tokens linguísticos. Assim que essa limitação for levantada, a mesma tarefa levará provavelmente uma hora ou menos.

De modo algo inesperado, o GPT-3 acrescentou também informação que não constava das referências originais.

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.

Nesta referência bibliográfica, por exemplo, o GPT-3 acrescentou a ligação permanente ao repositório de acesso aberto ( ) onde o artigo pode ser lido, incluindo os campos ad hoc HAL_ID e HAL_VERSION criados pelo repositório 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}
}

Estes acrescentos indicam que o GPT-3 não se limita a analisar a referência bibliográfica: completa-a com base no que aprendeu inicialmente. Seria interessante, a esse respeito, ver se se comporta da mesma maneira com referências posteriores ao seu treino…

Limitações

O GPT-3 não é perfeito, contudo. Precisa de supervisão humana. Uma das suas limitações conhecidas é a : por vezes inventa coisas e faz suposições improváveis.

Na minha experiência, os acessos de incoerência do GPT-3 manifestaram-se quando ele mudou espontaneamente o apelido de um autor de «Ruscelli» para «Ruscello». Tecnicamente, não é um erro, pois os apelidos italianos do início da Idade Moderna podiam usar-se indistintamente no plural ou no singular. A convenção atual, porém, manda conservar o apelido tal como está, no plural ou no singular. Hoje ninguém chamaria Machiavello a Machiavelli, tal como se espera que usemos o nome Rossello e não Rosselli. Terá o GPT-3 ignorado esta convenção por falta de consciência cronológica? Ou terá feito uma suposição a partir dos apelidos vizinhos, que nesta parte da bibliografia estão todos, por acaso, flexionados no singular (Bariletto, Cesano, Rossello)? Quem sabe.

@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}
}

Conclusão

Escritos ao longo de quatro anos de intensa colaboração, os mais de 150 ensaios fornecem informação vital sobre o manuscrito que editámos e traduzimos, e contêm, além disso, informação bibliográfica valiosa.

Agregar essas referências numa base de dados permite aos editores mudar de formato bibliográfico num abrir e fechar de olhos, com mais liberdade para apresentar a informação como entenderem. A base de dados diz-nos ainda muito sobre a edição e sobre o projeto que a tornou possível, abrindo novas perspetivas de análise aos investigadores. E pode ser completada com grande exatidão e em tempo recorde.

Pode ser que se infiltrem alguns erros, sobretudo por causa da tendência do GPT-3 para alucinar. Mas as futuras versões dos modelos de linguagem pré-treinados atenuarão esse problema.

Avviso | Publicar as notícias que nos fizeram modernos (1537—1743)

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

O objetivo principal do projeto Avviso é digitalizar, preservar, catalogar, editar, contextualizar e divulgar as 35 000 folhas noticiosas manuscritas do início da Idade Moderna, conhecidas por avvisi, que faziam parte da coleção dos Médicis e se encontram hoje no Arquivo de Estado de Florença. Catalogação, digitalização e divulgação de cerca de 35 000 avvisi – folhas noticiosas manuscritas do início da Idade Moderna – através da plataforma Medici Interactive Archive do Medici Archive Project.

Edição eficiente

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

As edições críticas digitais são onerosas. O trabalho de transcrição, tradução e anotação que uma mão-de-obra altamente qualificada tem de executar representa milhares de horas e exige financiamento substancial, além de apoio institucional de longo prazo.

Em certo sentido, é uma bênção que os projetos de grande visibilidade das humanidades digitais consigam reunir as somas avultadas de que precisam para funcionar.

Mas depender tanto da generosidade de fundações abastadas, de universidades e de agências governamentais, e precisar durante tanto tempo de tantos recursos humanos, não constitui um modelo económico viável para o futuro. Se cada vez mais investigadores se podem permitir produzir edições digitais ambiciosas de fontes primárias, a prática continua a ser privilégio de uns poucos países ricos, o que reforça a sua hegemonia cultural.

Para tornar os documentos históricos de todo o mundo acessíveis a um público mais vasto, o custo das edições críticas digitais tem de baixar várias ordens de grandeza .

Nesta série de artigos, avalio as diferentes abordagens e os tijolos tecnológicos de que os investigadores de todo o mundo se podem servir para publicar fontes primárias mais depressa e com despesas mínimas.

Avaliarei, em particular, tecnologias como a aprendizagem automática, a blockchain e o armazenamento descentralizado.

Automatizar a marcação nas edições académicas digitais

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

Introdução

Como produzir edições académicas digitais sem arruinar o orçamento? Neste artigo, o primeiro de uma série dedicada à edição eficiente, avalio o papel que os modelos de linguagem pré-treinados podem desempenhar na automatização de tarefas editoriais como a marcação semântica.

Lista de Conteúdos

O problema

Uma obra de amor

Quem ama não conta os custos… ou assim reza o velho ditado. Vale sobretudo para as edições académicas digitais: a transcrição, a tradução e a anotação que o seu desenvolvimento exige representam milhares de horas de trabalho, levadas a cabo, como no caso de , por centenas de colaboradores altamente qualificados.

Em certo sentido, é uma bênção que os projetos de grande visibilidade das humanidades digitais consigam reunir as somas avultadas de que precisam para funcionar. Mas depender tanto da generosidade de fundações abastadas, de universidades e de agências governamentais, e precisar durante tanto tempo de tantos recursos humanos, não constitui um modelo económico viável para o futuro.

Com efeito, se queremos encorajar investigadores de todo o mundo a tornar documentos históricos acessíveis a um público mais vasto, o custo das edições críticas digitais tem de baixar várias ordens de grandeza .

Uma fasquia alta

Um tanto paradoxalmente, a solução talvez venha de projetos tão exigentes em mão-de-obra como , porque constituem um valioso conjunto de treino para automatizar algumas das tarefas mais ingratas e repetitivas da edição digital, a começar pela marcação.

Não que a marcação seja coisa de somenos. Pelo contrário: a marcação tornou-se o componente indispensável de qualquer projeto académico digital que se leve a sério. Normalizada pela , permite registar o maior número possível de aspetos do documento e do texto que este veicula: estrutura, anotações marginais, rasuras, variantes, tipo de papel, manchas, caligrafia… o que se quiser.

O exemplo seguinte, retirado de , mostra como a marcação enriquece o texto com informação suplementar (categoria, estrutura, campos semânticos, rasuras, etc.), dando por fim às edições digitais uma vantagem considerável sobre as suas antepassadas em papel.

Texto simples Marcação XML

Texto simples	Marcação 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>

Esta informação não vale apenas para fins de arquivo: como já tive ocasião de mostrar, presta-se também à síntese e à análise. Ainda assim, este tipo de anotação pode consumir imenso tempo, tanto mais que o mesmo texto tem muitas vezes de existir em várias versões: tradução, transcrição, modernização, etc.

A solução

Os transformers: o caminho mais simples para a automatização?

Em 2020, a lançou com grande alarido a sua mais recente família de modelos de linguagem de grande dimensão e uso geral, a que chamou GPT-3, sigla de «Generative Pre-trained Transformer 3». Os transformers representam um avanço bastante recente da inteligência artificial. Aprendem tarefas novas com uma rapidez impressionante, bastando-lhes ler uma instrução (prompt) e observar um número muito reduzido de exemplos. Podem ainda receber treino adicional com um conjunto de dados feito à medida (fine-tuning), o que melhora a latência e a precisão. Por isso se diz que o GPT-3 e os transformers comparáveis são , aprendizes de poucos exemplos.

A OpenAI afirma que o GPT-3 contém um número recorde de 175 mil milhões de parâmetros e que foi treinado com mais de 570 GB de texto, na maior parte documentos em inglês presumivelmente recolhidos . Pela sua simples dimensão, o GPT-3 estabeleceu um novo padrão no domínio, executando de raiz as tarefas mais diversas com um realismo perturbador. Escreve plausíveis, em salas de chat, , , traduz documentos, explica jargão, e por aí fora.

Com acesso antecipado à API da OpenAI desde maio de 2021, pude experimentar a capacidade do modelo para resolver várias tarefas de reputada dificuldade: traduzir poesia francesa e textos neolatinos para inglês, explicar analogias e até simplificar o livro 4 da Fundamentação da Metafísica dos Costumes de Kant para uma criança de sete anos (sem grande convicção, diga-se).

Codex

Um dos desenvolvimentos mais recentes do GPT-3 incide sobre as linguagens de programação. Batizado Codex, este modelo traduz linguagem natural em linguagem de programação e vice-versa. Se eu procurar, por exemplo, uma expressão regular que me permita «encontrar apenas as palavras que começam por maiúscula», o GPT-3 converte-a de imediato numa expressão regular funcional: [A-Z]+\w+.

A OpenAI afirma que o Codex trabalha com uma dúzia de linguagens, entre as quais Python, JavaScript, Go, Perl, PHP, Ruby e Swift. Ao converter pseudocódigo em código sem esforço aparente, o Codex permite concentrar a atenção não na sintaxe fastidiosa de uma linguagem, mas nos passos lógicos e nas estratégias que permitem a uma aplicação resolver problemas.

Para lá da OpenAI

A OpenAI, claro está, não é a única a jogar. Como já referi, a Academia de Inteligência Artificial de Pequim anunciou em 2021 um modelo ainda maior e mais capaz, conhecido por Wu Dao 2. A Nvidia e a Microsoft juntaram forças para produzir o modelo Megatron-Turing NLG 530B, de nome bem escolhido. Start-ups mais pequenas, como a e a , também disponibilizam APIs ao público. Merecem ainda menção iniciativas de código aberto como a . O panorama da IA evolui, de resto, muito depressa; para acompanhar as novas iniciativas do sector, consulte .

As experiências

Nota

O objetivo destas experiências é encontrar o caminho mais económico para uma automatização fiável das tarefas editoriais. Poder-se-á objetar que algumas delas também se automatizariam com algoritmos de aprendizagem supervisionada. Exploraremos essa hipótese num próximo artigo.

Poderá um transformer como o GPT-3 aprender a anotar, por exemplo, um manuscrito técnico e científico do século XVI?

Experiência 1 – Categorização de textos.

Comecemos por algo relativamente simples. Sendo um «few-shot learner», o GPT-3 deveria perceber depressa como a nossa equipa editorial classificou as entradas do Ms Fr 640.

Engenharia do prompt

Para o treinar, usei um prompt minimalista e escolhi como exemplos quatro entradas curtas em texto simples, entre as quais uma sobre «medicina», outra sobre «armas e armaduras» e outra sobre «pintura».

Teste

Copiei em seguida outra passagem, que não constava da sequência inicial:

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.

O resultado é perfeitamente coerente com o conteúdo:

<categories="painting">

Se tentarmos com uma entrada pertencente a uma categoria que nem sequer figurava na seleção inicial de textos usada para treinar o GPT-3, o resultado surpreende.

<categories="jewelry">

Resultado

A categoria «jewelry» (joalharia) não existe na nossa edição do Ms. Fr. 640: a equipa editorial a categoria mais lata de «Stones» (pedras). A intuição do GPT-3 é, porém, boa, e indica que, com um pouco mais de treino, ele pode aprender a categorizar qualquer entrada do Ms. Fr. 640, e talvez até as de textos técnicos semelhantes do século XVI.

Experiência 2 – Marcação semântica

Subamos um pouco a fasquia. Se transformers como o GPT-3 aprendem a categorizar textos segundo critérios editoriais específicos, conseguirão também identificar parte da marcação do texto?

Nota

Secrets of Craft and Nature etiquetas semânticas e estruturais. Infelizmente, o GPT-3 não processa imagens, ao contrário de outros projetos, como o . É provável que futuras versões do GPT incluam essa capacidade, necessária para reconhecer a maior parte dos aspetos estruturais e materiais de um documento. Deixaremos de lado essas etiquetas em particular e concentrar-nos-emos na marcação que dispensa o reconhecimento de imagens.

Engenharia do prompt

As etiquetas semânticas incluem referências a animais, plantas, topónimos, sensações, etc. No prompt de treino, selecionei alguns exemplos da edição:

<!--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>

Teste

Experimentemos algumas palavras fáceis com o modelo Davinci-codex: Apothecary, smoke, glassmakers, latten e snake. Os resultados são imediatos e impecáveis:

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

Um teste mais difícil implica palavras compostas, como copper plates, walnut oil e wood block. O que se pretende ver é se o GPT-3 lida bem com etiquetas aninhadas.

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

Ora, os resultados são mistos: o Davinci-codex só etiquetou corretamente walnut oil, e não detetou as etiquetas aninhadas tl e m em copper plates e wood block. Como mostra o teste seguinte, porém, estes erros atenuam-se com um prompt de treino mais bem construído. Depois de acrescentar mais cinco exemplos de etiquetas aninhadas, o Davinci-codex devolveu um resultado quase perfeito, com um único erro (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>

Conclusão

Convém não esquecer que estes testes foram feitos com pequenos fragmentos de texto. Suspeito que, com mais contexto nos exemplos e no prompt, os modelos GPT-3 dariam resultados ainda melhores. De resto, afinar o modelo (fine-tuning) com conjuntos de dados de treino feitos à medida melhoraria sem dúvida a precisão da etiquetagem.
Embora estas experiências ainda tenham de ser conduzidas em maior escala para demonstrar a fiabilidade dos modelos de linguagem pré-treinados, podemos apesar de tudo concluir que esta abordagem permite aos editores automatizar várias tarefas de anotação em poucos passos simples, com uma poupança potencial enorme de tempo e de dinheiro.

Visualizar manuscritos 2 (atualização)

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

Como prometido, eis uma nova versão do treemap interativo apresentado num , desta vez com dois modos de visualização.

Nota

Para uma melhor experiência de visualização, certifique-se de que a página está em modo claro (clique no ícone da lua, no canto superior direito).

Group folios by category

Um navegador visual para o arquivo

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

O problema

As edições digitais sofrem de um paradoxo: se tornam documentos recônditos acessíveis a um público mais vasto, a perda de estímulos sensoriais que a sua desmaterialização acarreta tende a desorientar os leitores e até a desencorajá-los de se envolverem com o conteúdo. Tornam a navegação em vastos repositórios documentais bastante pesada e intimidante. Isto vale não apenas para os utilizadores sem experiência de investigação em arquivo, mas também para os leitores com dificuldades cognitivas.

A solução

É aqui que os metadados de arquivo nos podem ajudar. Com efeito, esses dados permitem criar abstrações visuais interativas que dão aos leitores um estímulo sensorial alternativo, melhorando assim a ergonomia e a acessibilidade. Para tornar o arquivo visualmente navegável, um treemap, ou qualquer diagrama que decomponha eficazmente dados hierárquicos, serve perfeitamente.

A experiência

A minha primeira experiência adapta o para D3.js, acrescentando-lhe hiperligações. Representa o manuscrito BnF Ms Fr 640, os seus fólios e as entradas dentro de cada fólio. As cores representam a categoria dominante. Ao passar o rato sobre cada entrada, obtêm-se mais dados, incluindo a hiperligação para o manuscrito.
Deste modo, o treemap torna-se um índice visual interativo, dando aos leitores uma panorâmica muito rápida e reativa, não apenas do conteúdo do manuscrito, mas também das dimensões de cada fólio e de cada entrada.
~~Nos próximos meses continuarei a explorar esta ideia, experimentando outros diagramas e outras hierarquias… Fiquem atentos!~~ Para uma nova versão do treemap, clique .

Nota

Para uma melhor experiência de visualização, certifique-se de que a página está em modo claro (clique no ícone da lua, no canto superior direito).

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

O arquivo num relance

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

O problema

Os arquivos históricos podem ser de uma desordem intimidante. O Mediceo del Principato, no , é um caso exemplar. Com efeito, só uma pequena parte está inventariada, e muitos dos seus documentos andam dispersos por mais de 6500 volumes sem razão aparente. Para complicar as coisas, o arquivo só permite consultar um número limitado de volumes – ou filze, como lá lhes chamam: maços, diríamos nós. Em tempos normais, o limite é de 4 filze por dia; em tempo de pandemia, porém, desceu para 4 de duas em duas semanas. Na falta de inventários detalhados, a dimensão considerável do arquivo obriga os investigadores a engendrar estratégias para encontrar depressa os documentos que procuram.

A solução

Uns preferem confiar no acaso; outros tentam também fazer conjeturas informadas a partir da cronologia, dos destinatários, dos autores, da origem do fundo de arquivo, da língua, etc. Olhar para todas estas variáveis ao mesmo tempo, porém, pode revelar padrões inesperados na estrutura do arquivo e melhorar as nossas conjeturas. A minha experiência mostra que, uma vez representados graficamente, os metadados que os investigadores costumam reunir numa folha de cálculo aumentam significativamente a consciência situacional no arquivo.

A experiência

A minha investigação atual centra-se na correspondência de um espião do século XVI. As suas cartas estão espalhadas por centenas de filze. Foram escritas sob identidades diferentes, a destinatários diferentes e por vezes inesperados, de lugares diferentes, etc. Para encontrar as filze com mais probabilidade de conter as cartas esperadas, montei um dashboard, uma aplicação web de visualização interativa de dados ( ) que cruza informação de toda a espécie, geográfica e cronológica incluída, com um diagrama hierárquico ( ) do fundo de arquivo. O dashboard diz-me num relance o que já foi encontrado, quanto isso representa, e dá-me uma ideia aproximada de onde poderia procurar cartas novas. Além disso, ao clicar em variáveis específicas, todos os diagramas se atualizam para mostrar correlações particulares.

Próximos passos

Mais importante ainda, talvez: este dashboard pode ser reconvertido em índice visual. Quando a edição crítica destas cartas for publicada em linha, o dashboard funcionará como porta de entrada alternativa, a partir da qual os leitores poderão percorrer os dados. Por razões de confidencialidade, só posso mostrar por agora uma captura de ecrã com partes ocultadas, mas divulgarei o dashboard completo no próximo ano. Entretanto, um protótipo estará disponível em breve. Fiquem atentos!

Making & Knowing Project

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

O , fundado em 2014 por Pamela H. Smith e com centenas de colaboradores, é uma iniciativa de investigação e de ensino do da Universidade de Columbia.

Como investigador de pós-doutoramento, participei no projeto trabalhando, entre outras coisas, na do BnF Ms. Fr. 640. Este manuscrito francês do século XVI, único no seu género, dá-nos um vislumbre em primeira mão do fazer e dos materiais de uma época em que os artistas eram cientistas.

A edição digital disponibiliza gratuitamente uma abundância de dados no seu . Ao longo do próximo ano, tenciono publicar uma série de artigos sobre a edição e os seus dados, mostrando como é fácil descarregar e analisar o texto com Python ou R. Fiquem atentos!

Visualizar a marcação semântica do BnF Ms. Fr. 640

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

Panorâmica

As edições académicas ricas em dados contêm anotações editoriais valiosas que se podem extrair, analisar e visualizar para toda a espécie de fins académicos. É o caso de , lançada em 2020, que disponibiliza o seu ficheiro de metadados para descarga no seu repositório GitHub. Neste artigo, mostro como reunir todas estas variáveis numa matriz de correlação e visualizá-las de diferentes maneiras.

Os dados

O Making and Knowing Project gera uma folha de cálculo com informação atualizada sobre o conteúdo do manuscrito: entry_metadata.csv. O ficheiro pode ser obtido no do Making & Knowing. Em alternativa, podem gerar-se ficheiros .csv à medida, com mais marcação, graças ao excelente de Matthew Kumar, uma versão em Python do BnF Ms. Fr. 640.

Preparar o Python

Usaremos o Pandas para tratar os dados, o Matplotlib e o seaborn para os mapas de calor e, por fim, o NetworkX para produzir redes baseadas em correlações.
Para este tipo de variáveis, evitaremos o método de Pearson e usaremos em seu lugar o método 𝜙𝐾. Convém este método de correlação e sobre o PhiK, a biblioteca correspondente.

#install packages
pip install phik

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

Preparar os dados

Comecemos por descarregar o ficheiro de metadados mais recente da edição, na pasta metadata do seu . Selecionaremos apenas as colunas de que precisamos. Para esta demonstração, escolho todas as etiquetas semânticas da tradução inglesa tl, mas também se podem escolher as da transcrição francesa tc ou as da versão normalizada tcn. Os dados vêm em valores separados por ponto e vírgula, e precisamos que o Python os conte por nós. Usaremos para isso o método stack-unstack com a expressão regular [^;\s][^\;]*[^;\s]*. Para tornar a matriz mais legível, mudamos o nome a cada coluna. Quem tiver pressa pode saltar este passo; basta ter presente que, nesta altura, o nosso dataframe se chama 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'})

Correlacionar

Limpo o dataframe, podemos passar ao cálculo dos coeficientes de correlação entre cada par de variáveis. Nesta fase, é importante compreender os dados e garantir que se usa o método de correlação mais adequado. O pacote pandas-profiling é particularmente útil para isso.

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

cortag é a nossa matriz de correlação. Podemos agora experimentar diferentes tipos de visualização.

Visualizar

A primeira coisa a tentar é visualizá-la como matriz codificada por cores, com o do seaborn.

Mapa de calor de correlações

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

Quem conhece bem o texto vê logo que o mapa de calor faz muito sentido. Os nomes, por exemplo, estão fortemente correlacionados com o latim, pois era costume, sobretudo entre os humanistas do século XVI, latinizá-los.

Haverá quem diga que este mapa de calor se limita a afirmar o óbvio. Não estão inteiramente errados e, à primeira vista, as etiquetas médicas parecem confirmá-lo, pois correlacionam-se, como seria de prever, com partes do corpo, medidas e plantas.

Mas, se lermos o mapa de calor com mais atenção, linha a linha, podemos encontrar correlações interessantes e inesperadas. Que as etiquetas médicas, por exemplo, se correlacionem com palavras italianas e latinas dá-nos pistas sobre a origem das receitas médicas do Ms. Fr. 640. Do mesmo modo, a correlação entre profissões, definições e medidas mostra até que ponto a identidade profissional estrutura os discursos técnicos do século XVI.

Mapa de agrupamentos (clustermap)

Os mapas de calor são úteis em contextos «exploratórios», mas podem parecer um pouco confusos ao público, sobretudo quando se discutem – ou ainda se procuram – agrupamentos semânticos específicos no manuscrito. O módulo clustermap do seaborn pode dar resultados interessantes.

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

Além de parecer um inseto pixelizado (sim, a palavra está dicionarizada), o clustermap distingue claramente as etiquetas isoladas (em cima e à esquerda) das mais interligadas. Distinguem-se também agrupamentos isolados, como música e poitevin (quem diria!), de outros mais centrais, como medidas, material, definições e armas. As profissões estão mais interligadas, mas não fazem parte, pelo menos nesta matriz de correlação, de nenhum agrupamento em particular.

Rede de correlações

Se quisermos sintetizar ainda mais as correlações contidas na matriz, os grafos de rede oferecem uma solução elegante. Isto é particularmente verdade nos contextos em que queremos comunicar sobre o conteúdo do manuscrito.
Para o fazer, é preciso transformar a matriz numa lista de arestas e nós e definir um limiar que elimine do grafo as correlações mais fracas.

# 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 houver arestas e nós a mais, pode sempre alterar-se o limiar para obter um resultado mais limpo. Em alternativa, pode exportar-se o grafo para o manipular no Gephi, com a função .write_gexf().

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

O resultado pode ver-se no início deste artigo.

Atualização: rede ponderada circular

Andava à procura de maneiras de representar matrizes de correlação como redes ponderadas e encontrei esta abordagem interessante , que adapto aqui ao nosso conjunto de dados.

# 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')

Removidas algumas arestas, podemos determinar a cor e a espessura das restantes.

# 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

Damos também aos nós um tamanho proporcional ao seu número de ligações.

# 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))

O resultado é um grafo ponderado que admite mais nós e consideravelmente mais arestas, sem deixar de ser legível e informativo.

A correspondência secreta de Filippo Cavriana, 1568—1589.

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

As cartas secretas de Filippo Cavriana são um testemunho único das guerras religiosas francesas: cobrem, ao longo de mais de 20 anos, as intrigas, batalhas, negociações e conspirações que marcaram o ritmo da vida na corte de França e fora dela.

As cartas, conservadas no , estão na sua maior parte dispersas por centenas de maços não inventariados – filze, como lhes chamam em Florença. Embora tenha conseguido descobrir dezenas de cartas novas nos últimos anos, este tipo de investigação em arquivo revela-se cada vez mais difícil. A distância geográfica de Florença, a degradação de alguns serviços públicos em Itália e a pandemia de Covid-19 concorrem para fazer destes projetos de publicação um processo longo e incerto.

Publicar fontes primárias deve continuar a fazer parte, apesar das dificuldades crescentes, do ofício do historiador. A forma dessas publicações, porém, terá provavelmente de evoluir: adaptar-se à situação que acabo de descrever, sem dúvida, mas também refletir melhor a natureza incremental desta investigação e permitir que outra pessoa a continue.

Daí a ideia de desenvolver um novo tipo de projeto de publicação digital que seja escalável, sustentável, fiável, independente de plataforma e potencialmente colaborativo.

A edição está agora em linha: . Reúne as cartas transcritas até à data, dos Arquivos de Estado de Florença e de Mântua e da BnF, e cresce à medida que surgem outras. Expliquei as razões do seu desenho num .