DrNbnonono/paper-figures

Figuras para artículos

Una figura es un argumento hecho visible. Se gana su lugar cuando un lector que la mira durante cinco segundos, antes de leer la leyenda, puede expresar la afirmación que hace. Todo en este skill sirve para esa prueba.

El estilo que codifica es el que comparten los artículos sólidos de S&P, USENIX Security, CCS y NDSS: pequeño, vectorial, figuras de dos columnas; pocos elementos visuales; etiquetas directas; color seguro para impresión; leyendas que expresan la conclusión en lugar de describir los ejes.

Principio fundamental

Una figura = una afirmación = un mensaje en la leyenda.

Si es necesario mostrar dos afirmaciones, dibuja dos paneles o dos figuras. Una figura que muestra tres cosas no se lee como ninguna de ellas.

Puntos no negociables

1. Un mensaje por figura. La primera frase de la leyenda lo expresa; el gráfico lo respalda.
2. Dibujar al tamaño de impresión. Una figura de una columna mide 3.5 pulgadas de ancho (IEEE), 3.33 pulgadas (ACM sigconf), 3.4 pulgadas (USENIX). Nunca dibujes grande y reduzcas en LaTeX: las fuentes se reducen por debajo del mínimo de 7 pt.
3. Salida vectorial (.pdf desde matplotlib) para cualquier cosa con texto o líneas. Solo raster a 300 dpi para fotografías y capturas de pantalla.
4. Fuentes ≥ 7 pt al tamaño de impresión; etiquetas de ejes a 8 pt, etiquetas de marcas a 7 pt.
5. Color seguro para impresión: paleta Okabe-Ito, nada distinguido solo por color, y la figura debe sobrevivir a escala de grises (scripts/check_figure.py --preview).
6. Sin ejes engañosos: los gráficos de barras empiezan en cero; las escalas logarítmicas están etiquetadas; sin eje Y truncado para exagerar una diferencia; sin ejes Y duales sin una razón explícita y declarada.
7. Mostrar incertidumbre donde la afirmación es cuantitativa: bandas de IC, barras de error, o n en la leyenda. Una estimación puntual sin denominador no es un resultado.
8. La leyenda indica qué notar, luego las unidades, luego n. No es una lista de colores.
9. Sin basura gráfica: sin 3D, sin sombras, sin degradados decorativos, sin mapas de arcoíris, sin rellenos de fondo, sin líneas de cuadrícula que compitan con los datos.
10. Reproducible: el script que generó la figura vive junto a ella en el repositorio, con el archivo de datos o una semilla. Una figura que nadie pueda regenerar es un pasivo al llegar a la versión final.

Paso 0 — Decide primero la afirmación

Escribe una oración, en palabras, que la figura debe hacer evidente:

"El código de exploit público ahora aparece más rápido que los avisos: la proporción artefacto-a-aviso a 30 días aumentó de 0.63 a 1.83 en cuatro épocas."

Si no puedes escribir esa oración sin "y", tienes dos figuras.

Completa templates/figure-brief.md antes de tocar matplotlib. Te llevará dos minutos y evitará la reelaboración más común: una figura hermosa que muestra la cantidad equivocada.

Paso 1 — Elige la codificación a partir de la afirmación

Lee references/encoding-guide.md. La versión corta:

Tipo de afirmación	Codificación	Evitar
Distribución / qué tan rápido	CDF (escalonada), violín, caja, tira	barra de medias sin dispersión
Comparación pareada	pesa, pendiente, puntos pareados	dos barras flotantes
Composición a lo largo del tiempo	área apilada, múltiplos pequeños	pastel, pastel 3D
Ranking	barras horizontales ordenadas, gráfico de puntos	barras desordenadas, arcoíris
Compensación de dos variables	dispersión + frontera de Pareto	burbuja con tamaños ilegibles
Matriz / cobertura	mapa de calor con mapa uniforme perceptual, valores en celda	mapa de calor arcoíris sin valores
Proceso / cronología	carril de natación, cronología, diagrama de secuencia	tabla de fechas en prosa
Taxonomía / decisión	árbol etiquetado, matriz de celdas pobladas	texto anidado con viñetas

Paso 2 — Dibuja con el estilo compartido

import sys; sys.path.insert(0, "scripts")
from figure_style import apply_style, new_fig, save, SERIES, panel_label

apply_style()                       # base 8 pt, Okabe-Ito, rcParams seguros para impresión
fig, ax = new_fig(3.5, 2.3)         # una columna, relación de aspecto correcta
ax.plot(x, y, color=SERIES[0], label="Pre-IA")
save(fig, "figs/fig1_cdf")          # escribe .pdf (para LaTeX) + .png (vista previa)

Ajusta el estilo globalmente, nunca por figura: dos figuras en un mismo artículo con fuentes diferentes o grosores de línea diferentes se leen como dos artículos diferentes.

references/style-spec.md enumera cada ajuste y por qué está configurado así.

Paso 3 — Etiqueta directamente, leyenda al final

• Coloca el nombre de la serie al final de su línea, o en la gráfica, en lugar de en un cuadro de leyenda. Usa una leyenda solo cuando las etiquetas directas chocarían (ver examples/fig01_cdf.png).
• Etiquetas de panel A, B, C en negrita en la parte superior izquierda, referenciadas desde la leyenda.
• Etiquetas de ejes: cantidad + unidad + escala (Días desde la divulgación (escala logarítmica)).
• Luego escribe la leyenda con references/captions.md: conclusión → qué muestran los ejes → unidades/n/IC → la única advertencia que el lector no debe perderse.

Paso 4 — Hazlo seguro para impresión

• Paleta: SERIES en scripts/figure_style.py (Okabe-Ito). Datos secuenciales: cividis, nunca jet. Divergentes: RdBu_r, solo alrededor de un cero significativo.
• Codifica también por forma: los marcadores y estilos de línea varían con la serie, así la figura sobrevive a la impresión en escala de grises y a los revisores daltónicos.
• Ejecuta el verificador:

python scripts/check_figure.py figs/fig1_cdf.png --preview

Informa tamaño/dpi, la paleta cromática, la separación en escala de grises y deuteranopia, y escribe fig1_cdf_gray.png / fig1_cdf_cvd.png. Mira ambas.

references/accessibility.md cubre los detalles (contraste, CVD, texto alternativo).

Paso 5 — Exporta e incluye

• Exporta PDF vectorial con fuentes TrueType incrustadas (pdf.fonttype = 42, ya configurado).
• Incluye al ancho de impresión: \includegraphics[width=\columnwidth]{figs/fig1_cdf.pdf}.
• Verifica el PDF compilado al 100 %: sin texto por debajo de 7 pt, sin etiquetas recortadas, sin figura más alta que media columna a menos que sea la figura conceptual principal del artículo.
• references/production.md cubre inclusión en LaTeX, incrustación de fuentes y disposición de archivos.

Paso 6 — Verifica como revisor

1. Prueba de cinco segundos: muestra la figura sola a alguien; ¿puede expresar la afirmación?
2. Prueba de leyenda: la primera frase debe ser la afirmación, no "La Figura 3 muestra…".
3. Prueba de escala de grises: ambas vistas previas se leen correctamente.
4. Prueba de zoom: al 100 % del PDF compilado, cada etiqueta es legible.
5. Prueba de integridad: los números en la figura coinciden con la tabla y el texto; el eje no está truncado; las barras de error están definidas en la leyenda.
6. Prueba de reutilización: elimina el PNG; ¿el script lo regenera de manera idéntica byte por byte? Debería.

Presupuesto de elementos visuales

Clase de foro	Elementos visuales totales	Notas
Conferencia top-4	6–10	Una figura conceptual, una cronología, tablas de resultados; cada elemento referenciado en el texto
Revista	4–6	Un mensaje por elemento; barras laterales en lugar de apéndices
Revista académica	8–12	Más espacio, mismas reglas

Si una figura no está referenciada con una afirmación en el texto ("La Figura 5 muestra que X"), elimínala o reescribe la frase.

Antipatrones

Antipatrón	Por qué falla
Mapa de color arcoíris/jet	No perceptualmento ordenado; valores engañosos; ilegible en escala de grises
Barras/pasteles 3D o con sombra	Decoración que distorsiona la comparación
Pastel con >3 rebanadas	Los humanos comparan ángulos mal; usa barras ordenadas
Doble eje Y	Invita a una afirmación de correlación que los datos no respaldan; usa dos paneles
Eje Y truncado en barras	Exagera diferencias; un revisor lo notará
Cuadro de leyenda con 6 entradas	Obliga a emparejar colores; usa etiquetas directas o múltiplos pequeños
Texto pequeño reducido en LaTeX	Las fuentes caen por debajo de 7 pt; la figura se vuelve ruido gris
Leyenda que lista colores	"La línea azul muestra…" no le dice al lector nada que no pueda ver
Captura de pantalla de una tabla	No es vectorial, no es editable, no es accesible
Figura que repite una tabla	Desperdicio de un elemento visual; quédate con la que respalda la afirmación
Eje logarítmico sin etiquetar	El lector no puede comparar pendientes entre décadas
Falta de n / barras de error	Una estimación puntual sin incertidumbre no es evidencia

Mapa de recursos

Archivo	Uso
references/venue-figure-profiles.md	Lo que esperan los foros top-4, anchos de columna, reglas de leyenda/colocación
references/encoding-guide.md	Mapeo afirmación → gráfico, escalas logarítmicas, incertidumbre, cuándo gana una tabla
references/style-spec.md	Cada ajuste de matplotlib con su razón; códigos hex de paleta
references/captions.md	Fórmula de leyenda y ejemplos antes/después
references/accessibility.md	Seguridad para daltonismo y escala de grises, contraste, texto alternativo
references/production.md	Exportación, inclusión en LaTeX, fuentes, disposición de archivos, reproducibilidad
references/anti-patterns.md	Qué eliminar, con el ejemplo que lo muestra
scripts/figure_style.py	rcParams, paleta Okabe-Ito, new_fig, save, panel_label
scripts/check_figure.py	Verificación de tamaño/dpi, vistas previas en escala de grises y deuteranopia, informe de paleta
scripts/make_examples.py	Genera cada figura de ejemplo (datos sintéticos)
examples/	Imágenes de referencia: cómo se ve lo bueno, más un par bueno vs. malo
templates/figure-brief.md	Resumen de una página antes de dibujar