CommunityImagengithub.com

research-figure-builder

Convierte tablas de datos científicos en figuras listas para enviar a revistas: limpieza declarativa con linaje a nivel de fila, selección de gráfico según datos y objetivo, estadísticas con R/ggplot2, exportación en PDF/600dpi PNG/SVG editable, y verificación mediante doble validación numérica, auditoría de metadatos/paleta easyplot, márgenes reales de renderizado y doble ejecución completa.

¿Qué es research-figure-builder?

Esta habilidad (skill) para agentes de IA (como Claude Code o Cursor) permite transformar datos científicos sin procesar en figuras de publicación de alta calidad, listas para enviar a revistas. El objetivo no es solo 'dibujar un gráfico', sino garantizar que cada elemento visual pueda rastrearse hasta su dato fuente original y que cualquier persona pueda reproducir exactamente la misma figura usando los scripts y la instantánea adjuntos. El skill soporta múltiples plataformas (terminal con Python y R) y formatos de datos (CSV, TSV, JSON, SQLite). El proceso sigue una declaración clara de datos: especifica de forma declarativa cómo limpiar los datos (manejo de valores faltantes, duplicados, centinelas) y mantiene un linaje completo a nivel de fila desde el origen hasta el gráfico. Para la selección del gráfico, el agente elige automáticamente el tipo de visualización más adecuado (barras con puntos de error, scatter con ajuste, heatmap, etc.) basándose en el propósito declarado (comparación, correlación, tendencia, distribución) sin adivinar. La ejecución combina R/ggplot2 para la capa estadística y de trazado, con scripts de Python para la preparación de datos y la verificación. La salida incluye tres formatos (PDF, PNG 600dpi, SVG editable), un informe de QA en cuatro niveles (expresión científica, validación numérica, inspección de archivos/visual, reproducibilidad de extremo a extremo), y un archivo result.json completo con metadatos, linaje, ajustes de diseño y brechas de formato. El skill maneja casos extremos (n=1, variables constantes, demasiadas categorías, márgenes ajustados) de forma robusta, registrando siempre los ajustes y nunca recortando datos silenciosamente. Cada figura incluye su propia especificación, archivos de datos y análisis, y todo el pipeline puede reejecutarse de forma independiente.

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

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

  1. Leer el /input/case.json real, /input/task.md y los materiales del caso; no adivinar la tarea basándose en el nombre del conjunto de datos.

  2. Los datos admiten dataset.rows embebido, 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 de input/, 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.

  3. 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.
  4. De data_dictionary, los campos label/type/unit/missing_values/sentinels se utilizan para etiquetas, tipos y reglas de limpieza. Los centinelas numéricos como -999 deben declararse explícitamente; no se hacen suposiciones globales. La label corta 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.

  5. 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/work que conserva el case_id original, la referencia a los datos y el output_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=true solo 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=true está 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:

RutaExpresión real
bar_with_error_pointsPuntos jitter originales + barras de media + SD/SE/IC 95% explícitos
comparison_auton<3 solo puntos; 3–9 puntos + resumen declarado; cada grupo n≥10 usa boxplot + jitter
boxplot_points / violin_pointsBoxplot/violín explícito + jitter; cuando n<3 por grupo, se degrada a gráfico de puntos y se registra
scatter_with_fitDispersión + OLS global + banda de confianza del 95%; fit_group=true solo entonces ajuste por grupo; codificación dual color + forma
line_seriesOrdenado por tiempo real/numérico ordenado, color + tipo de línea; puntos repetidos dan tendencia de media, conservando puntos originales
histogramAgrupación de Sturges, posible faceta por grupo
stacked_barCampos de grupo/componente explícitos, escala de marcas en la parte superior según total acumulado; sin grupo, barras ordenadas
category_countConteo por categoría, barras ordenadas
correlation_heatmapPearson 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

  1. Expresión científica: coherencia del tipo de gráfico, agrupación, unidades, barras de error, significación y leyenda.
  2. 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.
  3. 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.
  4. Reproducibilidad de extremo a extremo: volver a ejecutar data_prep.sh + plot.R + normalize_pdf.py desde 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) y format_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 con status.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ónComportamiento
Caso no analizable, nombres de columna duplicados, campos faltantesEscribir error/resultado parcial honesto y brechas, no falsificar figuras
Valores faltantes/NaN/Inf/centinelas declaradosExcluir esa observación no utilizable para la figura, conservar número de fila y razón
Duplicados exactosConservar por defecto e informar; eliminar solo si hay regla explícita
Un grupo con n=1Dibujar puntos originales, SD/SE/IC como null
Correlación constante/varianza X ceroDibujar solo puntos utilizables, correlación/ajuste como null
Demasiadas categorías o seriesNo 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 largasEl 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 densasMuestrear 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ónRenderizar 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, pypdfGuardar 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álidaBuscar en múltiples directorios base; si aún falla, informar todas las rutas intentadas
Fallo de renderizado de una figuraLas demás figuras continúan; para esa figura, escribir status=error y la razón real
Cualquier figura o QA fallaEl 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-plot local: R/ggplot2, tema ggprism, Arial/Cairo, svglite, Sturges, reglas de cobertura de marcas y QA visual.
  • Rimagination/easyplot commit d150e01: reutiliza easyplot_metadata.py y easyplot_palette_audit.py; licencia MIT en scripts/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.

Skills relacionados