rookieplayerjr/pygmt-plotting-skill

Trazado con PyGMT

PyGMT envuelve las Generic Mapping Tools. Cada parámetro de método acepta tanto un nombre completo en Python (projection) como el alias de una sola letra de GMT (J); esta habilidad utiliza nombres completos. Las funciones de procesamiento de cuadrículas devuelven xarray.DataArray cuando outgrid=None, por lo que los resultados se encadenan directamente en las funciones de trazado.

Formato de figura requerido (estilo editorial)

TODAS las figuras científicas DEBEN seguir estas reglas de formato:

• Marco: MAP_FRAME_TYPE='plain', MAP_FRAME_PEN='1p,black'. Nunca dibujar el marco dos veces (sin basemap + plot estableciendo marco ambos).
• Etiquetas de panel: Letra MAYÚSCULA (A, B, C...) en la esquina superior izquierda dentro del marco, sin paréntesis, negrita ≥10p, recuadro cuadrado (relleno blanco + pluma negra de 0.8p, clearance='1.5p/1.5p/1.5p/1.5p'). Distancia igual desde los bordes izquierdo y superior. El texto del título (por ejemplo, "Este") centrado en la parte superior por separado.
• Etiquetas de marcas: Solo en los bordes izquierdo (W) e inferior (S).
• Barra de color: Horizontal en la parte inferior, con etiqueta de unidad, suficiente desplazamiento de las etiquetas de los ejes (+o0c/0.8c).
• Escala de color: vik para desplazamiento divergente, secuencial: inferno o roma.
• Los ejes de profundidad se leen POSITIVOS, hacia abajo (regla estricta para figuras de fallas/cortes transversales/3D): el eje de profundidad debe etiquetarse 0, 20, 40 … (kilómetros positivos), nunca 0, -20, -40. Almacenar la profundidad como un valor positivo (la profundidad aumenta hacia abajo), establecer el rango de profundidad de la región en [0, zmax], e invertir el eje con una altura negativa: los cortes transversales 2D utilizan projection="X<w>c/-<h>c" (altura negativa → y aumenta hacia abajo); las tramas de perspectiva 3D usan zsize="-<h>c" (negativo → profundo en la parte inferior, etiquetas positivas). Nunca emitir datos z negativos solo para tener "arriba = positivo" — eso pone signos menos en el eje de profundidad. Cuando se invierte un eje z 3D de esta manera, cualquier componente vertical de un vector dentro del plano que apunte hacia arriba también cambia de signo (hacia arriba ahora significa disminución de la profundidad positiva).
• Sin marcos dobles: el subplot maneja el marco → NO llamar a basemap(frame=) dentro de los paneles.
• Autoverificación: Después de generar cada figura, leerla/inspeccionarla. Corregir marcos dobles, contenido recortado, etiquetas inconsistentes antes de mostrar al usuario.

Inicio rápido

import pygmt

fig = pygmt.Figure()
with pygmt.config(MAP_FRAME_TYPE="plain", MAP_FRAME_PEN="1p,black"):
    fig.basemap(region=[-125, -114, 32, 42], projection="M12c", frame=["WSne", "xaf", "yaf"])
    fig.coast(land="gray90", water="white", shorelines="0.5p,black")
    pygmt.makecpt(cmap="vik", series=[-10, 10])         # establece el CPT de la sesión
    fig.plot(x=[-119.5], y=[35.3], style="c0.3c", fill=[5.0], cmap=True, pen="0.5p,black")
    fig.colorbar(frame="x+lVelocity (mm/yr)", position="JBC+w8c/0.4c+h+o0c/0.8c")
fig.savefig("map.png", dpi=300, crop=True)

fig.show() previsualiza; fig.savefig("f.pdf") (vectorial) o .png/.tif (ráster, pasar dpi=).

Los tres parámetros universales

Cada comando de mapa los acepta; el primer comando los establece y los comandos posteriores los reutilizan.

• region (R) — [W, E, S, N] (notar el orden: Oeste, Este, Sur, Norte). "g"/"d" = global; "JP" = código de país ISO; añadir +r para coordenadas de esquina.
• projection (J) — code[params/]width, el ancho debe llevar una unidad (c/i/p): "M12c" Mercator, "X10c/6c" lineal, "L-100/35/33/45/12c" cónica de Lambert, "G-120/40/12c" ortográfica.
• frame (B) — ["WSne", "xaf", "yaf+lLabel", "+tTitle"]. Mayúscula en el borde = eje+marcas+anotaciones, minúscula = sin anotaciones. a=anotación/principal, f=marca menor, g=cuadrícula. Las etiquetas de eje +l funcionan solo en proyecciones Cartesianas (X), no geográficas.

Elección de proyección / CPT (chuleta)

Necesidad	Proyección
Mapa de región (latitud baja-media, InSAR/enjambre)	M Mercator "M12c"
Continental, baja distorsión	L Cónica de Lambert "L lon0/lat0/lat1/lat2/w"
Recuadro localizador / hemisferio	G Ortográfica "G lon0/lat0/w"
Global	W Mollweide / N Robinson / H Hammer
Sección profundidad/distancia	X lineal, altura negativa → y apunta hacia abajo: "X12c/-4c"

Tipo de dato	CPT
Divergente (desplazamiento, velocidad, anomalía; centrado en cero)	vik, roma, broc, polar
Escalar secuencial	inferno, roma, batlow, viridis, turbo
Topografía	geo (tierra), oleron/relief (tierra+océano), gray (sombreado)
Cíclico (fase envuelta, acimut)	romaO, vikO

Crear un CPT con pygmt.makecpt(cmap="vik", series=[-50, 50, 5]) — sin output= se convierte en el CPT de la sesión, por lo que grdimage/plot(cmap=True)/colorbar posteriores lo usan automáticamente. Ecualizar histograma de colores de una cuadrícula con pygmt.grd2cpt(grid=g, cmap="geo").

Estilo editorial (aplicar en cada figura)

Estos son los valores predeterminados basados en la opinión de esta habilidad — anularlos cuando una revista objetivo indique lo contrario:

1. Envolver el dibujo en with pygmt.config(MAP_FRAME_TYPE="plain", MAP_FRAME_PEN="1p,black"):. Nunca dibujar el marco dos veces (subplot/basemap lo maneja — no volver a pasar frame= dentro de los paneles).
2. Etiquetas de marcas solo en los bordes W (izquierdo) y S (inferior) → frame=["WSne", ...].
3. Etiquetas de panel: letra MAYÚSCULA (A, B, C…), sin paréntesis, negrita ≥10p, en un recuadro blanco cuadrado (relleno blanco + pluma negra de 0.8p), desplazamiento igual desde la izquierda y la parte superior:

   fig.text(position="TL", text="A", font="12p,Helvetica-Bold,black",
            justify="TL", offset="j0.2c", fill="white", pen="0.8p,black", clearance="1.5p/1.5p")
   

4. Barra de color: horizontal en la parte inferior, con etiqueta de unidad, desplazamiento generoso de las etiquetas de los ejes: position="JBC+w8c/0.4c+h+o0c/0.8c", frame="x+lQuantity (unit)".
5. Desplazamiento divergente → vik; secuencial → inferno/roma.
6. Resolución ráster — sin muaré (regla estricta): al generar imágenes de cuadrículas de franjas/moteado (interferogramas envueltos, coherencia), el recuento de píxeles del panel renderizado DEBE ser ≥ las columnas nativas de la cuadrícula: panel_cm × dpi / 2.54 >= n_columns. Valor predeterminado: un solo panel ≥16 cm a dpi=400 (modo moderno de GMT: gmt begin fig png E400). Si un diseño de varios paneles submuestrea, dividir en figuras de un solo panel en lugar de reducir el tamaño. Las franjas densas submuestreadas se convierten en ondulaciones de muaré — un modo de fallo recurrente en paneles de fase envuelta de ScanSAR.
7. Autoverificación: después de guardar, Leer la imagen de salida y corregir marcos dobles, contenido recortado, etiquetas inconsistentes o textura falsa similar a muaré/cuadrícula en áreas de franjas densas antes de mostrar al usuario.

Flujo de trabajo para una nueva figura

1. Decidir región, proyección y CPT de la chuleta anterior.
2. Elegir la plantilla más cercana en GALLERY.md o scripts/ y adaptarla.
3. Dibujar dentro del bloque de configuración del estilo editorial; construir capa inferior → capa superior (relieve → costa → datos → anotaciones → barra de color).
4. fig.savefig(..., dpi=300) (dpi=400+ y verificar la regla de recuento de píxeles para rásteres de franjas/moteado), luego Leer la imagen y autoverificar (paso 7 anterior).

Referencias

• REFERENCE.md — API completa: ciclo de vida de la figura, coast/plot/text, grdimage/grdcontour/grdview, makecpt/colorbar, conjuntos de datos, procesamiento de cuadrículas (grdcut/grdgradient/grdtrack/surface…), xarray, meca, velo, project, subplot/inset/shift_origin/legend.
• GOTCHAS.md — errores comunes de la comunidad que la documentación de la API no menciona: trampas de región/línea de cambio de fecha/proyección, sobrescritura del CPT de sesión y error "no z-slices", restablecimiento de gtype/registration de xarray después de operaciones aritméticas, grdimage-todo-negro, caché de earth_relief, ámbito de configuración de fuentes, barras de color de varios paneles, cambios de nombre de parámetros 0.x, correcciones de instalación de Ghostscript/conda. §8 errores probados en campo: el recuadro de inset elimina anotaciones/etiquetas (dibujar manualmente o usar shift_origin); inset fuerza un marco predeterminado por lo que box="+p" crea un marco doble; meca +m el escalado Mw es invisible (dimensionar beachballs manualmente); meca(cmap=True) en profundidades negativas causa segfault; un tif rasterio escrito a mano → grdimage causa segfault (usar xarray en su lugar); discrepancia de dimensión shading (grdsample primero); desbordamiento de etiqueta de barra de color en inset (+mal); fig.plot(fill="white") añade un borde negro no deseado. §9 Puntas de flecha vectoriales (style="v"): +g/+h NO están rotos — una punta solo aparece si también se pasa +e/+b, un vector más corto que la longitud de la punta pierde silenciosamente su punta (arreglar con +n<len>), y +h cerca de 1 degenera la punta por lo que el relleno desaparece. Leer esto cuando una figura de PyGMT se comporte mal o genere un error inesperado.
• CRAFT.md — arte de publicación comunitaria: orden de capas del modelo de pintor, mapas de colores científicos (divergente debe estar centrado en cero y ser simétrico), convenciones de acimut de sombreado de colinas, barra de escala/brújula/graticula, alineación de múltiples paneles y barras de color compartidas, exportación vectorial vs. ráster, estratificación sismotectónica. Leer esto para que una figura se vea bien y esté lista para enviar.
• GALLERY.md — 13 plantillas de escenarios listas para adaptar (mapa base, múltiples paneles, recuadro, dispersión clasificada, campo de velocidad, histograma, rosa, 3D, contornos, corte transversal, eje dual).
• scripts/ — plantillas ejecutables y parametrizadas: displacement_map.py, seismicity_map.py, cross_section.py, multipanel_components.py. Cada una se ejecuta de forma independiente con datos de demostración; editar el bloque CONFIG en la parte superior.