CommunityImagemgithub.com

research-figure-builder

Transforma tabelas de dados científicos em figuras prontas para submissão: limpeza declarativa com linhagem em nível de linha, seleção de gráfico baseada em dados e propósito, plotagem estatística em R/ggplot2, exportação nos formatos PDF/600 dpi PNG/SVG editável, com verificação numérica independente, auditoria de metadados/paleta easyplot, margens de renderização reais e duas rodadas completas de reexecução.

O que é research-figure-builder?

Esta Skill automatiza a criação de figuras científicas prontas para publicação a partir de dados tabulares de pesquisa. Diferente de ferramentas genéricas de plotagem, ela estabelece uma cadeia de custódia completa: cada elemento visual é rastreado até sua origem de dados, e todos os resultados são acompanhados por instantâneos e scripts que permitem a qualquer pessoa reproduzir exatamente a mesma figura. A Skill oferece suporte a uma ampla gama de tipos de gráfico, incluindo gráficos de barras com pontos de erro, gráficos de dispersão com ajuste, mapas de calor de correlação e séries temporais, e escolhe automaticamente a melhor representação com base no propósito da análise (comparação, correlação, tendência, distribuição, etc.). Ela executa uma limpeza de dados declarativa, documenta cada transformação com linhagem em nível de linha, e gera saídas nos formatos PDF, PNG (600 dpi) e SVG editável, garantindo conformidade com especificações de revistas (largura de coluna, DPI, fonte). A Skill é executada em um pipeline R/ggplot2 e Python, realiza uma rigorosa garantia de qualidade em quatro níveis (validação científica, verificação numérica independente, inspeção visual e reprodução de ponta a ponta), e lida com casos extremos como dados ausentes, amostras pequenas e muitos grupos sem truncar silenciosamente os dados.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Hao-IANWY/research-figure-builder/tree/HEAD

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Visualização de Dados Científicos (research-figure-builder)

O objetivo não é "desenhar um gráfico", mas sim garantir que cada elemento de dados no gráfico possa ser rastreado até a fonte de dados original e que outras pessoas possam reproduzir exatamente o mesmo artefato usando os instantâneos e scripts fornecidos.

Quando Usar

  • Entrada de tabelas de dados científicos e tarefas de criação de gráficos, que exigem figuras reais, estatísticas, legendas e evidências de reprodutibilidade;
  • Necessidade de comparar, correlacionar, mostrar tendências, distribuições, composições, contagens de categorias ou mapas de calor de correlação;
  • Necessidade de especificar largura de coluna da revista, canvas, DPI, fonte ou formato de exportação;
  • Necessidade de identificar valores ausentes, não finitos, duplicatas, amostras pequenas e categorias em excesso, em vez de remover dados silenciosamente.

Não é para desenho experimental, inovação de métodos estatísticos, pós-processamento estético de imagens ou dashboards interativos. Marcas de significância são aceitas apenas se fornecidas com o método estatístico/correção, e asteriscos não são gerados automaticamente.

Entrada

  1. Leia o /input/case.json, /input/task.md reais e os materiais do caso; não adivinhe a tarefa com base no nome do conjunto de dados.

  2. Dados suportados: dataset.rows inline, CSV, TSV, JSON e SQLite somente leitura; caminhos relativos são resolvidos a partir do diretório do caso; quando o caso é movido para /app/work, há fallback automático para diretórios ancestrais com input/, diretório atual e /input (layout Harbor); se nada for encontrado, reporte todos os caminhos tentados, sem adivinhar o conteúdo dos dados.

  3. O pedido de figura figure_requests[] suporta:

    • figure_id, purpose, chart_hint/chart_type;
    • x, y, group, variables, unit_id/replicate_unit, label;
    • x_label, y_label, x_unit, unit/y_unit, title, panel;
    • error_bar=sd|se|ci95|none, fit_group, significance;
    • venue, width_mm, height_mm, dpi, format/formats.
  4. O data_dictionary com label/type/unit/missing_values/sentinels alimenta os rótulos, tipos e regras de limpeza. Sentinelas como -999 para dados numéricos devem ser declarados explicitamente, sem adivinhação global. O label curto do dicionário de dados tem precedência como nome de exibição em eixos (por exemplo, heatmaps), enquanto os nomes das colunas originais são preservados na linhagem e na análise.

  5. Se o caso tiver apenas uma tarefa em linguagem natural sem figure_requests, o Agente deve primeiro gerar um caso de trabalho em /app/work que retenha o case_id original, as referências de dados e o output_contract, preenchendo apenas as requisições de figura estruturadas; caminhos de dados relativos não precisam ser reescritos (fallback conforme regra 2), documente essa conversão na evidência, não invente dados. Exemplo de mapeamento de requisição (mantendo a semântica original da tarefa, sem adicionar conclusões não mencionadas):

    Tarefa diz: "Comparar diferenças de expressão gênica entre três genótipos, usar erro padrão" →

    {"figure_id":"F1","purpose":"comparison","x":"Genótipo","y":"Expressão","error_bar":"se",
     "x_label":"Genótipo","y_label":"Expressão","title":"Comparação da Expressão Gênica entre Três Genótipos"}
    

    Justificativa do gráfico registrada no registro de conversão: purpose=comparison e barra de erro explícita → bar_with_error_points (média em barra + todos os pontos brutos); rejeitar gráfico de pizza (categorias não ordenadas não devem usar codificação angular).

    Tarefa diz: "Associação entre comprimento e largura da pétala, colorir por espécie, mostrar ajuste e banda de confiança" →

    {"figure_id":"F2","purpose":"correlation","x":"petal_length_cm","y":"petal_width_cm",
     "group":"species","fit_group":true,"x_label":"Comprimento da Pétala","y_label":"Largura da Pétala"}
    

    Rejeitar gráfico de linhas (observações não ordenadas não devem ser conectadas); fit_group=true habilita ajuste por grupo.

    Tarefa diz: "Exploratoriamente, ver a estrutura de correlação de todas as variáveis" → {"figure_id":"F3","purpose":"correlation","chart_hint":"heatmap"} (se as variáveis não forem listadas, o dicionário de dados as identifica automaticamente como colunas contínuas, e essa decisão é registrada).

Execução

Execute diretamente no ambiente de produção:

python3 -B /skills/weekly-skill/scripts/pipeline.py \
  --case /input/case.json --task /input/task.md --out /app/output
python3 -B /skills/weekly-skill/scripts/validate.py \
  --case /input/case.json --result /app/output/result.json
python3 -B /skills/weekly-skill/scripts/validate_figures.py \
  --result /app/output/result.json

Dependências: Rscript + ggplot2 + ggprism + svglite + jsonlite + systemfonts; auditoria Python usa Pillow e pypdf. Se faltarem dependências, salve instantâneos, plano de execução e scripts, marque o estado como parcialmente concluído e liste os itens ausentes. Se o contêiner não tiver pacotes R mas tiver rede, instale com inicialização a frio e reexecute:

Rscript -e 'install.packages(c("ggplot2","ggprism","svglite","jsonlite","systemfonts"), repos="https://cloud.r-project.org")'
python3 -m pip install --user Pillow pypdf

Falhas de instalação não bloqueiam: o resultado da detecção de dependências é escrito em dependencies.json, e os artefatos são entregues com rebaixamento honesto de acordo com o critério de conclusão parcial.

Fluxo

1. Congelar Entrada e Contrato

Salve source_data.tsv, fonte original/hash, run_plan.json, regras de limpeza e versões de dependências. Vincule dinamicamente o output_contract do caso; campos não produzidos entram explicitamente em status.unmet.

2. Shell/Python Somente para Preparação de Dados

data_prep.sh chama scripts/prepare_data.py, gera TSV limpo, não plota:

  • Marcadores de ausência padrão: vazio, NA, N/A, NaN, null, None, .;
  • Valores não finitos e números não analisáveis são excluídos, linhas originais e motivo registrados;
  • Linhas completamente duplicadas são mantidas por padrão e relatadas; removidas apenas com drop_duplicates=true explícito;
  • Categorias não são truncadas para os N primeiros; categorias em excesso são todas mantidas com ajuste de layout;
  • Saída: cleaned_data.tsv, figure_N.tsv, figure_N_lineage.json, data_quality.json.

3. Estatística e Plotagem em R/ggplot2

plot.R lê apenas TSV e plano de execução, chama theme.R:

RotaExpressão Real
bar_with_error_pointsPontos jitter brutos + barras de média + SD/SE/IC 95% explícitos
comparison_auton<3 → só pontos; 3–9 → pontos + resumo declarado; cada grupo n≥10 → boxplot + jitter
boxplot_points / violin_pointsBoxplot/violino explícito + jitter; cada grupo n<3 → rebaixado para gráfico de pontos e registrado
scatter_with_fitDispersão + OLS geral + banda de confiança 95%; fit_group=true → ajuste por grupo; codificação dupla: cor + forma
line_seriesOrdenado por tempo real/valores ordenados, cor + tipo de linha; pontos repetidos → tendência da média, pontos brutos preservados
histogramAgrupamento Sturges, pode ser facetado por grupo
stacked_barCampos gerais/grupo explícitos, escala do eixo y até o total acumulado no topo das barras; sem grupo → barras horizontais ordenadas
category_countContagem de categorias, barras horizontais ordenadas
correlation_heatmapPearson pairwise-complete; colunas constantes/pares válidos insuficientes → NA; escala divergente fixa [-1,1] com barra de cores

n=1 de SD/SE/IC, correlação de variável constante e ajuste de variância X zero são null, não escritos como 0. Barras/barras horizontais começam em 0, a escala máxima cobre o topo das barras e barras de erro.

Defesas automáticas de legibilidade (sem truncar dados): tamanho base da fonte de toda a figura é impulsionado por min(largura, 1.55×altura); canvas largo não amplia fonte; diâmetro dos pontos de dispersão/linha é reduzido pela densidade "área de plotagem disponível / número de pontos" (mínimo 0,9mm); categorias >8 viram layout horizontal e canvas é automaticamente aumentado em altura pelo número de linhas (teto max_height_mm); quando a distância entre linhas é insuficiente, o tamanho da fonte do rótulo da categoria é reduzido (mínimo 6pt); quando o layout vertical prevê sobreposição de rótulos, eles são rotacionados 45°; heatmaps aumentam o canvas em altura com base no número de variáveis e largura, os rótulos dos eixos usam preferencialmente nomes curtos do dicionário de dados e removem unidades entre parênteses, quando a projeção horizontal não cabe, sobem para 90°, o tamanho da fonte é reduzido pela largura da célula, números dentro das células são dimensionados pela largura da célula (limite ~9pt, células <5.5mm ou variáveis >12 → omitidos); a escala do eixo temporal é reduzida com limite na largura do canvas e usa rótulos de duas linhas "MM-DD / AAAA". Cada ajuste é escrito em layout_adjustment, notas e avisos da análise, rastreável.

4. Exportação em Três Formatos

Cada figura gera por padrão:

  • figure_N.pdf: Cairo PDF, verifica o tamanho real da página e evidências de incorporação de fontes;
  • figure_N.png: padrão 600 dpi, tarefa pode especificar maior ou menor, mas não inferior a 300 dpi;
  • figure_N.svg: svglite, preserva <text> editável;
  • figure_N.tsv + figure_N.csv, figure_N_spec.json, figure_N_analysis.json, figure_N_lineage.json.

Mesmo que o usuário solicite apenas PDF, mantenha visualização PNG e SVG editável. Graduação dos formatos de exportação: se um formato solicitado dentro do suporte (PDF/PNG/SVG) estiver ausente, essa figura não pode ser marcada como completa; formatos não suportados (por exemplo, emf) são registrados como format_gaps lacuna fora do escopo e os três formatos padrão são entregues, sem ignorar silenciosamente nem falsificar.

5. QA em Quatro Níveis

  1. Expressão Científica: Tipo de gráfico, agrupamento, unidades, barras de erro, marcas de significância e legenda consistentes.
  2. Verificação Numérica: Python recalcula independentemente média/SD/SE, OLS/Pearson e matriz de correlação; compara com resultados do R.
  3. Verificação de Arquivo e Visual: easyplot verifica tamanho/DPI/fonte PDF/texto SVG; verifica PNG não branco, margens reais e contexto da paleta de cores. Semântica de margem: gráfico em branco ou conteúdo colado/cortado (distância do canvas <0.02 pol) → falha; margem inferior a 0.1 pol → apenas sinal tight, não rebaixa gráfico aprovado para partial.
  4. Reprodução Ponta a Ponta: Execute novamente data_prep.sh + plot.R + normalize_pdf.py a partir do instantâneo original incluído; compare SHA-256 dos TSV/CSV de plotagem, linhagem, JSON de estatísticas, PDF, PNG, SVG. A normalização do PDF apenas fixa CreationDate/ModDate do Cairo/pypdf para a época Unix, sem alterar página, fonte ou conteúdo gráfico.

Após a verificação automática, o Agente deve inspecionar o PNG real (renderizar PDF se necessário), verificar sobreposição de rótulos, caracteres ilegíveis, oclusão e semântica científica. A verificação de margem de pixel não substitui a inspeção visual humana/multimodal.

Saída

result.json mantém case_id e o contrato de saída original, e inclui:

  • figures: rota por figura, tipo de gráfico real, registro de preparação, análise R, legenda independente de figura, metadados/hash de arquivo, QA, resultado de reprodução de cadeia completa, layout_adjustment (registro de adaptação de layout) e format_gaps (lacunas de formato fora do escopo);
  • data_to_visual_map: coluna fonte → canal visual, TSV de plotagem e linhagem em nível de linha;
  • baseline_comparison: comparação de defesa determinística em sete dimensões com Agente base/esquema de plotagem genérica (seleção de gráfico/eixo/codificação legibilidade/rótulo legenda/especificação de exportação/evidência de reprodução/rebaixamento de anomalia); cada item nota falha típica, tratamento desta Skill e localização da evidência; a comparação justa do lado da plataforma é executada pela própria organização, esta tabela não inventa números de linha de base;
  • evidence_map: instantâneos fonte, plano de execução, hash de regras, dependências, scripts e comandos de reprodução;
  • declaração de status: lacunas, explicações e incertezas consistentes com status.overall.

Todos os arquivos de entrega estão em /app/output. Pode ser executado independentemente:

cd /app/output
bash data_prep.sh
Rscript plot.R
python3 -B scripts/normalize_pdf.py --plan run_plan.json --out .
python3 -B scripts/audit_outputs.py --plan run_plan.json --out .

Tratamento de Exceções

SituaçãoComportamento
Caso não analisável, nomes de colunas duplicados, campos ausentesEscreva erro/resultado parcial honesto e lacunas, não falsifique figuras
Valores ausentes/NaN/Inf/sentinela declaradoExclua observações não utilizáveis dessa figura, mantenha número da linha original e motivo
Duplicatas completasMantidas por padrão e relatadas; remova apenas com regra explícita
Grupo com n=1Desenhe ponto bruto, SD/SE/IC como null
Correlação constante/variância X zeroDesenhe apenas pontos disponíveis, correlação/ajuste null
Categorias ou séries em excessoNão trunque; aumente canvas automaticamente / layout horizontal / reduza tamanho da fonte do rótulo / facete e registre layout_adjustment; excedendo altura máxima, indique que os rótulos podem ainda estar densos
Heatmap com muitas variáveis/rótulos longosCanvas aumenta em altura por número de variáveis + largura; nomes curtos do dicionário + remova unidades entre parênteses; ângulo 45°→90° adaptativo; tamanho da fonte reduzido pela largura da célula (≥6pt); >12 variáveis omitem números dentro das células
Escala de data densaEscala reduzida com limite na largura do canvas, rótulos de duas linhas MM-DD/AAAA
Requisição de formato de exportação não suportado (por exemplo, emf)Registre format_gaps lacuna fora do escopo e entregue três formatos padrão, não julgue partial, não silencie
Resultados de significância fornecidos pela tarefaRenderize transparentemente: emparelhado → linha de suporte + anotação, categoria única → letras no final do grupo; legenda nota método e "nenhum teste calculado", jamais crie asteriscos próprios
Pacotes R, fontes, Pillow, pypdf ausentesSalve materiais reproduzíveis e itens claramente incompletos; com rede, instale com comando de inicialização a frio e reexecute; se matplotlib estiver disponível, rebaixe para renderização de PNG real (300dpi+, apenas PNG, lacunas PDF/SVG registradas honestamente, sem falsificação)
Falha no caminho do arquivo de dadosFallback com múltiplos diretórios base; se ainda falhar, reporte todos os caminhos tentados
Falha na renderização de uma figura únicaOutras figuras continuam; essa figura escreve status=error e motivo real
Qualquer falha de plotagem ou QAStatus geral é partial, não complete

Autoverificação

# Execute a partir do diretório raiz do repositório
python3 -B answer/060_VisualizacaoDadosCientificos/scripts/test_pipeline.py
python3 answer/_shared/verify.py --only 060

Exemplo mínimo deve atender: contrato geral PASS, tarefa específica de figura PASS, três formatos existentes para cada figura, QA completo, hashes consistentes em duas execuções de cadeia completa. Apenas generated_at pode mudar em execuções repetidas.

Fonte do Método e Licença

  • sci-plot local: R/ggplot2, tema ggprism, Arial/Cairo, svglite, Sturges, escala de tampa e regras de QA visual.
  • Rimagination/easyplot commit d150e01: reutiliza easyplot_metadata.py e easyplot_palette_audit.py; texto MIT original em scripts/easyplot-LICENSE.txt.
  • Rótulos em chinês são um requisito de fidelidade de entrada desta tarefa: padrão Arial; somente quando os rótulos reais precisam de CJK, escolha uma fonte chinesa real e registre, não trate fallback de falta de glifo como sucesso.

Exemplo Mínimo de Chamada

cd answer/060_VisualizacaoDadosCientificos
python3 -B scripts/pipeline.py \
  --case examples/min_example/input/case.json --out /tmp/figure060-demo
python3 -B scripts/validate.py \
  --case examples/min_example/input/case.json --result /tmp/figure060-demo/result.json
python3 -B scripts/validate_figures.py --result /tmp/figure060-demo/result.json

O exemplo são dados sintéticos de 24 linhas, contendo uma comparação entre grupos e um gráfico de correlação; a saída do exemplo é apenas para regressão, não resultado de caso formal.

Habilidades Relacionadas