Pular para conteúdo

Explorar o exemplo em 5 minutos

Neste tutorial você instala o mapa-da-ciencia e abre o painel com um exemplo sintético: 1.500 artigos fictícios de ciência política, em 28 tópicos, publicados entre 2010 e 2025. Não é preciso Ollama, modelos nem internet (além da instalação).

Dados fictícios

Títulos, autores, resumos e afiliações do exemplo são inventados. Só os nomes das revistas e das instituições são reais, para o exemplo parecer familiar. Não use esses dados em análises.

1. Instale o uv

O uv gerencia o Python e as dependências do projeto.

brew install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Instale o mapa-da-ciencia

Há dois caminhos. Para usar, o primeiro basta; o segundo é para quem vai mexer no código.

Cada release tem um arquivo .whl com tudo pronto, inclusive a interface do painel. Instale o da mais recente (troque a versão, se houver uma mais nova):

uv tool install "https://github.com/felipelmc/mapa-da-ciencia/releases/download/v1.0.1/mapa_da_ciencia-1.0.1-py3-none-any.whl"
mapa --versao

A última linha mostra a versão instalada, por exemplo mapa-da-ciencia 1.0.1.

Além do uv, é preciso o Node.js 22.18 ou mais recente, para compilar a interface do painel uma vez:

git clone https://github.com/felipelmc/mapa-da-ciencia.git
cd mapa-da-ciencia
uv sync
cd frontend
npm ci
npm run empacotar
cd ..
uv run mapa --versao

O npm pode sugerir npm audit fix --force ou npm run preview no fim: não é preciso, pode ignorar. Neste caminho, os comandos do mapa começam com uv run (uv run mapa painel), e as dicas que o próprio mapa imprime (mapa status) também.

3. Abra o painel com o exemplo

mapa painel --exemplo

(Pelo código: uv run mapa painel --exemplo.) O navegador abre em http://127.0.0.1:8765/. A página inicial mostra os números do corpus e os sete macrotemas, cada um com sua cor. Use o trilho à esquerda para passear pelas vistas. O Mapa mostra os 1.500 documentos fictícios como pontos: arraste para mover, use a roda do mouse para aproximar, clique num ponto para ver o documento, e experimente a busca (/), o laço (L) e o Play da linha do tempo (Ler o mapa). Tópicos mostra os assuntos no tempo, Geografia as UFs, os países e as instituições dos autores, e Classificação e Validação, a leitura dos resumos por um codebook e a concordância numa amostra.

Para encerrar, volte ao terminal e aperte Ctrl+C.

A página diz que a interface não foi compilada?

Você instalou pelo código e a interface ainda não foi compilada. Encerre o painel (Ctrl+C), rode os comandos do npm do passo 2 e abra o painel de novo: o painel só enxerga a interface nova quando é aberto de novo.

O que aconteceu

mapa painel --exemplo gerou os dados de exemplo numa pasta temporária, subiu um servidor local só na sua máquina e abriu o navegador. Os dados seguem o mesmo contrato que o pipeline produz para um projeto real. Por isso o exemplo é uma prévia fiel do que você vai ver com os seus próprios dados.

Próximos passos