btrainee/revisão-sistemática-de-literatura

Revisão Sistemática de Literatura em Bioinformática

Objetivo

Transformar um PDF bruto de um artigo de pesquisa em inglês em um conjunto de materiais de revisão em português padronizados e de alta qualidade: relatório de leitura aprofundada em Word com cada figura principal incorporada e explicada, slides de apresentação para compartilhamento e artigo de divulgação científica opcional. Projetado para pesquisadores em bioinformática que precisam de interpretação de literatura reprodutível e aprofundada.

Quando usar

Acione quando o usuário fornecer um PDF de artigo científico (ou pedir para revisar um artigo específico) e quiser qualquer um dos seguintes:

• Relatório de leitura aprofundada em Word (análise estruturada em 10 seções)
• Extração de figuras — extrair cada figura principal do PDF como imagem e explicá-las uma por uma
• Material de apresentação para reunião de grupo em PPT
• Artigo de divulgação científica para conta oficial do WeChat
• Todos os itens acima (fluxo completo)

Frases típicas do usuário:

• "Interpretar este artigo" / "Analisar este artigo"
• "Me ajude a fazer uma leitura aprofundada do artigo"
• "Extrair cada figura principal e explicar" / "Cada Figura deve ser acompanhada de explicação"
• "Gerar Word + PPT"
• "Organizar como artigo de divulgação científica"

Pré-requisitos

Ambiente Python

Qualquer Python >= 3.9 funciona. Use o interpretador que acompanha seu ambiente de execução de agente ou seu próprio virtualenv.

Instale as dependências (uma vez):

pip install pdfplumber pymupdf python-docx python-pptx

Se o PyPI estiver lento (comum na China continental), use um espelho doméstico:

pip install pymupdf -i https://mirrors.cloud.tencent.com/pypi/simple

• pymupdf (PyMuPDF) é necessário para extração de figuras — ele fornece renderização de página e inspeção de texto/gráficos em nível de coordenadas.
• pdfplumber é usado para extração de texto simples.
• python-docx / python-pptx geram os entregáveis.

Convenção de Estrutura do Projeto

Cada artigo recebe uma pasta independente sob a raiz do espaço de trabalho:

NN_YYYY-Journal-Topic/
  Original_Paper.pdf
  Journal_YYYY_Topic_LiteratureReview.docx
  Journal_YYYY_Topic_ArticleSharing.pptx
  full_text.txt              (texto extraído, intermediário)
  figures/                   (PNGs das figuras principais extraídas, intermediário)
    fig1.png, fig2.png, ...
    captions.json            (número da figura -> legenda/página/bbox manifest)
  Topic_PopularScience.html   (opcional, para WeChat OA)

• NN: número de sequência com zero à esquerda (01, 02, 03...)
• YYYY: ano de publicação
• Journal: nome abreviado do periódico (Nature, Cell, Science...)
• Topic: breve descrição do tópico em português

Fluxo de Trabalho

Passo 1: Configuração e Extração de Texto do PDF

1. Crie a pasta de saída seguindo a convenção de nomenclatura acima
2. Copie o PDF de origem para a nova pasta
3. Execute o script scripts/extract_pdf_text.py para extrair o texto completo:

   python scripts/extract_pdf_text.py "<caminho_do_pdf>" "<caminho_do_txt_de_saida>"
   

   Isso produz full_text.txt com texto extraído delimitado por página.

Passo 2: Extrair Figuras Principais do PDF

Execute o script scripts/extract_figures.py para extrair cada figura principal como PNG de alta resolução (padrão 300 DPI):

python scripts/extract_figures.py "<caminho_do_pdf>" --out "<pasta_do_artigo>/figures" --dpi 300

• Adicione --include-ed para extrair também figuras de Dados Estendidos / Suplementares.
• O script localiza legendas ("Fig. 1", "Figure 1", "圖1"), determina a extensão da coluna, une os gráficos acima da legenda e renderiza a região.
• Variantes de layout já tratadas (verificado em PDFs da Nature / Cancer Cell):
  • legenda abaixo da arte (mais comum);
  • legenda ao lado da arte (legenda no topo da coluna, figura na outra coluna);
  • legenda acima da arte;
  • "legenda na próxima página" da Cell Press: arte na página N-1, legenda no topo da página N — o script detecta que não há gráficos acima da legenda e renderiza automaticamente a arte da página anterior (status: prev-page).
  • banner do periódico: a barra colorida de largura total da Cell Press / Cancer Cell no topo da página é filtrada (status: above nunca deve contê-la).
• Se uma figura ainda contiver um cabeçalho, aumente --header-frac (ex.: 0.13 para Cancer Cell / Cell Genomics, padrão 0.055 para Nature).
• Proteção contra absorção de texto do corpo: no modo "legenda ao lado da arte", uma figura pode se estender para o parágrafo do corpo que flui abaixo dela. Blocos de texto são absorvidos apenas quando são compactos (altura curta ou largura estreita) e ≤ 4 linhas, e no modo beside apenas quando começam na borda inferior do gráfico ou acima dela. Se uma figura ainda terminar com um parágrafo de prosa, esta é a regra a ser ajustada.
• Saída: figures/figN.png + figures/captions.json (texto da legenda, página, caption_page, bbox, status de extração por figura).
• Sempre verifique os PNGs extraídos visualizando-os (ViewImage): verifique se cada imagem é a figura completa (todos os painéis, sem cortes, sem texto do corpo misturado). Se uma figura estiver mal cortada, renderize novamente essa região manualmente com PyMuPDF usando o bbox de captions.json como ponto de partida. NÃO incorpore uma imagem quebrada silenciosamente.

Passo 3: Leitura Aprofundada do Artigo

Leia o texto extraído em segmentos (200 linhas por leitura). Para CADA figura principal, visualize também o PNG extraído para entender painéis e layout. Concentre-se em extrair:

• Título, autores, periódico, DOI, data de publicação
• Resumo e principais descobertas
• Todas as Figuras (número, título, painéis, o que cada uma mostra) — verifique a legenda em captions.json com a imagem real
• Métodos (plataformas de sequenciamento, ferramentas de software, algoritmos, parâmetros)
• Informações da amostra (tamanho da coorte, tipos de tecido, tipos de sequenciamento)
• Principais resultados e significância estatística
• Limitações mencionadas pelos autores

Passo 4: Gerar Relatório de Leitura Aprofundada em Word

Siga a estrutura de 10 seções definida em references/word_structure.md.

Use o script scripts/generate_word_report.py como modelo. Copie-o para a pasta do artigo (ex.: generate_word_report.py), substitua o bloco CONTEÚDO pela análise real e execute-o com o caminho de saída:

python generate_word_report.py "<pasta_do_artigo>/Journal_YYYY_Topic_LiteratureReview.docx"

O script demonstra:

• Criação de documento python-docx com cabeçalhos estilizados
• Formatação de tabela para informações básicas e terminologia
• Listas com marcadores para pipelines de análise
• Caixas de destaque coloridas para principais descobertas
• add_figure_block(): incorpora cada PNG de figura extraída + legenda + análise em 4 partes (Pergunta de Pesquisa / Método / Resultados Principais / Interpretação)

A Seção 7 (Principais Conteúdos da Pesquisa) DEVE incorporar as imagens das figuras extraídas (figures/figN.png) — uma imagem por figura, cada uma seguida por sua análise por figura. Os caminhos das imagens e legendas vêm de figures/ e captions.json.

Regras principais de formatação:

• Cabeçalhos usam estilos Heading 1/2/3 com formatação personalizada
• Tabelas usam "Light Grid Accent 1" mais um preenchimento de cabeçalho escuro explícito (shade_cell(cell, "1A3A5C")) — o estilo interno deixa a linha de cabeçalho sem preenchimento quando o texto branco é aplicado, tornando o cabeçalho invisível no Word
• Figuras são ajustadas para largura 15,5 cm com altura máxima de ~18,5 cm (proporcional à imagem, via PIL). Um gráfico Manhattan de 4 painéis em retrato com largura total da página (mais de 21 cm de altura) transborda da página e é cortado na parte inferior — sempre limite a altura
• Tabelas com mais de uma página: keep_rows_together(table) marca a linha de cabeçalho como w:tblHeader (repete em cada página) e cada linha como w:cantSplit, para que uma tabela nunca quebre no meio de uma linha ou perca seu cabeçalho
• Termos técnicos mantêm a abreviatura em inglês, seguida de explicação em português
• Sem fabricação de dados: itens incertos marcados com "precisa confirmar"
• Verifique a saída exportando para PDF (Word COM SaveAs(..., 17)) e visualizando 2-3 páginas: linha de cabeçalho visível, figuras completas, sem transbordamento

Passo 5: Gerar Slides de Apresentação PPT

Siga a estrutura dos slides definida em references/ppt_structure.md.

Use o script scripts/generate_ppt_slides.py como modelo:

python scripts/generate_ppt_slides.py

O script demonstra:

• Criação de slides python-pptx com layouts personalizados
• Design minimalista estilo Nature/Cell (fundo branco, texto escuro)
• Slides por figura: incorpore o figures/figN.png extraído no slide, depois Título da Figura → pergunta de pesquisa → métodos → resultados → significado
• Slide final de Principais Descobertas + Impacto Científico

Passo 6: Gerar Artigo de Divulgação Científica (Opcional)

Quando o usuário quiser um artigo para WeChat OA, escreva um arquivo HTML com:

• CSS inline (WeChat remove tags <style>)
• Design mobile-first (largura máxima: 680px)
• Comunicação científica baseada em metáforas
• Cartões de dados, tabelas de comparação, linhas do tempo
• Todos os dados devem vir do artigo original, sem fabricação

Consulte references/popular_science_style.md para um guia de redação detalhado.

Passo 7: Verificação de Qualidade

Verifique:

• Todos os termos técnicos têm abreviatura em inglês + explicação
• Todas as Figuras são cobertas tanto no Word quanto no PPT
• Cada figura principal no relatório Word tem sua imagem incorporada verificada (painéis completos, sem cortes, sem texto do corpo estranho)
• Nenhum dado fabricado ou conclusões especulativas
• O pipeline de análise está completo (software → algoritmo → entrada/saída)
• Os valores estatísticos correspondem ao artigo original

Princípios de Interpretação

Siga references/interpretation_principles.md para todo o conteúdo gerado. Regras principais:

1. Mantenha abreviaturas em inglês — NÃO traduza simplesmente para português
2. Explique princípios técnicos — não apenas o quê, mas porquê e como
3. Aprofundamento — responda "por que este método?", "o que os dados mostram?", "o que isso significa?"
4. Público-alvo: engenheiros de bioinformática, pesquisadores em genômica
5. Sem fabricação — informações incertas marcadas como "precisa confirmar"

Referência de Arquivos

Arquivo	Finalidade
scripts/extract_pdf_text.py	Extrair texto completo do PDF usando pdfplumber
scripts/extract_figures.py	Extrair figuras principais como PNGs de alta resolução + manifest captions.json (PyMuPDF)
scripts/generate_word_report.py	Script modelo para geração de documento Word (incl. incorporação de figuras)
scripts/generate_ppt_slides.py	Script modelo para geração de slides PPT
references/word_structure.md	Especificação da estrutura do relatório Word em 10 seções (incl. formato do bloco por figura)
references/ppt_structure.md	Especificação da estrutura dos slides PPT
references/interpretation_principles.md	Princípios e regras de interpretação de IA
references/popular_science_style.md	Guia de redação de artigo de divulgação científica