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
-
Leia o
/input/case.json,/input/task.mdreais e os materiais do caso; não adivinhe a tarefa com base no nome do conjunto de dados. -
Dados suportados:
dataset.rowsinline, 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 cominput/, diretório atual e/input(layout Harbor); se nada for encontrado, reporte todos os caminhos tentados, sem adivinhar o conteúdo dos dados. -
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.
-
O
data_dictionarycomlabel/type/unit/missing_values/sentinelsalimenta os rótulos, tipos e regras de limpeza. Sentinelas como-999para dados numéricos devem ser declarados explicitamente, sem adivinhação global. Olabelcurto 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. -
Se o caso tiver apenas uma tarefa em linguagem natural sem
figure_requests, o Agente deve primeiro gerar um caso de trabalho em/app/workque retenha ocase_idoriginal, as referências de dados e ooutput_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=truehabilita 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=trueexplí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:
| Rota | Expressão Real |
|---|---|
bar_with_error_points | Pontos jitter brutos + barras de média + SD/SE/IC 95% explícitos |
comparison_auto | n<3 → só pontos; 3–9 → pontos + resumo declarado; cada grupo n≥10 → boxplot + jitter |
boxplot_points / violin_points | Boxplot/violino explícito + jitter; cada grupo n<3 → rebaixado para gráfico de pontos e registrado |
scatter_with_fit | Dispersão + OLS geral + banda de confiança 95%; fit_group=true → ajuste por grupo; codificação dupla: cor + forma |
line_series | Ordenado por tempo real/valores ordenados, cor + tipo de linha; pontos repetidos → tendência da média, pontos brutos preservados |
histogram | Agrupamento Sturges, pode ser facetado por grupo |
stacked_bar | Campos gerais/grupo explícitos, escala do eixo y até o total acumulado no topo das barras; sem grupo → barras horizontais ordenadas |
category_count | Contagem de categorias, barras horizontais ordenadas |
correlation_heatmap | Pearson 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
- Expressão Científica: Tipo de gráfico, agrupamento, unidades, barras de erro, marcas de significância e legenda consistentes.
- Verificação Numérica: Python recalcula independentemente média/SD/SE, OLS/Pearson e matriz de correlação; compara com resultados do R.
- 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. - Reprodução Ponta a Ponta: Execute novamente
data_prep.sh + plot.R + normalize_pdf.pya 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) eformat_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 comstatus.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ção | Comportamento |
|---|---|
| Caso não analisável, nomes de colunas duplicados, campos ausentes | Escreva erro/resultado parcial honesto e lacunas, não falsifique figuras |
| Valores ausentes/NaN/Inf/sentinela declarado | Exclua observações não utilizáveis dessa figura, mantenha número da linha original e motivo |
| Duplicatas completas | Mantidas por padrão e relatadas; remova apenas com regra explícita |
| Grupo com n=1 | Desenhe ponto bruto, SD/SE/IC como null |
| Correlação constante/variância X zero | Desenhe apenas pontos disponíveis, correlação/ajuste null |
| Categorias ou séries em excesso | Nã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 longos | Canvas 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 densa | Escala 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 tarefa | Renderize 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 ausentes | Salve 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 dados | Fallback com múltiplos diretórios base; se ainda falhar, reporte todos os caminhos tentados |
| Falha na renderização de uma figura única | Outras figuras continuam; essa figura escreve status=error e motivo real |
| Qualquer falha de plotagem ou QA | Status 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-plotlocal: R/ggplot2, tema ggprism, Arial/Cairo, svglite, Sturges, escala de tampa e regras de QA visual.- Rimagination/easyplot commit
d150e01: reutilizaeasyplot_metadata.pyeeasyplot_palette_audit.py; texto MIT original emscripts/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.