Contrato de dados
Modelos do contrato de dados v1 (arquivos de saida/dados/).
Convenções:
- Todo arquivo tem versao_contrato. Mudança incompatível = nova versão maior; versões menores
(1.1, 1.2…) só acrescentam campos, e quem lê a 1.0 lê qualquer 1.x.
- Tabelas grandes são colunares: colunas com listas do mesmo tamanho, e campos
categóricos guardados como índices em dicionarios (economiza espaço e acelera o
filtro cruzado no navegador). -1 significa "sem valor".
- Resumos e evidências ficam fora de documentos.json, em fragmentos
detalhes/{00..3f}.json, carregados sob demanda (ver fragmento_de).
- Nenhum arquivo do contrato pode conter e-mails ou codificações humanas individuais (as divergências de
validacao.json vêm só de codificadores de referência; as de pessoas ficam na API local do painel).
Versão atual: 1.7. Os JSON Schemas ficam em contrato/schema/, e um exemplo sintético completo em contrato/exemplo/dados/.
manifesto.json
Manifesto
Índice do projeto publicado: o que existe, de onde veio e como foi gerado. É o primeiro arquivo que
a interface lê.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
api |
sim/não |
obrigatório |
True no painel local (há API); False no site estático publicado. |
gerado_em |
datetime |
obrigatório |
|
projeto |
ProjetoInfo |
obrigatório |
Identificação do projeto. |
recorte |
RecorteInfo |
obrigatório |
Recorte do corpus: período, fontes e idiomas. |
contagens |
Contagens |
obrigatório |
Números do corpus, usados na capa do painel. |
arquivos |
lista de texto |
obrigatório |
Arquivos do contrato presentes nesta pasta. |
execucao |
ExecucaoInfo |
obrigatório |
Dados de reprodutibilidade da última execução de cada etapa. |
licencas |
mapa de texto para inteiro |
vazio |
Licença → número de documentos. |
publicacao |
PublicacaoInfo ou vazio |
vazio |
Presente só no site publicado (mapa publicar). |
desatualizadas |
lista de texto |
vazio |
Etapas com resultado desatualizado (as entradas mudaram depois), que por isso ficou fora destes dados: topicos, geografia, redes ou classificacao. A interface diz o que rodar de novo. |
mudancas |
mapa de texto para lista de texto |
vazio |
Para cada etapa desatualizada, o que mudou desde a última execução, quando se sabe (nas redes: "o pessoas.yaml", "a geografia"…). |
ProjetoInfo
Identificação do projeto.
| Campo |
Tipo |
Padrão |
Descrição |
nome |
texto |
obrigatório |
|
titulo |
texto |
obrigatório |
|
descricao |
texto |
"" |
|
RecorteInfo
Recorte do corpus: período, fontes e idiomas.
| Campo |
Tipo |
Padrão |
Descrição |
anos |
par de inteiro e inteiro |
obrigatório |
|
fontes |
lista de texto |
obrigatório |
Ex.: ['scielo:scl', 'openalex']. |
idioma_analise |
texto |
obrigatório |
|
idioma_exibicao |
texto |
obrigatório |
|
Contagens
Números do corpus, usados na capa do painel.
| Campo |
Tipo |
Padrão |
Descrição |
documentos |
inteiro |
obrigatório |
|
topicos |
inteiro |
0 |
|
classificados |
inteiro |
0 |
|
validados |
inteiro |
0 |
|
com_afiliacao |
inteiro |
0 |
|
com_instituicao |
inteiro |
0 |
Documentos com ao menos uma instituição identificada. |
ExecucaoInfo
Dados de reprodutibilidade da última execução de cada etapa.
| Campo |
Tipo |
Padrão |
Descrição |
versao_pacote |
texto |
obrigatório |
|
modelos |
mapa de texto para texto |
vazio |
Papel → modelo@digest. |
hash_codebook |
texto ou vazio |
vazio |
|
sementes |
mapa de texto para inteiro |
vazio |
|
duracao_s |
mapa de texto para número |
vazio |
Etapa → segundos da última execução. |
PublicacaoInfo
O que o mapa publicar fez: quando, e quantos resumos foram ou não publicados.
| Campo |
Tipo |
Padrão |
Descrição |
em |
datetime |
obrigatório |
|
resumos_publicados |
inteiro |
obrigatório |
Resumos com licença Creative Commons, publicados sem alteração. |
resumos_retirados |
inteiro |
obrigatório |
Resumos que ficaram de fora (licença não aberta, desconhecida ou --sem-resumos). |
sem_resumos |
sim/não |
false |
|
revistas.json
Revistas
Revistas presentes no corpus, com o número de documentos de cada uma.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
revistas |
lista de Revista |
obrigatório |
Uma revista do corpus. |
Revista
Uma revista do corpus.
| Campo |
Tipo |
Padrão |
Descrição |
id |
texto |
obrigatório |
Acrônimo no SciELO, ex.: dados. |
issn |
texto |
obrigatório |
|
titulo |
texto |
obrigatório |
|
areas |
lista de texto |
vazio |
|
n |
inteiro |
obrigatório |
|
documentos.json
Documentos
Tabela principal: um documento por posição, com coordenadas no mapa, tópico e classificações.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
n |
inteiro |
obrigatório |
|
colunas |
ColunasDocumentos |
obrigatório |
Colunas da tabela de documentos (todas com n itens, na mesma ordem). |
dicionarios |
DicionariosDocumentos |
obrigatório |
Valores por trás dos índices das colunas categóricas. |
ColunasDocumentos
Colunas da tabela de documentos (todas com n itens, na mesma ordem).
| Campo |
Tipo |
Padrão |
Descrição |
id |
lista de texto |
obrigatório |
|
doi |
lista de texto ou vazio |
obrigatório |
|
titulo |
lista de texto |
obrigatório |
|
ano |
lista de inteiro |
obrigatório |
|
revista |
lista de inteiro |
obrigatório |
Índice em dicionarios.revista. |
idioma |
lista de inteiro |
obrigatório |
Índice em dicionarios.idioma (idioma do resumo exibido). |
x |
lista de número |
obrigatório |
|
y |
lista de número |
obrigatório |
|
topico |
lista de inteiro |
obrigatório |
Id do tópico (ver topicos.json) ou -1. |
atribuicao |
lista de inteiro |
obrigatório |
Índice em dicionarios.atribuicao: cluster (o HDBSCAN agrupou o documento) ou vizinho (o HDBSCAN o deixou sem tópico; os vizinhos o atribuíram, ou não, se topico = -1). |
autores_curto |
lista de texto |
obrigatório |
Ex.: Limongi, F.; +2. |
vizinhos |
lista de lista de inteiro |
obrigatório |
Índices (nesta tabela) dos 5 documentos mais próximos. |
cls |
mapa de texto para lista de inteiro |
vazio |
Variável do codebook → índice em dicionarios.cls[variavel] ou -1. |
DicionariosDocumentos
Valores por trás dos índices das colunas categóricas.
| Campo |
Tipo |
Padrão |
Descrição |
revista |
lista de texto |
obrigatório |
|
idioma |
lista de texto |
obrigatório |
|
atribuicao |
lista de "cluster" | "vizinho" |
["cluster", "vizinho"] |
|
cls |
mapa de texto para lista de texto |
vazio |
|
afiliacoes.json
Afiliacoes
Afiliações com contagem fracionária, base da vista de geografia.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
n |
inteiro |
obrigatório |
|
colunas |
ColunasAfiliacoes |
obrigatório |
Colunas da tabela longa de afiliações: uma linha por documento × (instituição, UF, país), pesos somados. |
dicionarios |
DicionariosAfiliacoes |
obrigatório |
Instituições, UFs e países por trás dos índices. |
ColunasAfiliacoes
Colunas da tabela longa de afiliações: uma linha por documento × (instituição, UF, país), pesos somados.
| Campo |
Tipo |
Padrão |
Descrição |
doc |
lista de inteiro |
obrigatório |
Índice do documento em documentos.json. |
instituicao |
lista de inteiro |
obrigatório |
Índice em dicionarios.instituicao, ou -1 quando o autor não informou afiliação. |
uf |
lista de inteiro |
obrigatório |
Índice em dicionarios.uf ou -1 (fora do Brasil ou desconhecida). |
pais |
lista de inteiro |
obrigatório |
Índice em dicionarios.pais ou -1 (desconhecido). |
peso |
lista de número |
obrigatório |
Contagem fracionária: 1 por documento, dividido entre os autores e depois entre as afiliações de cada um. A soma por documento é 1. |
DicionariosAfiliacoes
Instituições, UFs e países por trás dos índices.
| Campo |
Tipo |
Padrão |
Descrição |
instituicao |
lista de Instituicao |
obrigatório |
Uma instituição de afiliação, já normalizada. |
uf |
lista de texto |
obrigatório |
Siglas das UFs (as 27, em ordem alfabética, para índices estáveis). |
pais |
lista de texto |
obrigatório |
Códigos ISO 3166-1 alfa-2 presentes nas afiliações. |
Instituicao
Uma instituição de afiliação, já normalizada.
| Campo |
Tipo |
Padrão |
Descrição |
id |
texto |
obrigatório |
ror:… quando houver, openalex:I… sem ROR, um apelido do projeto, ou nao-identificada (reservado: afiliação informada que não casou com nenhuma instituição). |
nome |
texto |
obrigatório |
|
sigla |
texto ou vazio |
vazio |
|
uf |
texto ou vazio |
vazio |
|
pais |
texto |
obrigatório |
ISO 3166-1 alfa-2; vazio em nao-identificada. |
detalhes/{00..3f}.json
Fragmento
Um dos 64 fragmentos de detalhes, carregados sob demanda.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
fragmento |
texto |
obrigatório |
|
documentos |
mapa de texto para Detalhe |
obrigatório |
O que a interface mostra ao abrir um documento: resumo, autores, licença e evidências. |
Detalhe
O que a interface mostra ao abrir um documento: resumo, autores, licença e evidências.
| Campo |
Tipo |
Padrão |
Descrição |
resumo |
texto ou vazio |
obrigatório |
None quando a licença não permite publicar o resumo. |
idioma |
texto ou vazio |
obrigatório |
|
palavras_chave |
lista de texto |
vazio |
|
autores |
lista de texto |
obrigatório |
|
url |
texto ou vazio |
obrigatório |
|
licenca |
texto |
obrigatório |
|
licenca_fonte |
texto |
obrigatório |
|
evidencias |
mapa de texto para Evidencia |
vazio |
Valor de uma variável do codebook e o trecho do resumo que o justifica. |
idioma_analise |
texto ou vazio |
vazio |
Idioma do texto usado nos embeddings e nos tópicos. |
fonte_analise |
"resumo" | "reserva" | "so_titulo" ou vazio |
vazio |
resumo: título e resumo no idioma de análise; reserva: resumo em outro idioma (não havia no de análise); so_titulo: o documento não tem resumo. O texto em si não é publicado. |
juri |
mapa de texto para DecisaoJuri |
vazio |
Variável → decisão do júri (só nos documentos da amostra, com júri). |
Evidencia
Valor de uma variável do codebook e o trecho do resumo que o justifica.
| Campo |
Tipo |
Padrão |
Descrição |
valor |
texto ou sim/não ou lista de texto ou vazio |
obrigatório |
|
evidencia |
texto |
obrigatório |
|
status |
"literal" | "aproximada" | "ausente" | "dispensada" |
obrigatório |
literal: o trecho está no texto; aproximada: quase (90% dos caracteres); ausente: não está; dispensada: vazia numa resposta sem informação. |
inicio |
inteiro ou vazio |
vazio |
Posição do trecho no resumo exibido, se localizado, em pontos de código Unicode (como o Python conta; em JavaScript, converta para UTF-16). |
fim |
inteiro ou vazio |
vazio |
|
campo |
"titulo" | "resumo" ou vazio |
vazio |
Onde o trecho foi localizado; inicio e fim são posições nesse texto. |
DecisaoJuri
Como o júri decidiu uma variável de um documento da amostra de validação.
| Campo |
Tipo |
Padrão |
Descrição |
etapa |
"unanime" | "maioria" | "deliberacao" | "sem_maioria" |
obrigatório |
|
virou |
sim/não |
false |
A deliberação mudou a decisão (outra maioria, ou antes não havia). |
valor |
texto ou sim/não ou lista de texto ou vazio |
obrigatório |
A decisão final (com o supervisor, se ele decidiu). |
valor_sem_supervisor |
texto ou sim/não ou lista de texto ou vazio |
obrigatório |
|
supervisor |
texto ou vazio |
vazio |
Quem arbitrou, quando não houve maioria. |
justificativa |
texto ou vazio |
vazio |
A justificativa do supervisor (vazia no site publicado). |
votos |
lista de VotoJuri |
vazio |
O voto de um membro do júri numa variável, numa rodada (1: votação; 2: deliberação). |
VotoJuri
O voto de um membro do júri numa variável, numa rodada (1: votação; 2: deliberação).
| Campo |
Tipo |
Padrão |
Descrição |
membro |
texto |
obrigatório |
|
rodada |
1 | 2 |
obrigatório |
|
valor |
texto ou sim/não ou lista de texto ou vazio |
obrigatório |
|
evidencia |
texto |
obrigatório |
Vazia no site publicado quando a licença do resumo não é aberta. |
status |
"literal" | "aproximada" | "ausente" | "dispensada" |
obrigatório |
|
revisou |
sim/não |
false |
Na rodada 2: o membro mudou de valor na deliberação. |
topicos.json
Topicos
Tópicos e macrotemas do corpus, com as séries por ano.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
anos |
lista de inteiro |
obrigatório |
|
total_por_ano |
lista de inteiro |
obrigatório |
|
parametros |
mapa de texto para número ou inteiro ou texto |
obrigatório |
|
estabilidade_ari |
número ou vazio |
obrigatório |
|
macrotemas |
lista de Macrotema |
obrigatório |
Agrupamento de tópicos próximos, usado para a cor e a navegação. |
topicos |
lista de Topico |
obrigatório |
Um tópico: rótulo e descrição escritos pelo LLM, palavras-chave, cor estável e série no tempo. |
outliers |
Outliers |
obrigatório |
Documentos que o agrupamento não encaixou em nenhum tópico. |
metodo_tendencia |
MetodoTendencia ou vazio |
vazio |
Como a tendência é calculada. O painel lê daqui os parâmetros para recalcular com os filtros. |
Macrotema
Agrupamento de tópicos próximos, usado para a cor e a navegação.
| Campo |
Tipo |
Padrão |
Descrição |
id |
inteiro |
obrigatório |
|
rotulo |
texto |
obrigatório |
|
cor |
texto |
obrigatório |
|
topicos |
lista de inteiro |
obrigatório |
|
descricao |
texto |
"" |
|
serie |
Serie ou vazio |
vazio |
Soma das séries dos tópicos do macrotema. |
tendencia |
Tendencia ou vazio |
vazio |
Tendência da participação anual no período inteiro, sem filtros: o gabarito para o painel. |
Serie
Série temporal de um tópico.
| Campo |
Tipo |
Padrão |
Descrição |
n |
lista de inteiro |
obrigatório |
Documentos por ano, alinhado a anos. |
prop |
lista de número |
obrigatório |
Proporção do total do ano. |
Tendencia
Tendência da participação anual no período inteiro, sem filtros: o gabarito para o painel.
| Campo |
Tipo |
Padrão |
Descrição |
direcao |
"alta" | "queda" | "estavel" | "insuficiente" |
obrigatório |
|
inclinacao |
número ou vazio |
vazio |
Inclinação na escala logit, por ano. |
erro_padrao |
número ou vazio |
vazio |
Erro-padrão da inclinação, já corrigido pela dispersão. |
ic95 |
par de número e número ou vazio |
vazio |
|
dispersao |
número ou vazio |
vazio |
φ de Pearson (1 na binomial pura). |
prop_inicio |
número ou vazio |
vazio |
Participação ajustada no primeiro ano com documentos. |
prop_fim |
número ou vazio |
vazio |
Participação ajustada no último ano com documentos. |
pp_periodo |
número ou vazio |
vazio |
Variação em pontos percentuais no período. |
pp_por_ano |
número ou vazio |
vazio |
|
anos |
par de inteiro e inteiro ou vazio |
vazio |
|
motivo |
"poucos_anos" | "poucos_documentos" | "sem_variacao" | "sem_convergencia" ou vazio |
vazio |
Por que não há tendência, quando é insuficiente. |
fragil |
sim/não ou vazio |
vazio |
Só em alta ou em queda: true quando, refeita sem um dos anos, a tendência muda de direção (ou fica sem dados suficientes) em ao menos uma das retiradas. Ausente nos dados até a 1.6. |
anos_decisivos |
lista de inteiro |
vazio |
Os anos cuja retirada muda a direção de uma tendência frágil. |
Topico
Um tópico: rótulo e descrição escritos pelo LLM, palavras-chave, cor estável e série no tempo.
| Campo |
Tipo |
Padrão |
Descrição |
id |
inteiro |
obrigatório |
|
macro_id |
inteiro |
obrigatório |
|
rotulo |
texto |
obrigatório |
|
descricao |
texto |
obrigatório |
|
palavras_chave |
lista de par de texto e número |
obrigatório |
|
n |
inteiro |
obrigatório |
|
centroide |
par de número e número |
obrigatório |
|
cor |
texto |
obrigatório |
|
serie |
Serie |
obrigatório |
Série temporal de um tópico. |
por_revista |
mapa de texto para inteiro |
obrigatório |
|
representativos |
lista de texto |
obrigatório |
Ids de documentos. |
rotulo_fonte |
"llm" | "palavras" | "manual" |
"llm" |
Quem escreveu o rótulo: o modelo de linguagem, as palavras-chave ou você (rotulos.yaml). |
n_nucleo |
inteiro ou vazio |
vazio |
Documentos do núcleo, que o HDBSCAN agrupou (os demais foram reatribuídos por vizinhança). |
tendencia |
Tendencia ou vazio |
vazio |
Tendência da participação anual no período inteiro, sem filtros: o gabarito para o painel. |
Outliers
Documentos que o agrupamento não encaixou em nenhum tópico.
| Campo |
Tipo |
Padrão |
Descrição |
n |
inteiro |
obrigatório |
Documentos que o HDBSCAN deixou sem tópico. |
reatribuidos |
inteiro |
obrigatório |
Quantos deles foram atribuídos ao tópico mais próximo. |
por_ano |
lista de inteiro |
vazio |
Documentos que o HDBSCAN deixou de fora, por ano (inclui os reatribuídos depois), alinhado a anos. |
sem_topico_por_ano |
lista de inteiro |
vazio |
Documentos que ficaram sem tópico (−1) no fim, por ano. |
MetodoTendencia
Como a tendência é calculada. O painel lê daqui os parâmetros para recalcular com os filtros.
| Campo |
Tipo |
Padrão |
Descrição |
modelo |
"logistica_binomial" |
"logistica_binomial" |
Regressão logística da participação anual, com o ano como variável. |
dispersao |
"quase" | "binomial" |
"quase" |
quase: o erro-padrão é corrigido pela dispersão de Pearson; binomial: não é. |
nivel |
número |
0.95 |
Nível do intervalo da inclinação. |
quantil |
"t" | "normal" |
"t" |
Quantil do intervalo: t (de Student, com anos − 2 graus de liberdade, quando a dispersão é estimada) ou normal. Ausente nos dados até a 1.6, que usavam a normal. |
z |
número |
1.959963984540054 |
Quantil da normal no nível pedido: o valor crítico com quantil: normal. |
anos_minimos |
inteiro |
5 |
Anos com documentos no recorte para haver tendência. |
docs_minimos |
inteiro |
10 |
Documentos do tópico no período para haver tendência. |
codebook.json
CodebookContrato
Cópia publicada do codebook, com o hash que identifica a versão usada.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
nome |
texto |
obrigatório |
|
versao |
texto |
obrigatório |
|
hash |
texto |
obrigatório |
|
instrucoes |
texto |
obrigatório |
|
variaveis |
lista de VariavelContrato |
obrigatório |
Variável do codebook. |
VariavelContrato
Variável do codebook.
| Campo |
Tipo |
Padrão |
Descrição |
id |
texto |
obrigatório |
|
rotulo |
texto |
obrigatório |
|
tipo |
"categorica" | "multipla" | "booleana" | "texto" |
obrigatório |
|
pergunta |
texto |
obrigatório |
|
categorias |
lista de CategoriaContrato |
vazio |
Categoria de uma variável, como o codebook define. |
CategoriaContrato
Categoria de uma variável, como o codebook define.
| Campo |
Tipo |
Padrão |
Descrição |
valor |
texto |
obrigatório |
|
rotulo |
texto |
obrigatório |
|
definicao |
texto |
obrigatório |
|
exemplos |
lista de texto |
vazio |
|
classificacoes.json
Classificacoes
Resumo da classificação por codebook: modelo, cobertura e contagens por categoria.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
modelo |
texto |
obrigatório |
|
hash_codebook |
texto |
obrigatório |
|
cobertura |
número |
obrigatório |
Fração dos documentos com classificação válida. |
evidencia_literal |
número |
obrigatório |
Fração das evidências encontradas literalmente no resumo. |
contagens |
mapa de texto para mapa de texto para inteiro |
obrigatório |
Variável → valor → documentos. Nas de múltipla escolha, cada categoria conta à parte; as de texto ficam de fora. |
classificados |
inteiro |
0 |
|
documentos |
inteiro |
0 |
Documentos com resumo, que podiam ser classificados. |
sem_resumo |
inteiro |
0 |
|
parcial |
sim/não |
false |
A classificação ainda não cobre todos os documentos com resumo. |
json_valido_na_primeira |
número ou vazio |
vazio |
|
por_variavel |
mapa de texto para VariavelClassificada |
vazio |
Como uma variável saiu na classificação. |
VariavelClassificada
Como uma variável saiu na classificação.
| Campo |
Tipo |
Padrão |
Descrição |
n |
inteiro |
obrigatório |
Documentos com resposta nesta variável. |
sem_informacao |
número |
obrigatório |
Fração das respostas sem informação (nao_informado, nao_se_aplica ou falso). |
evidencia |
mapa de texto para número |
vazio |
Status → fração das evidências, sem as dispensadas. |
validacao.json
Validacao
Resultados da validação da classificação: concordância por variável e por par de participantes.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
amostra |
AmostraInfo |
obrigatório |
Como a amostra de validação foi sorteada. |
metricas |
lista de MetricaVariavel |
obrigatório |
Concordância entre dois participantes (codificador × modelo, codificadores ou modelos) numa variável. |
modelos |
lista de texto |
obrigatório |
|
divergencias |
lista de Divergencia |
obrigatório |
Um caso em que um codificador de referência e o modelo principal discordam, para arbitragem. |
codificadores |
lista de Participante |
vazio |
Participantes, com o tipo. |
modelo_principal |
texto ou vazio |
vazio |
|
hash_codebook |
texto ou vazio |
vazio |
|
comparacoes_modelos |
lista de ComparacaoModelos |
vazio |
McNemar exato entre dois modelos, contra a mesma referência, numa variável. |
evidencia_literal |
mapa de texto para número |
vazio |
Modelo → fração das evidências literais na amostra. |
juri |
ResumoJuri ou vazio |
vazio |
O júri de modelos locais, quando o projeto tem um. |
AmostraInfo
Como a amostra de validação foi sorteada.
| Campo |
Tipo |
Padrão |
Descrição |
n |
inteiro |
obrigatório |
|
estratificar_por |
texto |
obrigatório |
|
semente |
inteiro |
obrigatório |
|
idiomas |
mapa de texto para inteiro |
vazio |
Documentos da amostra por idioma do texto lido. Vazio até a 1.6. |
MetricaVariavel
Concordância entre dois participantes (codificador × modelo, codificadores ou modelos) numa variável.
Nas de múltipla escolha, variavel é id:categoria (uma variável sim/não por categoria).
| Campo |
Tipo |
Padrão |
Descrição |
variavel |
texto |
obrigatório |
|
comparacao |
texto |
obrigatório |
Ex.: claude-opus × qwen3.5:9b (referência primeiro). |
n |
inteiro |
obrigatório |
|
concordancia |
número ou vazio |
obrigatório |
|
kappa |
número ou vazio |
obrigatório |
|
kappa_ic95 |
par de número e número ou vazio |
obrigatório |
|
pabak |
número ou vazio |
obrigatório |
|
alfa |
número ou vazio |
obrigatório |
|
matriz |
Matriz |
obrigatório |
Matriz de confusão entre dois participantes. |
referencia |
texto |
"" |
Participante tomado como referência (linhas da matriz). |
comparado |
texto |
"" |
|
por_classe |
lista de MetricaClasse |
vazio |
Precisão, revocação e F1 de uma categoria, tomando o primeiro do par como referência. |
circular |
sim/não |
false |
Os dois participantes são da mesma família de modelo (a referência e o supervisor do júri, por exemplo): um limite superior, e não uma medida independente. |
subconjuntos |
lista de MetricaSubconjunto |
vazio |
A concordância por idioma (quando a amostra tem mais de um) e entre respostas informativas. Vazio nos dados até a 1.6. |
Matriz
Matriz de confusão entre dois participantes.
| Campo |
Tipo |
Padrão |
Descrição |
rotulos |
lista de texto |
obrigatório |
|
valores |
lista de lista de inteiro |
obrigatório |
Linhas = a referência do par; colunas = o outro participante. |
MetricaClasse
Precisão, revocação e F1 de uma categoria, tomando o primeiro do par como referência.
| Campo |
Tipo |
Padrão |
Descrição |
rotulo |
texto |
obrigatório |
|
suporte |
inteiro |
obrigatório |
Quantas vezes a referência deu esta categoria. |
precisao |
número ou vazio |
obrigatório |
|
revocacao |
número ou vazio |
obrigatório |
|
f1 |
número ou vazio |
obrigatório |
|
MetricaSubconjunto
A concordância de um par numa parte da amostra. Sem matriz nem métricas por classe: num grupo pequeno, elas
mostrariam as respostas de cada documento.
| Campo |
Tipo |
Padrão |
Descrição |
tipo |
"idioma" | "informativas" |
obrigatório |
idioma: os documentos cujo texto lido está em idioma; informativas: os documentos em que nenhuma das duas respostas é de sem-informação ("não informado", "não se aplica"). |
idioma |
texto ou vazio |
vazio |
Código do idioma, no subconjunto por idioma. |
n |
inteiro |
obrigatório |
|
concordancia |
número ou vazio |
vazio |
Ausente com menos de 20 documentos, como as outras métricas. |
kappa |
número ou vazio |
vazio |
|
kappa_ic95 |
par de número e número ou vazio |
vazio |
|
pabak |
número ou vazio |
vazio |
|
alfa |
número ou vazio |
vazio |
|
Divergencia
Um caso em que um codificador de referência e o modelo principal discordam, para arbitragem.
| Campo |
Tipo |
Padrão |
Descrição |
doc |
texto |
obrigatório |
|
variavel |
texto |
obrigatório |
|
humano |
texto |
obrigatório |
Valor dado pelo codificador (o nome do campo vem da versão 1.0). |
modelo |
texto |
obrigatório |
|
evidencia |
texto |
obrigatório |
Trecho que o modelo citou. |
codificador |
texto |
"" |
|
status |
"literal" | "aproximada" | "ausente" | "dispensada" ou vazio |
vazio |
|
incerto |
sim/não |
false |
O codificador marcou a resposta como incerta. |
Participante
Quem respondeu na amostra: um codificador (humano ou referencia, que não é uma pessoa) ou um modelo.
| Campo |
Tipo |
Padrão |
Descrição |
nome |
texto |
obrigatório |
|
tipo |
"humano" | "referencia" | "modelo" |
obrigatório |
|
n |
inteiro |
obrigatório |
Documentos da amostra com resposta. |
familia |
texto ou vazio |
vazio |
Família de modelo, quando se conhece (ver circular). |
ComparacaoModelos
McNemar exato entre dois modelos, contra a mesma referência, numa variável.
| Campo |
Tipo |
Padrão |
Descrição |
variavel |
texto |
obrigatório |
|
referencia |
texto |
obrigatório |
|
modelo_a |
texto |
obrigatório |
|
modelo_b |
texto |
obrigatório |
|
n |
inteiro |
obrigatório |
|
acertos_a |
inteiro |
obrigatório |
|
acertos_b |
inteiro |
obrigatório |
|
p |
número |
obrigatório |
|
ResumoJuri
O júri de modelos locais na amostra: estágios, deliberação, concordância por estágio e auditoria.
| Campo |
Tipo |
Padrão |
Descrição |
referencia |
texto ou vazio |
obrigatório |
O codificador tomado como referência nas contagens. |
membros |
lista de texto |
obrigatório |
|
supervisor |
texto ou vazio |
obrigatório |
|
familia_supervisor |
texto ou vazio |
obrigatório |
|
documentos |
inteiro |
obrigatório |
|
etapas |
mapa de texto para mapa de texto para inteiro |
obrigatório |
Variável → estágio → decisões. |
virou |
mapa de texto para inteiro |
vazio |
Variável → decisões que a deliberação mudou. |
concordancia_por_etapa |
mapa de texto para mapa de texto para inteiro |
vazio |
Estágio → {n, acertos} contra a referência, com a decisão do júri sem o supervisor (no estágio sem_maioria, o voto do primeiro membro). |
concordancia_supervisor |
ConcordanciaSupervisor ou vazio |
vazio |
Nas decisões sem maioria arbitradas, a concordância com a escolha do supervisor. |
deliberacao |
mapa de texto para mapa de texto para inteiro |
vazio |
Membro → {votos, mudou, para_referencia, contra}: votos revistos na deliberação e a direção. |
auditoria |
AuditoriaJuri ou vazio |
vazio |
A conferência, pelo supervisor, de uma amostra das decisões unânimes do júri. |
ConcordanciaSupervisor
A concordância com a referência nas decisões sem maioria que o supervisor arbitrou, com a escolha dele.
| Campo |
Tipo |
Padrão |
Descrição |
n |
inteiro |
obrigatório |
|
acertos |
inteiro |
obrigatório |
|
circular |
sim/não |
obrigatório |
O supervisor e a referência são da mesma família: não é medida independente. |
AuditoriaJuri
A conferência, pelo supervisor, de uma amostra das decisões unânimes do júri.
| Campo |
Tipo |
Padrão |
Descrição |
n |
inteiro |
obrigatório |
|
erros |
inteiro |
obrigatório |
|
taxa |
número ou vazio |
obrigatório |
|
ic95 |
par de número e número ou vazio |
obrigatório |
Intervalo de Wilson de 95% da taxa de erro. |
por_variavel |
mapa de texto para par de inteiro e inteiro |
vazio |
Variável → (erros, n). |
agregados.json
Agregados
Gabarito calculado no Python para testar o filtro cruzado do frontend.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
topico_ano_revista |
lista de tupla |
obrigatório |
(tópico, ano, revista, n). |
uf |
mapa de texto para número |
obrigatório |
Contagem fracionária por UF (sigla). |
pais |
mapa de texto para número |
obrigatório |
Contagem fracionária por país (ISO alfa-2). |
instituicao |
mapa de texto para número |
vazio |
Contagem fracionária por instituição. |
uf_inteiro |
mapa de texto para inteiro |
vazio |
Documentos com alguma afiliação na UF. |
pais_inteiro |
mapa de texto para inteiro |
vazio |
|
instituicao_inteiro |
mapa de texto para inteiro |
vazio |
|
sem_afiliacao |
número |
0 |
Peso dos autores sem afiliação informada. |
sem_pais |
número |
0 |
Peso das afiliações de país desconhecido (inclui sem_afiliacao). |
arestas_coautoria |
inteiro |
0 |
Pares de coautores no corpus inteiro. |
uf_pares |
lista de tupla |
vazio |
(UF, UF ou EX, peso, documentos) na colaboração entre estados. |
canone_n |
lista de inteiro |
vazio |
Documentos que citam cada obra do cânone. |
redes.json
Redes
Coautoria (pessoas), colaboração entre instituições e as séries da colaboração.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
pessoas |
ColunasPessoas |
obrigatório |
As pessoas (autores identificados), em colunas. x e y só para quem teve coautor (o desenho da rede). |
autorias |
AutoriasRede |
obrigatório |
Quem escreveu cada documento: pares (índice do documento em documentos.json, índice da pessoa). |
instituicoes |
ColunasInstituicoesRede ou vazio |
vazio |
As instituições que colaboraram com outra, com o desenho da rede (os ids são os de afiliacoes.json). |
comunidades |
lista de ComunidadeRede |
vazio |
|
metricas |
mapa de texto para MetricasRede |
vazio |
|
colaboracao |
lista de ColaboracaoAno |
vazio |
A colaboração num ano, em frações dos documentos do ano. |
parametros |
mapa de texto para Any |
vazio |
|
ColunasPessoas
As pessoas (autores identificados), em colunas. x e y só para quem teve coautor (o desenho da rede).
| Campo |
Tipo |
Padrão |
Descrição |
id |
lista de texto |
obrigatório |
Id publicado: um HMAC curto do id interno com o segredo do projeto (o site não publica ORCIDs nem ids do OpenAlex, e o id não se liga a eles sem o segredo). |
nome |
lista de texto |
obrigatório |
|
documentos |
lista de inteiro |
obrigatório |
|
grau |
lista de inteiro |
obrigatório |
Coautores distintos. |
comunidade |
lista de inteiro |
obrigatório |
Índice em comunidades da rede de coautoria; -1 nas pequenas. |
x |
lista de número ou vazio |
obrigatório |
|
y |
lista de número ou vazio |
obrigatório |
|
AutoriasRede
Quem escreveu cada documento: pares (índice do documento em documentos.json, índice da pessoa).
| Campo |
Tipo |
Padrão |
Descrição |
doc |
lista de inteiro |
obrigatório |
|
pessoa |
lista de inteiro |
obrigatório |
|
ColunasInstituicoesRede
As instituições que colaboraram com outra, com o desenho da rede (os ids são os de afiliacoes.json).
| Campo |
Tipo |
Padrão |
Descrição |
id |
lista de texto |
obrigatório |
|
grau |
lista de inteiro |
obrigatório |
|
comunidade |
lista de inteiro |
obrigatório |
|
x |
lista de número |
obrigatório |
|
y |
lista de número |
obrigatório |
|
ComunidadeRede
| Campo |
Tipo |
Padrão |
Descrição |
rede |
"coautoria" | "instituicoes" |
obrigatório |
|
id |
inteiro |
obrigatório |
|
n |
inteiro |
obrigatório |
Nós da comunidade. |
documentos |
inteiro |
obrigatório |
|
macro |
inteiro ou vazio |
obrigatório |
Macrotema mais frequente nos documentos da comunidade. |
topicos |
lista de inteiro |
obrigatório |
Os tópicos mais frequentes, em ordem. |
rotulo |
texto |
obrigatório |
Os dois tópicos mais frequentes (a comunidade não recebe nome de pessoa). |
cor |
texto ou vazio |
vazio |
Cor da comunidade (hex): um tom da cor do macrotema dela, diferente dos tons das outras comunidades do mesmo macrotema na mesma rede. null sem macrotema (a interface usa a cor neutra). Desde a versão 1.6; antes, a interface usava a cor do macrotema. |
MetricasRede
| Campo |
Tipo |
Padrão |
Descrição |
nos |
inteiro |
obrigatório |
|
arestas |
inteiro |
obrigatório |
|
componentes |
inteiro |
obrigatório |
|
maior_componente |
inteiro |
obrigatório |
|
fracao_maior |
número |
obrigatório |
|
densidade |
número |
obrigatório |
|
grau_medio |
número |
obrigatório |
|
agrupamento |
número |
obrigatório |
|
modularidade |
número ou vazio |
obrigatório |
|
ColaboracaoAno
A colaboração num ano, em frações dos documentos do ano.
| Campo |
Tipo |
Padrão |
Descrição |
ano |
inteiro |
obrigatório |
|
documentos |
inteiro |
obrigatório |
|
com_coautoria |
número |
obrigatório |
|
autores_medio |
número |
obrigatório |
|
com_instituicoes |
número ou vazio |
vazio |
Duas ou mais instituições identificadas. |
entre_ufs |
número ou vazio |
vazio |
Duas ou mais UFs brasileiras. |
com_exterior |
número ou vazio |
vazio |
Brasil e exterior no mesmo documento. |
citacoes.json
Citacoes
A rede de citação pelas referências do OpenAlex e o cânone.
| Campo |
Tipo |
Padrão |
Descrição |
versao_contrato |
texto |
"1.7" |
Versão do contrato. Versões 1.x só acrescentam campos: quem lê 1.0 lê qualquer 1.x. |
n_referencias |
lista de inteiro |
obrigatório |
Referências de cada documento resolvidas no OpenAlex (0: casado, sem nenhuma); -1: sem casamento. |
internas |
ArestasCitacao |
obrigatório |
Citações dentro do corpus: índices de documentos (quem cita → quem é citado). |
canone |
lista de ObraCitada |
obrigatório |
Uma obra de fora do corpus entre as mais citadas (o cânone), na ordem de n (e do id, no empate). |
canone_citantes |
CitantesCanone |
obrigatório |
|
fluxo_macrotemas |
lista de lista de inteiro |
obrigatório |
Citações internas de macrotema (linha) a macrotema (coluna), na ordem de topicos.macrotemas (pela posição, e não pelo id, que não é contíguo). |
cobertura |
mapa de texto para inteiro |
vazio |
Documentos (documentos, com_referencias), referências resolvidas (referencias) e, nos documentos casados, as listadas na ArticleMeta (referencias_listadas), as resolvidas entre elas (referencias_resolvidas) e a mediana por documento da fração resolvida (resolvidas_mediana_pct); citações internas, anacrônicas e autorreferências; referências a obras apagadas (a_obras_apagadas); citantes, resenhas e autorias corrigidas do cânone; obras sem metadados entre as mais citadas. |
ArestasCitacao
Citações dentro do corpus: índices de documentos (quem cita → quem é citado).
| Campo |
Tipo |
Padrão |
Descrição |
de |
lista de inteiro |
obrigatório |
|
para |
lista de inteiro |
obrigatório |
|
ObraCitada
Uma obra de fora do corpus entre as mais citadas (o cânone), na ordem de n (e do id, no empate).
| Campo |
Tipo |
Padrão |
Descrição |
id |
texto |
obrigatório |
Id do OpenAlex (W…). |
titulo |
texto ou vazio |
obrigatório |
|
ano |
inteiro ou vazio |
obrigatório |
O ano da obra (o das referências, quando o registro do OpenAlex é uma resenha). |
autores |
lista de texto |
obrigatório |
Até três autores, conferidos nas referências da ArticleMeta. |
veiculo |
texto ou vazio |
obrigatório |
|
tipo |
texto ou vazio |
obrigatório |
|
doi |
texto ou vazio |
obrigatório |
|
n |
inteiro |
obrigatório |
Documentos do corpus que a citam. |
edicoes |
lista de texto |
vazio |
Outros registros da mesma obra, somados a este. |
resenha |
sim/não |
false |
O registro do OpenAlex é uma resenha da obra (tipo book-review, Choice Reviews, ou um primeiro autor que as referências não citam): autores e ano vêm das referências. |
registro_openalex |
texto ou vazio |
vazio |
Autores e ano do registro do OpenAlex, quando diferem dos mostrados (a conferência os mudou). |
CitantesCanone
| Campo |
Tipo |
Padrão |
Descrição |
doc |
lista de inteiro |
obrigatório |
|
obra |
lista de inteiro |
obrigatório |
Índice em canone. |