Visualización de datos científicos (research-figure-builder)
El objetivo no es "dibujar un gráfico", sino que cada elemento de datos en la figura pueda rastrearse hasta los datos fuente, y que otros puedan reproducir el mismo entregable utilizando la instantánea y los scripts adjuntos.
Cuándo usar
- Se proporcionan tablas de datos científicos y una tarea de generación de figuras, y se necesitan figuras reales, estadísticas robustas, leyendas y evidencia de reproducibilidad.
- Se necesitan comparaciones, correlaciones, tendencias, distribuciones, composiciones, conteos por categoría o mapas de calor de correlación.
- Se necesita especificar el ancho de columna de la revista, el lienzo, los DPI, la fuente o el formato de exportación.
- Se necesita identificar valores faltantes, no finitos, duplicados, muestras pequeñas y categorías excesivas, en lugar de eliminar datos silenciosamente.
No se utiliza para diseño experimental, innovación en métodos estadísticos, retoque estético de imágenes o paneles interactivos. Las marcas de significación solo se aceptan si ya se proporcionan con el método estadístico y el criterio de corrección; nunca se generan asteriscos automáticamente.
Entrada
-
Leer el
/input/case.jsonreal,/input/task.mdy los materiales del caso; no adivinar la tarea basándose en el nombre del conjunto de datos. -
Los datos admiten
dataset.rowsembebido, CSV, TSV, JSON y SQLite de solo lectura; las rutas relativas se resuelven según el directorio del caso. Cuando el caso se migra a directorios como/app/work, se busca automáticamente en los directorios ancestros en busca deinput/, en el directorio actual y en/input(estructura Harbor). Si no se encuentra nada en ninguna parte, se informan todas las rutas intentadas y no se adivina el contenido de los datos. -
Las solicitudes de figura
figure_requests[]admiten: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.
-
De
data_dictionary, los camposlabel/type/unit/missing_values/sentinelsse utilizan para etiquetas, tipos y reglas de limpieza. Los centinelas numéricos como-999deben declararse explícitamente; no se hacen suposiciones globales. Lalabelcorta del diccionario de datos tiene prioridad como nombre de eje en mapas de calor, etc.; los nombres de columna originales se conservan en el linaje y el análisis. -
Si el caso solo tiene una tarea en lenguaje natural y carece de
figure_requests, el Agente primero genera un caso de trabajo en/app/workque conserva elcase_idoriginal, la referencia a los datos y eloutput_contract, y solo completa las órdenes de trabajo estructuradas. Las rutas de datos relativas no necesitan reescribirse (se resuelven según el punto 2). Se registra esta conversión en la evidencia, pero no se inventan datos. Ejemplos de mapeo de órdenes de trabajo (manteniendo la semántica original de la tarea, sin añadir conclusiones no mencionadas en la tarea):La tarea dice "Comparar las diferencias de expresión de tres genotipos, barras de error con error estándar" →
{"figure_id":"F1","purpose":"comparison","x":"Genotipo","y":"Expresión","error_bar":"se", "x_label":"Genotipo","y_label":"Expresión","title":"Comparación de expresión entre tres genotipos"}La razón de la elección del gráfico se escribe en el registro de conversión de la orden de trabajo: purpose=comparison y barra de error explícita →
bar_with_error_points(barras de media + todos los puntos originales); se rechaza el gráfico circular (las categorías no ordenadas no se codifican por ángulo).La tarea dice "Asociación entre largo y ancho de pétalo por especie, dar ajuste y banda de confianza" →
{"figure_id":"F2","purpose":"correlation","x":"petal_length_cm","y":"petal_width_cm", "group":"species","fit_group":true,"x_label":"Largo del pétalo","y_label":"Ancho del pétalo"}Se rechaza el gráfico de líneas (observaciones no ordenadas no se conectan);
fit_group=truesolo entonces se ajusta por grupo.La tarea dice "Exploratoriamente, ver la estructura de correlación de todas las variables" →
{"figure_id":"F3","purpose":"correlation","chart_hint":"heatmap"}(si las variables no se enumeran, el diccionario de datos identifica automáticamente las columnas continuas y registra esa decisión).
Ejecución
Ejecutar directamente en el entorno de producción:
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
Dependencias: Rscript + ggplot2 + ggprism + svglite + jsonlite + systemfonts; la auditoría Python usa Pillow y pypdf. Si faltan dependencias, se guardan las instantáneas, el plan de ejecución y los scripts, el estado se marca como parcialmente completado y se listan los elementos faltantes. Si el contenedor carece de paquetes R pero tiene red, se puede instalar primero con un arranque en frío y luego re-ejecutar:
Rscript -e 'install.packages(c("ggplot2","ggprism","svglite","jsonlite","systemfonts"), repos="https://cloud.r-project.org")'
python3 -m pip install --user Pillow pypdf
Si la instalación falla, no bloquea: el resultado de la detección de dependencias se escribe en dependencies.json, y los materiales de entrega se degradan honestamente según el criterio de finalización parcial.
Flujo de trabajo
1. Congelar entrada y contrato
Guardar source_data.tsv, fuente original/hash, run_plan.json, reglas de limpieza y versiones de dependencias. Vincular dinámicamente el output_contract del caso; los campos no producidos se indican explícitamente en status.unmet.
2. Shell/Python solo para preparar datos
data_prep.sh llama a scripts/prepare_data.py para generar un TSV limpio, sin dibujar gráficos:
- Marcadores de faltantes predeterminados: vacío, NA, N/A, NaN, null, None,
.; - Los valores no finitos y no analizables numéricamente se excluyen y se registran con el número de fila y la razón;
- Las filas completamente duplicadas se conservan por defecto y se informan; solo se eliminan si
drop_duplicates=trueestá explícito; - Las categorías no se truncan a las primeras N; si hay muchas categorías, se conservan todas y se ajusta el diseño;
- Salida:
cleaned_data.tsv,figure_N.tsv,figure_N_lineage.json,data_quality.json.
3. R/ggplot2: Estadísticas y trazado
plot.R solo lee TSV y el plan de ejecución, y llama a theme.R:
| Ruta | Expresión real |
|---|---|
bar_with_error_points | Puntos jitter originales + barras de media + SD/SE/IC 95% explícitos |
comparison_auto | n<3 solo puntos; 3–9 puntos + resumen declarado; cada grupo n≥10 usa boxplot + jitter |
boxplot_points / violin_points | Boxplot/violín explícito + jitter; cuando n<3 por grupo, se degrada a gráfico de puntos y se registra |
scatter_with_fit | Dispersión + OLS global + banda de confianza del 95%; fit_group=true solo entonces ajuste por grupo; codificación dual color + forma |
line_series | Ordenado por tiempo real/numérico ordenado, color + tipo de línea; puntos repetidos dan tendencia de media, conservando puntos originales |
histogram | Agrupación de Sturges, posible faceta por grupo |
stacked_bar | Campos de grupo/componente explícitos, escala de marcas en la parte superior según total acumulado; sin grupo, barras ordenadas |
category_count | Conteo por categoría, barras ordenadas |
correlation_heatmap | Pearson pairwise-complete; columnas constantes/pares válidos insuficientes se marcan como NA; escala de color divergente fija [-1,1] con barra de color |
Para n=1, la SD/SE/IC, la correlación de variables constantes y el ajuste con varianza X cero son todos null, no se escriben como 0. Las barras comienzan en 0, la marca más alta cubre la parte superior de la barra y las barras de error.
Defensa automática de legibilidad (no truncar datos): el tamaño de letra base de la figura es impulsado por min(ancho, 1.55×alto); los lienzos anchos y planos no aumentan el tamaño de letra con el ancho; el diámetro del punto de dispersión/línea se contrae por densidad según "área de trazado disponible / número de puntos" (mínimo 0.9 mm); las categorías >8 cambian a diseño horizontal y aumentan automáticamente la altura del lienzo según el número de filas (límite max_height_mm); cuando el espacio entre filas es insuficiente, se contrae el tamaño de letra de la etiqueta de categoría según el espacio entre filas (mínimo 6pt); cuando se predice superposición de etiquetas en diseño vertical, se rotan 45°; los mapas de calor aumentan la altura del lienzo según el número de variables y el ancho; las etiquetas de los ejes usan preferentemente el nombre corto del diccionario de datos y eliminan las unidades entre paréntesis; cuando la proyección horizontal no cabe, se elevan a 90°; el tamaño de letra se contrae según el ancho de la celda; los números dentro de las celdas tienen un diámetro determinado por el ancho de la celda (límite superior ~9pt, se omiten cuando la celda <5.5 mm o variables >12); las marcas de tiempo se muestrean según el ancho del lienzo y se presentan en formato de dos líneas "MM-DD / AAAA"; el título se ajusta al ancho del lienzo. Cada ajuste se escribe en layout_adjustment, analysis notes y warnings, y es rastreable.
4. Exportación en tres formatos
Por figura, se generan por defecto:
figure_N.pdf: Cairo PDF, se verifica el tamaño de página real y la evidencia de incrustación de fuentes.figure_N.png: 600 dpi por defecto, la tarea puede especificar mayor o menor pero no inferior a 300 dpi.figure_N.svg: svglite, conserva<text>editable.figure_N.tsv+figure_N.csv,figure_N_spec.json,figure_N_analysis.json,figure_N_lineage.json.
Incluso si el usuario solo solicita PDF, se conservan la previsualización PNG y el SVG editable. Graduación de formatos de exportación: si falta un formato solicitado y que esté dentro del rango compatible (PDF/PNG/SVG), esa figura no puede marcarse como completa; si se solicita un formato no compatible (ej. emf), se registra como brecha fuera de rango (format_gaps) y se entregan los tres formatos predeterminados, sin ignorar silenciosamente ni falsificar.
5. QA en cuatro niveles
- Expresión científica: coherencia del tipo de gráfico, agrupación, unidades, barras de error, significación y leyenda.
- Validación numérica: Python recalcula de forma independiente media/SD/SE, OLS/Pearson y matriz de correlación, y se compara con los resultados de R.
- Inspección de archivos y visual: easyplot verifica tamaño/DPI/fuente PDF/texto SVG; verifica que PNG no esté en blanco, márgenes reales y contexto de paleta. Semántica de márgenes: gráfico en blanco o contenido pegado/recortado (<0.02 in del lienzo) se considera fallo; márgenes inferiores a 0.1 in solo se marcan con bandera
tight, no se degrada un gráfico válido a parcial. - Reproducibilidad de extremo a extremo: volver a ejecutar
data_prep.sh + plot.R + normalize_pdf.pydesde la instantánea original adjunta, y comparar SHA-256 de TSV/CSV de trazado, linaje, JSON de estadísticas, PDF, PNG, SVG. La normalización de PDF solo fija CreationDate/ModDate de Cairo/pypdf a Unix epoch, no modifica páginas, fuentes o contenido gráfico.
Una vez completadas las comprobaciones automáticas, el Agente debe inspeccionar el PNG real (y renderizar el PDF si es necesario) para verificar superposición de etiquetas, caracteres ilegibles, solapamiento y semántica científica. La verificación de márgenes de píxeles no equivale a una revisión visual humana/multimodal.
Salida
result.json conserva case_id y el contrato de salida original, e incluye:
figures: ruta por figura, tipo de gráfico real, registro de preparación, análisis R, leyenda independiente, metadatos/hash de archivo, QA, resultado de reproducción completa,layout_adjustment(registro de adaptación de diseño) yformat_gaps(brechas de formato fuera de rango).data_to_visual_map: columna fuente → canal visual, TSV de trazado y linaje a nivel de fila.baseline_comparison: comparación de defensa determinista en siete dimensiones contra un agente base/esquema de visualización genérico (selección de gráfico/eje/legibilidad de codificación/anotación/leyenda/especificaciones de exportación/evidencia de reproducibilidad/ degradación de anomalías), cada elemento anota fallos típicos, manejo de esta Skill y ubicación de la evidencia; la comparación justa del lado de la plataforma la ejecuta la organización por su cuenta; esta tabla no inventa números de referencia.evidence_map: instantánea fuente, plan de ejecución, hash de reglas, dependencias, scripts y comandos de reproducción.status.notes: brechas, explicaciones e incertidumbres coherentes constatus.overall.
Todos los archivos de entrega se encuentran en /app/output. Se puede re-ejecutar de forma independiente:
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 .
Manejo de excepciones
| Situación | Comportamiento |
|---|---|
| Caso no analizable, nombres de columna duplicados, campos faltantes | Escribir error/resultado parcial honesto y brechas, no falsificar figuras |
| Valores faltantes/NaN/Inf/centinelas declarados | Excluir esa observación no utilizable para la figura, conservar número de fila y razón |
| Duplicados exactos | Conservar por defecto e informar; eliminar solo si hay regla explícita |
| Un grupo con n=1 | Dibujar puntos originales, SD/SE/IC como null |
| Correlación constante/varianza X cero | Dibujar solo puntos utilizables, correlación/ajuste como null |
| Demasiadas categorías o series | No truncar; aumentar automáticamente la altura del lienzo/diseño horizontal/contraer tamaño de letra de etiqueta/facetar y registrar layout_adjustment; si se supera la altura máxima, indicar que las etiquetas pueden seguir siendo densas |
| Muchas variables en heatmap/etiquetas largas | El lienzo se eleva según el número de variables y el ancho; usar nombre corto del diccionario + eliminar unidades entre paréntesis; ángulo 45°→90° adaptativo; tamaño de letra se contrae según el ancho de celda (≥6pt); >12 variables omiten números dentro de celdas |
| Marcas de fecha densas | Muestrear marcas según el ancho del lienzo, etiquetas de dos líneas MM-DD/AAAA |
| Se solicita formato de exportación no compatible (ej. emf) | Registrar brecha fuera de rango format_gaps y entregar tres formatos predeterminados, no marcar como parcial, no silenciar |
| La tarea proporciona resultados de significación | Renderizar tal cual: emparejado → línea de gancho + anotación; categoría única → letras al final del grupo; la leyenda indica el método y "no se realizó ninguna prueba", nunca autogenerar asteriscos |
| Faltan paquetes R, fuentes, Pillow, pypdf | Guardar materiales re-ejecutables e indicar elementos incompletos; si hay red, se puede instalar con comando de arranque en frío y re-ejecutar; si matplotlib está disponible, degradar a renderizado PNG real (300dpi+, solo PNG, las brechas de PDF/SVG se registran honestamente sin falsificar) |
| Ruta de archivo de datos no válida | Buscar en múltiples directorios base; si aún falla, informar todas las rutas intentadas |
| Fallo de renderizado de una figura | Las demás figuras continúan; para esa figura, escribir status=error y la razón real |
| Cualquier figura o QA falla | El estado general es parcial, no completo |
Autocomprobación
# Ejecutar desde la raíz del repositorio
python3 -B answer/060_科研数据可视化/scripts/test_pipeline.py
python3 answer/_shared/verify.py --only 060
El ejemplo mínimo debe cumplir: contrato general PASS, prueba específica de figuras PASS, tres formatos para cada figura presentes, QA todo aprobado, dos ejecuciones completas con el mismo hash. En ejecuciones repetidas, solo generated_at puede cambiar.
Fuente del método y licencia
sci-plotlocal: R/ggplot2, tema ggprism, Arial/Cairo, svglite, Sturges, reglas de cobertura de marcas y QA visual.- Rimagination/easyplot commit
d150e01: reutilizaeasyplot_metadata.pyyeasyplot_palette_audit.py; licencia MIT enscripts/easyplot-LICENSE.txt. - Las etiquetas en chino son un requisito de fidelidad de la entrada de esta tarea: predeterminado Arial; solo cuando las etiquetas reales necesitan CJK, se elige una fuente china real y se registra; no se considera la falla de caracteres faltantes como un éxito.
Ejemplo de invocación mínima
cd answer/060_科研数据可视化
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
El ejemplo son datos sintéticos de 24 filas, que incluyen una comparación entre grupos y un gráfico de correlación; la salida del ejemplo solo se usa para regresión, no es un resultado de caso formal.