vosviewer

Integração VOSviewer

Propósito: transformar qualquer conjunto de dados bibliográficos em uma rede funcional do VOSviewer: seja como um arquivo JSON que carrega diretamente no VOSviewer Online (sem instalação), ou como um par .map + .net para a versão desktop.

Quando usar esta skill

Acione esta skill quando o usuário solicitar qualquer um dos seguintes:

• Mapa bibliométrico / bibliometric map
• Rede de coautoria / co-authorship network
• Rede de co-citação / co-citation network / bibliographic coupling
• Mapa de termos / keyword map / term co-occurrence
• "Visualizar artigos do PubMed/Crossref/Scopus/RIS no VOSviewer"
• "Quero ver a rede de autores/termos/keywords de …"
• Explícito: "VOSviewer", "app.vosviewer.com", ".map", ".net", ".json VOSviewer"

Considere também esta skill quando o usuário tiver um conjunto de referências acadêmicas (fontes do NotebookLM, acervo, bibliografia_parsed.json) e quiser explorá-lo visualmente.

Conceitos principais

O VOSviewer trabalha com itens (nós) conectados por ligações (arestas), organizados em clusters. Itens podem ser autores, documentos, termos, palavras-chave, periódicos, organizações, países, etc.

Quatro tipos de análise:

1. Coautoria: itens = autores/organizações/países, força da ligação = número de artigos em coautoria
2. Cocitação: itens = referências citadas/autores/fontes, força da ligação = número de documentos que citam ambos
3. Acoplamento bibliográfico: itens = documentos/autores/fontes, força da ligação = número de referências compartilhadas
4. Coocorrência: itens = palavras-chave/termos, força da ligação = número de documentos onde ambos aparecem

Formatos de arquivo aceitos pelo VOSviewer

Formato	Extensão	Caso de uso
JSON do VOSviewer	.json	Melhor para compartilhamento. Arquivo único carrega no VOSviewer Online via URL. Contém itens + ligações + configuração.
Mapa + Rede	.map + .net	Formato clássico desktop. Separado por tabulação. .map = itens, .net = ligações.
Banco de dados bibliográfico	Vários	Exportações brutas do Web of Science, Scopus, Dimensions, Lens, PubMed (MEDLINE), JSON do Crossref, RIS. O VOSviewer analisa estes diretamente.

Regra prática: Produza o arquivo JSON sempre que possível: é o mais flexível, compartilhável e funciona no VOSviewer Online (sem necessidade de instalação desktop).

Esquema JSON do VOSviewer (essenciais)

{
  "network": {
    "items": [
      {
        "id": 1,                          // inteiro único
        "label": "cultura digital",       // nome de exibição
        "description": "HTML opcional",   // mostrado no popover
        "url": "https://...",             // URL clicável opcional
        "x": 0.42,                        // opcional; o VOSviewer calcula se omitido
        "y": -0.17,                       // opcional
        "cluster": 1,                     // id do cluster (inteiro)
        "weights": {                      // pesos numéricos arbitrários
          "Documentos": 12,
          "Citações": 58,
          "Força total de ligação": 23
        },
        "scores": {                       // opcional: escores numéricos para coloração
          "Ano médio de publicação": 2022.4
        }
      }
    ],
    "links": [
      {"source_id": 1, "target_id": 2, "strength": 3}
    ]
  },
  "config": {
    "terminology": {                      // opcional: personalizar rótulos
      "item": "termo", "items": "termos",
      "link": "coocorrência", "links": "coocorrências",
      "cluster": "cluster", "clusters": "clusters"
    },
    "templates": [                        // opcional: visualização de rótulo/cor
      { "label_size": {"min": 0.5, "max": 2.0} }
    ]
  }
}

Fluxo de trabalho canônico

Siga estes passos quando o usuário solicitar uma visualização no VOSviewer:

1. Identificar a fonte de dados

Pergunte (ou infira) a partir de:

• Consulta PubMed: use mcp__7899fadf-...__search_articles + get_article_metadata (este projeto tem o MCP do PubMed)
• Crossref: WebFetch https://api.crossref.org/works?query=...&rows=100 (gratuito, sem chave)
• OpenAlex: WebFetch https://api.openalex.org/works?search=...&per_page=100
• Fontes do NotebookLM: mcp__notebooklm-mcp__source_get_content por fonte
• Arquivo local: RIS, BibTeX, CSV, JSON no projeto (use Leitura/Glob)
• Lista manual: usuário cola DOIs ou títulos

2. Escolher o tipo de análise

Usuário diz	Tipo de análise	Itens	Ligações por
"rede de autores" / "co-authorship"	coautoria	autores	artigos em coautoria
"mapa de termos" / "keyword map"	coocorrência	palavras-chave/termos	coocorrência em resumos/títulos
"co-citação" / "co-citation"	cocitação	referências citadas	co-citadas por um artigo comum
"artigos similares" / "coupling"	acoplamento bibliográfico	documentos	referências compartilhadas
"mapa de temas" / "themes"	coocorrência	termos	coocorrência

Padrão quando ambíguo: coocorrência de palavras-chave/termos: é a análise mais tolerante e funciona apenas com títulos e resumos.

3. Construir a rede

Use o script conversor apropriado em scripts/ (veja abaixo). Todos os scripts emitem um arquivo JSON do VOSviewer no diretório do projeto atual.

4. Abrir o resultado

Duas opções: apresente ambas ao usuário.

Opção A: VOSviewer Online (sem instalação):

1. Hospede o arquivo JSON em qualquer lugar publicamente acessível (GitHub raw, S3, Netlify, Cloudflare R2, um gist, etc.)
2. Construa a URL:

   https://app.vosviewer.com/?json=<URL-encoded-URL-to-json>
   

3. Compartilhe esta URL com o usuário. Clicar nela carrega a rede diretamente no navegador.

Opção B: VOSviewer Desktop:

1. Salve o arquivo JSON localmente
2. Instrua o usuário: abra o VOSviewer → Arquivo → Abrir → selecione o arquivo JSON
3. Alternativamente, forneça os arquivos .map + .net separados por tabulação

5. Oferecer ajustes

Após produzir a primeira versão, ofereça-se para:

• Filtrar itens por peso mínimo (ex.: palavras-chave que aparecem ≥ 5 vezes)
• Alterar o número de clusters por meio do parâmetro de resolução
• Adicionar escores de ano para mostrar tendências temporais (mais antigo = azul, mais recente = vermelho)
• Mesclar sinônimos por meio de um tesauro (ex.: "ia" ↔ "inteligência artificial")

Scripts

Esta skill vem com scripts conversores prontos em scripts/:

• scripts/pubmed_to_vosviewer.py: Consulta PubMed → JSON de coocorrência de palavras-chave
• scripts/crossref_to_vosviewer.py: Consulta Crossref → JSON de coautoria
• scripts/openalex_to_vosviewer.py: Consulta OpenAlex → JSON de coocorrência de conceitos
• scripts/ris_to_vosviewer.py: Arquivo RIS → JSON de coocorrência de palavras-chave
• scripts/json_to_map_net.py: Converter JSON do VOSviewer → .map + .net para desktop
• scripts/open_in_vosviewer.py: Construir a URL do VOSviewer Online (ou abrir desktop)

Todos os scripts usam apenas a biblioteca padrão do Python (sem dependências pip) a menos que indicado.

Tesauro (amigável ao português)

reference/thesaurus-pt.txt contém normalizações comuns de sinônimos em português brasileiro (ex.: ia → inteligência artificial, chatgpt → modelos de linguagem, aps → atenção primária). Carregue este arquivo ao construir mapas de coocorrência de termos para conjuntos de dados de saúde/educação em português.

Convenção de local de saída

Salve todos os arquivos produzidos em vosviewer-out/ na raiz do projeto atual (crie se não existir):

vosviewer-out/
├── YYYY-MM-DD_topic.json        # JSON do VOSviewer
├── YYYY-MM-DD_topic.map         # arquivo de mapa desktop (se solicitado)
├── YYYY-MM-DD_topic.net         # arquivo de rede desktop (se solicitado)
└── README.md                     # O que foi gerado, como e a URL Online

Formato de resposta

Ao entregar um resultado do VOSviewer ao usuário, SEMPRE inclua:

1. Resumo do conjunto de dados: fonte, número de itens, número de ligações, intervalo de datas (se disponível)
2. Caminho(s) do(s) arquivo(s): onde os arquivos JSON/map/net foram salvos
3. URL do VOSviewer Online: se o JSON foi hospedado em algum lugar acessível
4. Instruções para desktop: uma linha sobre como abrir o JSON localmente
5. Próximas ações: o que ajustar em seguida (filtro, contagem de clusters, tesauro, etc.)

Mantenha a resposta concisa. Não cole o JSON completo no chat: apenas o resumo e a URL/caminho.

Links de referência

• Página inicial do VOSviewer: https://www.vosviewer.com/
• VOSviewer Online: https://app.vosviewer.com/
• Manual (formato JSON): https://app.vosviewer.com/docs/file-types/json-file-type/
• Manual desktop: https://www.vosviewer.com/documentation/Manual_VOSviewer_1.6.20.pdf