climplot 0.2.0__tar.gz → 0.4.0__tar.gz

{climplot-0.2.0 → climplot-0.4.0}/.gitignore

@@ -79,5 +79,3 @@ venv.bak/
 .DS_Store
 Thumbs.db
 
-# Claude Code context (local only)
-CLAUDE.md

climplot-0.4.0/CLAUDE.md

@@ -0,0 +1,178 @@
+# climplot — AI Agent Guide
+
+## Land-Rendering Decision Rule
+
+| Grid type | How to render land | Functions |
+|---|---|---|
+| **Atmosphere / observations** (reanalysis, CMIP atmos, regular lat-lon) | Cartopy Natural Earth land (bundled) | `climplot.plot_atmos_field()` |
+| **Native ocean-model grid** (tripolar, MOM6) | Gray background + NaN masking | `climplot.plot_ocean_field()` |
+| **Regular / regridded ocean grid** (obs, 1°×1°) | Cartopy Natural Earth land (manual) | `climplot.add_land_feature()` + `climplot.add_coastlines()` |
+
+> **Do NOT** use `add_land_feature` or `add_coastlines` on native model grids — Cartopy coastlines will not align with the model's land/sea boundary.
+
+## Workflow A — Native Ocean-Model Grids
+
+Use `plot_ocean_field()`. It bundles three steps: gray background, land masking, and plotting.
+
+```python
+import climplot
+import cartopy.crs as ccrs
+
+climplot.publication()
+fig, ax = climplot.map_figure()
+
+# geolon_c / geolat_c are CORNER coordinates for pcolormesh
+cs = climplot.plot_ocean_field(
+    ax, geolon_c, geolat_c, sst,
+    wet_mask=wet,          # 1=ocean, 0=land
+    method="pcolormesh",   # default
+    cmap=cmap, norm=norm,
+)
+climplot.add_colorbar(cs, ax, "SST (°C)")
+climplot.save_figure("native_grid_sst.png")
+```
+
+### Corner vs Center Coordinates
+
+| Plot method | Coordinate type | Typical MOM6 variable |
+|---|---|---|
+| `pcolormesh` | **Corner** (cell boundaries) | `geolon_c`, `geolat_c` |
+| `contourf` | **Center** (cell midpoints) | `geolon`, `geolat` |
+| `contour` | **Center** (cell midpoints) | `geolon`, `geolat` |
+
+## Workflow B — Regular / Regridded Grids
+
+Use `add_land_feature()` (filled gray continents) and optionally `add_coastlines()`.
+
+```python
+import climplot
+import cartopy.crs as ccrs
+
+climplot.publication()
+fig, ax = climplot.map_figure()
+
+cs = ax.pcolormesh(
+    lon, lat, data,
+    cmap=cmap, norm=norm,
+    transform=ccrs.PlateCarree(),
+)
+climplot.add_land_feature(ax)      # filled gray continents
+climplot.add_coastlines(ax)        # optional coastline outlines
+climplot.add_colorbar(cs, ax, "SSH Anomaly (m)")
+climplot.save_figure("regridded_ssh.png")
+```
+
+## Workflow C — Atmosphere / Observations
+
+Use `plot_atmos_field()`. It draws light-gray land underneath, plots data
+with slight transparency on top, and adds thin coastlines. Default method
+is `contourf` with `extend="both"` (prevents white holes from
+out-of-range values). Optionally add `add_gridlines()`.
+
+```python
+import climplot
+
+climplot.publication()
+fig, ax = climplot.map_figure()
+
+cmap, norm, levels = climplot.anomaly_cmap(vmin=-2, vmax=2, interval=0.5)
+cs = climplot.plot_atmos_field(
+    ax, lon, lat, temperature,
+    method="contourf",          # default
+    land=True,                  # default: light-gray Natural Earth land underneath
+    coastlines=True,            # default: thin coastline outlines on top
+    alpha=0.85,                 # default: slight transparency so land shows through
+    coastline_linewidth=0.3,    # default: thin coastlines
+    cmap=cmap, norm=norm, levels=levels,
+)
+climplot.add_gridlines(ax, x_spacing=60, y_spacing=30)
+climplot.add_colorbar(cs, ax, "Temperature Anomaly (K)")
+climplot.save_figure("atmos_temperature.png")
+```
+
+## Map Function Reference
+
+| Function | When to use | Notes |
+|---|---|---|
+| `climplot.map_figure()` | Always — creates figure + GeoAxes | Default: Robinson, central_longitude=180 |
+| `climplot.plot_atmos_field()` | Atmosphere / regular grids | Land underneath → data (alpha=0.85) → coastlines; default `contourf`, `extend="both"` |
+| `climplot.plot_ocean_field()` | Native model grids | Bundles background + mask + plot; default `pcolormesh` |
+| `climplot.add_gridlines()` | Atmosphere / regular grids | Subtle lat/lon gridlines; returns Gridliner |
+| `climplot.set_land_background()` | Manual native-grid workflow | Sets ax facecolor so NaN → gray |
+| `climplot.mask_land()` | Manual native-grid workflow | Sets land points to NaN using wet_mask |
+| `climplot.add_land_feature()` | Regular/regridded grids | Draws Natural Earth filled continents |
+| `climplot.add_coastlines()` | Regular/regridded grids | Draws Natural Earth coastline outlines |
+| `climplot.add_land_overlay()` | Legacy — center-coord pcolormesh only | Paints gray over land using wet_mask with pcolormesh |
+
+## Common Mistakes
+
+1. **Using `add_coastlines()` on native grids** — coastlines won't align with model land mask. Use `plot_ocean_field()` instead.
+2. **Passing center coords to pcolormesh** — pcolormesh expects corner coordinates (`geolon_c`/`geolat_c`). Center coords cause a half-cell shift.
+3. **Forgetting `transform=ccrs.PlateCarree()`** — data in lon/lat coordinates needs this transform. `plot_ocean_field` sets it automatically.
+4. **Using `add_land_feature()` on native grids** — Natural Earth polygons won't match the model's coastline. Gray background + NaN masking is the correct approach.
+5. **Using `add_land_overlay()` with corner-coord pcolormesh** — `add_land_overlay` uses center coordinates internally, so shapes won't match. Use `plot_ocean_field()` instead.
+6. **Using `plot_ocean_field()` for atmosphere data** — atmosphere data doesn't have a wet mask or need gray-background land rendering. Use `plot_atmos_field()` instead.
+7. **Using `draw_labels=True` on Robinson/Mollweide** — Cartopy gridline labels only work reliably on PlateCarree and Mercator projections. Leave `draw_labels=False` (the default) for other projections.
+
+## Package Conventions
+
+- **Public API**: All functions are exported from `climplot` directly (e.g., `climplot.add_land_feature()`, not `from climplot.maps import add_land_feature`).
+- **wet_mask convention**: 1 = ocean, 0 = land.
+- **Default land color**: `#808080` (medium gray) for ocean workflows; `#e0e0e0` (light gray) for `plot_atmos_field()`.
+- **Default projection**: Robinson, centered on 180° (Pacific-centered).
+- **Colormap intervals**: Use round numbers ending in 0, 1, 2, or 5.
+
+## Colormap & Colorbar Reference
+
+### Colormap Construction Functions
+
+| Data type | Function | Example use case |
+|---|---|---|
+| Anomaly (centered on zero) | `anomaly_cmap` | Temperature bias, SSH anomaly |
+| Positive-only | `sequential_cmap` | Precipitation, wind speed, ice concentration |
+| General discrete | `discrete_cmap` | SLP (non-zero-centered ranges) |
+| Auto-picked interval | `auto_levels` + `discrete_cmap` | Unknown data range |
+| Log-spaced | `log_cmap` | Concentration spanning decades |
+| Categorical | `categorical_cmap` | Land-use types |
+
+### `center_on_white`
+
+Use `center_on_white=True` on difference/bias plots where near-zero values should be visually neutral. It adds a white band at ±interval/2 around zero by building a `ListedColormap` with one color per interval. Pass it to `anomaly_cmap` or `discrete_cmap`:
+
+```python
+cmap, norm, levels = climplot.anomaly_cmap(-0.3, 0.3, 0.05, center_on_white=True)
+```
+
+### `auto_levels`
+
+When the data range isn't known in advance, `auto_levels` picks a "nice" interval (significant digit of 1, 2, or 5) and snaps the range to clean boundaries:
+
+```python
+interval, levels = climplot.auto_levels(data.min(), data.max(), n_levels=10)
+cmap, norm, _ = climplot.discrete_cmap(levels[0], levels[-1], interval)
+```
+
+### `log_cmap`
+
+For data spanning orders of magnitude. `per_decade` controls boundary density: 1 = powers of 10, 2 = half-decades, 3 = 1-2-5 sequence. `vmin` must be > 0.
+
+```python
+cmap, norm, levels = climplot.log_cmap(0.01, 100, per_decade=3)
+```
+
+### Colorbar Behavior
+
+`add_colorbar` automatically:
+- Thins ticks to ≤9 (configurable via `max_ticks`), preferring round values
+- Ensures symmetric colormaps get symmetric tick labels
+- Suppresses minor ticks
+- Formats labels cleanly (integers without decimals, minimal decimal precision)
+- Respects `publication()`/`presentation()` font sizes
+
+Overridable kwargs: `max_ticks` (default 9), `min_ticks` (default 5), `width` (colorbar thickness as fraction of axes), `label_fontsize`, `tick_fontsize`.
+
+### Common Colormap Mistakes
+
+8. **Using awkward intervals** (e.g., 0.07 instead of 0.05) — always pick intervals ending in 0, 1, 2, or 5.
+9. **Forgetting `center_on_white` for bias plots** — without it, near-zero differences blend with the gradient and are hard to distinguish.
+10. **Using `log_cmap` with `vmin <= 0`** — logarithmic scales require strictly positive values; `log_cmap` raises `ValueError` if `vmin <= 0`.

{climplot-0.2.0/src/climplot.egg-info → climplot-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: climplot
-Version: 0.2.0
+Version: 0.4.0
 Summary: Publication-quality climate science plotting utilities
 Author-email: John Krasting <john.krasting@noaa.gov>
 License: MIT
@@ -132,8 +132,32 @@ For difference plots where near-zero values should appear neutral:
 cmap, norm, levels = climplot.anomaly_cmap(-0.3, 0.3, 0.05, center_on_white=True)
 ```
 
+### Auto-Levels
+When you don't know the data range in advance, `auto_levels` picks a nice interval automatically:
+
+```python
+interval, levels = climplot.auto_levels(-2.7, 2.7, n_levels=10)
+cmap, norm, _ = climplot.discrete_cmap(levels[0], levels[-1], interval)
+```
+
+### Log-Scale Colormap
+For data spanning orders of magnitude (e.g., tracer concentrations):
+
+```python
+cmap, norm, levels = climplot.log_cmap(0.01, 100, per_decade=3)
+```
+
+### Colorbar Customization
+`add_colorbar` supports keyword arguments for tick density and sizing:
+
+```python
+climplot.add_colorbar(cs, ax, 'Precip (mm/day)', max_ticks=7, width=0.03)
+```
+
 ## Maps
 
+### Projections
+
 ```python
 # Robinson projection (Pacific-centered)
 fig, ax = climplot.map_figure()
@@ -145,6 +169,45 @@ fig, ax = climplot.map_figure(central_longitude=0)
 fig, ax = climplot.map_figure(projection='mollweide')
 ```
 
+### Rendering Land: Three Workflows
+
+**Atmosphere / lat-lon grids** (reanalysis, CMIP atmos, observations):
+
+```python
+fig, ax = climplot.map_figure()
+cmap, norm, levels = climplot.anomaly_cmap(-2, 2, 0.5)
+cs = climplot.plot_atmos_field(
+    ax, lon, lat, temperature,
+    cmap=cmap, norm=norm, levels=levels,
+)
+climplot.add_gridlines(ax, x_spacing=30, y_spacing=30)  # optional
+climplot.add_colorbar(cs, ax, 'Temperature Anomaly (K)')
+```
+
+`plot_atmos_field` draws light-gray land underneath, plots data with slight transparency on top, and adds thin coastlines — all in one call.
+
+**Regular / regridded grids** (observations, reanalysis on 1°×1°, etc.):
+
+```python
+fig, ax = climplot.map_figure()
+cs = ax.pcolormesh(lon, lat, data, cmap=cmap, norm=norm,
+                   transform=ccrs.PlateCarree())
+climplot.add_land_feature(ax)    # filled gray continents from Natural Earth
+climplot.add_coastlines(ax)      # optional coastline outlines
+```
+
+**Native ocean-model grids** (tripolar, MOM6 — Cartopy coastlines won't align):
+
+```python
+fig, ax = climplot.map_figure()
+cs = climplot.plot_ocean_field(
+    ax, geolon_c, geolat_c, sst,
+    wet_mask=wet,   # 1=ocean, 0=land
+)
+```
+
+`plot_ocean_field` sets a gray background so NaN over land renders as the model's coastline, optionally masks land, and plots the data in one call. See the [Plotting Guide](docs/plotting-guide.md) for full details.
+
 ## Multi-panel Figures
 
 ```python

{climplot-0.2.0 → climplot-0.4.0}/README.md

@@ -91,8 +91,32 @@ For difference plots where near-zero values should appear neutral:
 cmap, norm, levels = climplot.anomaly_cmap(-0.3, 0.3, 0.05, center_on_white=True)
 ```
 
+### Auto-Levels
+When you don't know the data range in advance, `auto_levels` picks a nice interval automatically:
+
+```python
+interval, levels = climplot.auto_levels(-2.7, 2.7, n_levels=10)
+cmap, norm, _ = climplot.discrete_cmap(levels[0], levels[-1], interval)
+```
+
+### Log-Scale Colormap
+For data spanning orders of magnitude (e.g., tracer concentrations):
+
+```python
+cmap, norm, levels = climplot.log_cmap(0.01, 100, per_decade=3)
+```
+
+### Colorbar Customization
+`add_colorbar` supports keyword arguments for tick density and sizing:
+
+```python
+climplot.add_colorbar(cs, ax, 'Precip (mm/day)', max_ticks=7, width=0.03)
+```
+
 ## Maps
 
+### Projections
+
 ```python
 # Robinson projection (Pacific-centered)
 fig, ax = climplot.map_figure()
@@ -104,6 +128,45 @@ fig, ax = climplot.map_figure(central_longitude=0)
 fig, ax = climplot.map_figure(projection='mollweide')
 ```
 
+### Rendering Land: Three Workflows
+
+**Atmosphere / lat-lon grids** (reanalysis, CMIP atmos, observations):
+
+```python
+fig, ax = climplot.map_figure()
+cmap, norm, levels = climplot.anomaly_cmap(-2, 2, 0.5)
+cs = climplot.plot_atmos_field(
+    ax, lon, lat, temperature,
+    cmap=cmap, norm=norm, levels=levels,
+)
+climplot.add_gridlines(ax, x_spacing=30, y_spacing=30)  # optional
+climplot.add_colorbar(cs, ax, 'Temperature Anomaly (K)')
+```
+
+`plot_atmos_field` draws light-gray land underneath, plots data with slight transparency on top, and adds thin coastlines — all in one call.
+
+**Regular / regridded grids** (observations, reanalysis on 1°×1°, etc.):
+
+```python
+fig, ax = climplot.map_figure()
+cs = ax.pcolormesh(lon, lat, data, cmap=cmap, norm=norm,
+                   transform=ccrs.PlateCarree())
+climplot.add_land_feature(ax)    # filled gray continents from Natural Earth
+climplot.add_coastlines(ax)      # optional coastline outlines
+```
+
+**Native ocean-model grids** (tripolar, MOM6 — Cartopy coastlines won't align):
+
+```python
+fig, ax = climplot.map_figure()
+cs = climplot.plot_ocean_field(
+    ax, geolon_c, geolat_c, sst,
+    wet_mask=wet,   # 1=ocean, 0=land
+)
+```
+
+`plot_ocean_field` sets a gray background so NaN over land renders as the model's coastline, optionally masks land, and plots the data in one call. See the [Plotting Guide](docs/plotting-guide.md) for full details.
+
 ## Multi-panel Figures
 
 ```python

climplot-0.4.0/demo_atmosphere.py

@@ -0,0 +1,89 @@
+"""Visual demo of atmosphere data plotting functions.
+
+Creates a 4-panel figure showing plot_atmos_field with different
+variables and methods, plus an add_gridlines demo. Uses synthetic
+data only (no external dependencies beyond climplot).
+"""
+
+import numpy as np
+import cartopy.crs as ccrs
+
+import climplot
+
+# ---------- style ----------------------------------------------------------
+climplot.publication()
+
+# ---------- synthetic data -------------------------------------------------
+lon = np.arange(0.5, 360.5, 2.0)
+lat = np.arange(-89.5, 90.5, 2.0)
+LON, LAT = np.meshgrid(lon, lat)
+
+# (a) Temperature anomaly: dipole pattern
+temperature = 2.0 * np.sin(np.deg2rad(LAT * 3)) * np.cos(np.deg2rad(LON * 2))
+
+# (b) Precipitation: ITCZ-like tropical band (positive only)
+precip = 8.0 * np.exp(-((LAT / 15.0) ** 2)) * (1 + 0.5 * np.cos(np.deg2rad(LON * 3)))
+
+# (c) Sea level pressure: wavy zonal pattern
+slp = 1013.0 + 15.0 * np.sin(np.deg2rad(LAT * 2)) + 5.0 * np.cos(np.deg2rad(LON))
+
+# (d) Wind speed: jet stream pattern (positive only)
+wind = 12.0 * np.exp(-(((LAT - 45) / 10.0) ** 2)) + 8.0 * np.exp(
+    -(((LAT + 45) / 10.0) ** 2)
+)
+wind = wind * (1 + 0.3 * np.cos(np.deg2rad(LON * 4)))
+
+# ---------- colormaps ------------------------------------------------------
+cmap_t, norm_t, levels_t = climplot.anomaly_cmap(vmin=-2, vmax=2, interval=0.5)
+cmap_p, norm_p, levels_p = climplot.sequential_cmap(vmin=0, vmax=12, interval=1)
+cmap_s, norm_s, levels_s = climplot.sequential_cmap(vmin=990, vmax=1030, interval=5)
+cmap_w, norm_w, levels_w = climplot.sequential_cmap(
+    vmin=0, vmax=20, interval=2, cmap_name="inferno"
+)
+
+# ---------- figure ---------------------------------------------------------
+fig, axes = climplot.panel_figure(
+    2, 2, projection=ccrs.Robinson(central_longitude=180)
+)
+
+# (a) Temperature anomaly -- contourf (default)
+cs_a = climplot.plot_atmos_field(
+    axes[0, 0], lon, lat, temperature,
+    cmap=cmap_t, norm=norm_t, levels=levels_t,
+)
+climplot.add_colorbar(cs_a, axes[0, 0], "Temperature Anomaly (K)")
+axes[0, 0].set_title("contourf — Temperature Anomaly", fontsize=7)
+
+# (b) Precipitation -- contourf with sequential colormap
+cs_b = climplot.plot_atmos_field(
+    axes[0, 1], lon, lat, precip,
+    cmap=cmap_p, norm=norm_p, levels=levels_p,
+)
+climplot.add_colorbar(cs_b, axes[0, 1], "Precipitation (mm/day)")
+axes[0, 1].set_title("contourf — Precipitation", fontsize=7)
+
+# (c) Sea level pressure -- contourf
+cs_c = climplot.plot_atmos_field(
+    axes[1, 0], lon, lat, slp,
+    cmap=cmap_s, norm=norm_s, levels=levels_s,
+)
+climplot.add_colorbar(cs_c, axes[1, 0], "SLP (hPa)")
+axes[1, 0].set_title("contourf — SLP", fontsize=7)
+
+# (d) Wind speed -- pcolormesh
+cs_d = climplot.plot_atmos_field(
+    axes[1, 1], lon, lat, wind,
+    method="pcolormesh",
+    cmap=cmap_w, norm=norm_w,
+)
+climplot.add_colorbar(cs_d, axes[1, 1], "Wind Speed (m/s)")
+axes[1, 1].set_title("pcolormesh — Wind Speed", fontsize=7)
+
+# Gridlines on all panels
+for ax in axes.flat:
+    climplot.add_gridlines(ax, x_spacing=30, y_spacing=30)
+
+# ---------- finishing touches ----------------------------------------------
+climplot.add_panel_labels(axes)
+path = climplot.save_figure("demo_atmosphere.png")
+print(f"Saved to {path}")

climplot-0.4.0/demo_native_grid.py

@@ -0,0 +1,90 @@
+"""Visual demo of native-grid plotting functions.
+
+Creates a 4-panel figure showing plot_ocean_field on tripolar and
+lat-lon grids plus a traditional Cartopy-based panel for comparison.
+"""
+
+import numpy as np
+import cartopy.crs as ccrs
+import momgrid
+
+import climplot
+
+# ---------- style ----------------------------------------------------------
+climplot.publication()
+
+# ---------- colormap -------------------------------------------------------
+cmap, norm, levels = climplot.anomaly_cmap(
+    vmin=-15, vmax=15, interval=2.5, cmap_name="RdBu_r"
+)
+
+# ---------- tripolar grid (ESM4) ------------------------------------------
+grd = momgrid.MOMgrid("esm4_sym")
+
+geolon = np.asarray(grd.geolon)
+geolat = np.asarray(grd.geolat)
+geolon_c = np.asarray(grd.geolon_c)
+geolat_c = np.asarray(grd.geolat_c)
+wet = np.asarray(grd.wet)
+
+sst_tri = 15.0 * np.cos(np.deg2rad(geolat))
+
+# ---------- regular lat-lon grid (WOA 1°) ---------------------------------
+woa = momgrid.external.woa18_grid(1.0)
+
+lon_1d = np.asarray(woa.lon)
+lat_1d = np.asarray(woa.lat)
+lon_b_1d = np.asarray(woa.lon_b)
+lat_b_1d = np.asarray(woa.lat_b)
+mask_woa = np.asarray(woa.mask)
+
+lon_2d, lat_2d = np.meshgrid(lon_1d, lat_1d)
+lon_b_2d, lat_b_2d = np.meshgrid(lon_b_1d, lat_b_1d)
+
+sst_ll = 15.0 * np.cos(np.deg2rad(lat_2d))
+
+# ---------- figure ---------------------------------------------------------
+fig, axes = climplot.panel_figure(
+    2, 2, projection=ccrs.Robinson(central_longitude=180)
+)
+
+# (a) pcolormesh on tripolar with corner coords
+cs_a = climplot.plot_ocean_field(
+    axes[0, 0], geolon_c, geolat_c, sst_tri,
+    wet_mask=wet, method="pcolormesh",
+    cmap=cmap, norm=norm,
+)
+axes[0, 0].set_title("plot_ocean_field — pcolormesh (tripolar)", fontsize=7)
+
+# (b) contourf on tripolar with center coords
+cs_b = climplot.plot_ocean_field(
+    axes[0, 1], geolon, geolat, sst_tri,
+    wet_mask=wet, method="contourf",
+    cmap=cmap, norm=norm, levels=levels,
+)
+axes[0, 1].set_title("plot_ocean_field — contourf (tripolar)", fontsize=7)
+
+# (c) pcolormesh on regular lat-lon via plot_ocean_field
+cs_c = climplot.plot_ocean_field(
+    axes[1, 0], lon_b_2d, lat_b_2d, sst_ll,
+    wet_mask=mask_woa, method="pcolormesh",
+    cmap=cmap, norm=norm,
+)
+axes[1, 0].set_title("plot_ocean_field — pcolormesh (lat-lon 1°)", fontsize=7)
+
+# (d) traditional workflow: pcolormesh + add_land_feature + add_coastlines
+ax_d = axes[1, 1]
+cs_d = ax_d.pcolormesh(
+    lon_b_2d, lat_b_2d, sst_ll,
+    transform=ccrs.PlateCarree(),
+    cmap=cmap, norm=norm,
+)
+climplot.add_land_feature(ax_d, resolution="110m")
+climplot.add_coastlines(ax_d, resolution="110m")
+ax_d.set_title("Traditional: pcolormesh + land + coastlines", fontsize=7)
+
+# ---------- finishing touches ----------------------------------------------
+climplot.add_panel_labels(axes)
+climplot.bottom_colorbar(cs_a, fig, axes, "Synthetic SST (°C)")
+path = climplot.save_figure("demo_native_grid.png")
+print(f"Saved to {path}")