Seu primeiro mapa, parte 1: a coleta¶

Neste tutorial você monta um corpus de verdade: os artigos da revista Opinião Pública publicados em 2024. No fim, você terá um projeto com 25 artigos, com títulos, resumos, autores, afiliações e licenças, e saberá conferir a cobertura desses dados. Leva uns 10 minutos.

A parte 1 não usa modelos de linguagem: só precisa de internet, para consultar a ArticleMeta do SciELO e o OpenAlex. A parte 2 descobre os tópicos e monta o mapa; a parte 3 mostra os tópicos no tempo e a geografia; e a parte 4 classifica os resumos com um codebook e mede a concordância.

Antes de começar

Você precisa do mapa-da-ciencia instalado. Se ainda não instalou, siga os passos 1 e 2 de Explorar o exemplo e volte para cá.

Os comandos abaixo são os de quem instalou pelo código: começam com uv run e rodam dentro da pasta mapa-da-ciencia que você baixou. Quando o próprio mapa sugerir um próximo passo (por exemplo, mapa status), ponha uv run na frente. Se instalou pelo wheel, digite só mapa (sem uv run), em qualquer pasta.

1. Escolha a revista¶

O mapa traz a lista das revistas correntes do SciELO Brasil. Procure pela revista:

uv run mapa revistas "opinião pública"

A linha da revista mostra o ISSN (0104-6276) e o acrônimo (op). Os dois servem para identificá-la nos próximos comandos.

2. Crie o projeto¶

uv run mapa novo projetos/op-2024 --revista op --anos 2024

O comando cria a pasta projetos/op-2024 com dois arquivos de configuração:

mapa.yaml: o recorte (revistas e anos), as fontes e os modelos;
codebook.yaml: as variáveis da classificação, usadas na parte 4.

Abra o mapa.yaml num editor. As opções --revista e --anos já deixaram o recorte pronto:

fontes:
  scielo:
    colecao: scl            # SciELO Brasil
    revistas:               # ISSN como aparece no SciELO
      - 0104-6276           # Opinião Pública
...
recorte:
  anos: [2024, 2024]

Entre na pasta do projeto. Daqui em diante, os comandos valem para ele:

cd projetos/op-2024

Identifique-se para as APIs (opcional)

A ArticleMeta e o OpenAlex pedem que quem faz muitas consultas se identifique. O mapa novo deixou na pasta do projeto um modelo, .env.exemplo. Copie-o para .env e preencha o seu e-mail:

cp .env.exemplo .env

Depois, abra o .env num editor de texto e complete a linha MAPA_EMAIL= (por exemplo, MAPA_EMAIL=voce@exemplo.org). O e-mail vai só no cabeçalho das requisições, e o .env fica fora do git (mapa novo já o colocou no .gitignore). Sem ele, a coleta funciona igual: é uma cortesia com as APIs, que respondem a quem se identifica.

3. Colete¶

uv run mapa coletar

Em alguns segundos, o mapa:

lista na ArticleMeta todos os artigos da revista e separa os de 2024 pelo identificador (o PID);
baixa o registro completo de cada um e o normaliza: títulos e resumos em cada idioma, palavras-chave, autores com ORCID e afiliações;
deixa de fora resenhas, editoriais e outros tipos que não são artigos;
liga cada artigo ao OpenAlex, que acrescenta as citações recebidas e a licença de cada artigo.

A saída termina assim:

Coleta concluída em 7,2 s: 25 documento(s) de 1 revista(s), 2024.
┏━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Revista ┃ Documentos ┃
┡━━━━━━━━━╇━━━━━━━━━━━━┩
│ op      │ 25         │
└─────────┴────────────┘
Ficaram de fora — fora do período: 544.
ArticleMeta: 26 requisição(ões), 0 resposta(s) do cache.
OpenAlex: 25 de 25 casados; 2 requisição(ões), 2 crédito(s).

Os 544 "fora do período" são os artigos da revista de outros anos. O OpenAlex cobra créditos por consulta, e sem cadastro são mil por dia: esta coleta gastou 2, um pela lista de artigos da revista e outro pelos registros das instituições dos autores.

4. Rode de novo¶

uv run mapa coletar

Agora a coleta termina quase instantaneamente:

ArticleMeta: 0 requisição(ões), 26 resposta(s) do cache.
OpenAlex: 25 de 25 casados; 0 requisição(ões), 0 crédito(s).

Cada resposta das APIs fica guardada em brutos/, e as próximas execuções leem de lá. É isso que torna a coleta reproduzível (o corpus não muda enquanto você não pedir) e retomável (se a internet cair no meio, a próxima execução busca só o que faltou). Para buscar artigos publicados depois da primeira coleta, use mapa coletar --atualizar.

5. Confira a cobertura¶

uv run mapa status

Além do recorte e das etapas, o status mostra a seção Corpus:

Corpus: 25 documento(s), 2024
Cobertura                         Resumo por idioma
                   ┃  n ┃   %          ┃   n ┃    %
━━━━━━━━━━━━━━━━━━━╇━━━━╇━━━━     ━━━━━╇━━━━━╇━━━━━
com resumo         │ 25 │ 100     fr   │  25 │  100
com DOI            │ 25 │ 100     pt   │  25 │  100
com afiliação      │ 25 │ 100     en   │  25 │  100
possível duplicata │  0 │   0     es   │  25 │  100

Todos os 25 artigos têm resumo, DOI e afiliação, e a Opinião Pública publica resumos em quatro idiomas. Em outras revistas e períodos a cobertura é menor: o guia Montar um recorte explica o que cada tabela significa e o que conferir.

6. Explore os dados em Python¶

O corpus fica em dados/documentos.parquet, e a API Python consulta esse arquivo em SQL. Abra o Python do projeto com uv run python e rode:

import mapa_da_ciencia.api as mapa

p = mapa.abrir()
mais_citados = """
    SELECT titulos[1].texto AS titulo, citacoes
    FROM documentos
    ORDER BY citacoes DESC
    LIMIT 3
"""
mapa.consultar(p, mais_citados)

O resultado lista os três artigos mais citados da revista em 2024, segundo o OpenAlex. Para sair do Python, digite exit(). O mesmo código funciona num notebook do Jupyter.

7. Veja no painel¶

uv run mapa painel

A página inicial do painel agora mostra os números do seu corpus: 25 documentos, 1 revista, 2024. O mapa e os tópicos aparecem depois da etapa de tópicos, na parte 2. Para encerrar, aperte Ctrl+C no terminal.

O que você fez¶

Criou um projeto com um recorte de uma revista e um ano.
Coletou os artigos da ArticleMeta e os ligou ao OpenAlex, com cache em brutos/.
Conferiu a cobertura com mapa status e consultou o corpus em SQL.

Próximos passos¶

Um recorte maior. O projeto piloto reúne dez revistas de ciência política e relações internacionais, de 2010 a 2025: cerca de 4.300 artigos. Na primeira vez, a coleta leva alguns minutos:
```
cd ../..
uv run mapa novo projetos/cp-scielo
uv run mapa coletar -P projetos/cp-scielo
```
Uma busca, em vez de revistas inteiras: Importar do search.scielo.org ou a busca por termo em Montar um recorte.
De onde vêm os dados e como as fontes são ligadas: Fontes de dados.