climplot 0.1.0__py3-none-any.whl

climplot/__init__.py

@@ -0,0 +1,118 @@
+"""
+climplot - Publication-quality climate science plotting utilities.
+
+A Python package for creating beautiful, publication-ready climate and weather
+science figures with minimal effort. Designed for climate science beginners
+and experts alike.
+
+Quick Start
+-----------
+>>> import climplot
+>>> climplot.publication()  # Set up publication-quality defaults
+>>> fig, ax = climplot.map_figure()  # Create a map with Robinson projection
+
+Style Modes
+-----------
+- climplot.publication(): 3.5" width, 8-11pt fonts, 300 DPI
+- climplot.presentation(): 7" width, 12-16pt fonts, 150 DPI
+
+See Also
+--------
+- Documentation: https://climplot.readthedocs.io
+- Source: https://github.com/jkrasting/climplot
+"""
+
+__version__ = "0.1.0"
+
+# Style functions
+from .style import (
+    publication,
+    presentation,
+    reset_style,
+    get_current_mode,
+)
+
+# Colormap functions
+from .colormaps import (
+    anomaly_cmap,
+    sequential_cmap,
+    categorical_cmap,
+    discrete_cmap,
+    list_colormaps,
+)
+
+# Map functions
+from .maps import (
+    map_figure,
+    add_land_overlay,
+    add_coastlines,
+)
+
+# Time series functions
+from .timeseries import (
+    timeseries_figure,
+)
+
+# Panel/multi-figure functions
+from .panels import (
+    panel_figure,
+    add_panel_labels,
+    add_colorbar,
+    bottom_colorbar,
+    save_figure,
+)
+
+# Metrics functions
+from .metrics import (
+    area_weighted_mean,
+    area_weighted_bias,
+    area_weighted_rmse,
+    area_weighted_corr,
+    area_weighted_std,
+    timeseries_bias,
+    timeseries_rmse,
+    timeseries_corr,
+    timeseries_std,
+    metrics_summary,
+    print_metrics_summary,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Style
+    "publication",
+    "presentation",
+    "reset_style",
+    "get_current_mode",
+    # Colormaps
+    "anomaly_cmap",
+    "sequential_cmap",
+    "categorical_cmap",
+    "discrete_cmap",
+    "list_colormaps",
+    # Maps
+    "map_figure",
+    "add_land_overlay",
+    "add_coastlines",
+    # Time series
+    "timeseries_figure",
+    # Panels
+    "panel_figure",
+    "add_panel_labels",
+    "add_colorbar",
+    "bottom_colorbar",
+    "save_figure",
+    # Metrics
+    "area_weighted_mean",
+    "area_weighted_bias",
+    "area_weighted_rmse",
+    "area_weighted_corr",
+    "area_weighted_std",
+    "timeseries_bias",
+    "timeseries_rmse",
+    "timeseries_corr",
+    "timeseries_std",
+    "metrics_summary",
+    "print_metrics_summary",
+]

climplot/colormaps.py

@@ -0,0 +1,254 @@
+"""
+Climate-specific colormap utilities.
+
+This module provides colormaps optimized for climate data visualization,
+including diverging colormaps for anomalies and sequential colormaps
+for positive-only data.
+
+Key Features
+------------
+- Discrete levels with "round" intervals (0, 1, 2, or 5 endings)
+- Center-on-white option for difference plots
+- Pre-defined colormaps for common climate variables
+
+Examples
+--------
+>>> import climplot
+>>> cmap, norm, levels = climplot.anomaly_cmap(-0.3, 0.3, 0.05)
+>>> ax.pcolormesh(lon, lat, data, cmap=cmap, norm=norm)
+"""
+
+import matplotlib.pyplot as plt
+import matplotlib.colors as mcolors
+from matplotlib.colors import ListedColormap, BoundaryNorm
+import numpy as np
+from typing import Tuple, List, Optional
+
+# Standard climate colormaps
+CLIMATE_COLORMAPS = {
+    "anomaly": "RdBu_r",  # Red-blue diverging (red=high, blue=low)
+    "temperature": "RdBu_r",
+    "precipitation": "BrBG",  # Brown-teal diverging
+    "ssh": "RdBu_r",  # Sea surface height
+    "wind": "PuOr_r",  # Purple-orange diverging
+    "sequential": "viridis",  # Sequential
+    "ice": "Blues_r",  # Ice concentration
+}
+
+
+def anomaly_cmap(
+    vmin: float = -1.0,
+    vmax: float = 1.0,
+    interval: float = 0.1,
+    center_on_white: bool = False,
+    cmap_name: str = "RdBu_r",
+) -> Tuple[mcolors.Colormap, mcolors.BoundaryNorm, np.ndarray]:
+    """
+    Create a diverging colormap for anomaly fields.
+
+    Generates discrete color levels centered on zero with the specified
+    interval. By default uses RdBu_r where red=positive, blue=negative.
+
+    Parameters
+    ----------
+    vmin : float, optional
+        Minimum value for color scale. Default is -1.0.
+    vmax : float, optional
+        Maximum value for color scale. Default is 1.0.
+    interval : float, optional
+        Interval between color levels. Should end in 0, 1, 2, or 5.
+        Default is 0.1.
+    center_on_white : bool, optional
+        If True, creates a white band centered on zero.
+        White band width is ±interval/2. Default is False.
+        Recommended for difference plots.
+    cmap_name : str, optional
+        Base colormap name. Default is 'RdBu_r'.
+
+    Returns
+    -------
+    cmap : Colormap
+        The colormap object
+    norm : BoundaryNorm
+        Normalization for discrete levels
+    levels : ndarray
+        The discrete color levels
+
+    Examples
+    --------
+    >>> # Standard anomaly colormap
+    >>> cmap, norm, levels = climplot.anomaly_cmap(-0.3, 0.3, 0.05)
+
+    >>> # Difference plot with white band for near-zero values
+    >>> cmap, norm, levels = climplot.anomaly_cmap(-0.3, 0.3, 0.05, center_on_white=True)
+
+    Notes
+    -----
+    Common interval choices:
+    - 0.01, 0.02, 0.05, 0.10, 0.20, 0.50, 1.0, 2.0, 5.0
+    """
+    return discrete_cmap(
+        vmin, vmax, interval, cmap_name=cmap_name, center_on_white=center_on_white
+    )
+
+
+def sequential_cmap(
+    vmin: float = 0.0,
+    vmax: float = 1.0,
+    interval: float = 0.1,
+    cmap_name: str = "viridis",
+) -> Tuple[mcolors.Colormap, mcolors.BoundaryNorm, np.ndarray]:
+    """
+    Create a sequential colormap for positive-only data.
+
+    Parameters
+    ----------
+    vmin : float, optional
+        Minimum value. Default is 0.0.
+    vmax : float, optional
+        Maximum value. Default is 1.0.
+    interval : float, optional
+        Interval between levels. Default is 0.1.
+    cmap_name : str, optional
+        Colormap name. Default is 'viridis'.
+
+    Returns
+    -------
+    cmap : Colormap
+    norm : BoundaryNorm
+    levels : ndarray
+
+    Examples
+    --------
+    >>> cmap, norm, levels = climplot.sequential_cmap(0, 100, 10)
+    """
+    return discrete_cmap(vmin, vmax, interval, cmap_name=cmap_name, extend="max")
+
+
+def categorical_cmap(
+    n_categories: int,
+    cmap_name: str = "tab10",
+) -> ListedColormap:
+    """
+    Create a colormap for discrete categories.
+
+    Parameters
+    ----------
+    n_categories : int
+        Number of categories
+    cmap_name : str, optional
+        Base colormap. Default is 'tab10'.
+
+    Returns
+    -------
+    ListedColormap
+        Colormap with n_categories discrete colors
+
+    Examples
+    --------
+    >>> cmap = climplot.categorical_cmap(5)
+    """
+    base_cmap = plt.get_cmap(cmap_name)
+    colors = [base_cmap(i) for i in range(n_categories)]
+    return ListedColormap(colors)
+
+
+def discrete_cmap(
+    vmin: float,
+    vmax: float,
+    interval: float,
+    cmap_name: str = "RdBu_r",
+    extend: str = "both",
+    center_on_white: bool = False,
+) -> Tuple[mcolors.Colormap, mcolors.BoundaryNorm, np.ndarray]:
+    """
+    Create a discrete colormap with BoundaryNorm.
+
+    Generates color levels with "round" intervals for clean, readable
+    colorbars. Optionally centers colormap on white for difference plots.
+
+    Parameters
+    ----------
+    vmin : float
+        Minimum value for color scale
+    vmax : float
+        Maximum value for color scale
+    interval : float
+        Interval between color levels. Should end in 0, 1, 2, or 5.
+    cmap_name : str, optional
+        Name of matplotlib colormap. Default is 'RdBu_r'.
+    extend : str, optional
+        Out-of-range handling: 'neither', 'min', 'max', or 'both'.
+        Default is 'both'.
+    center_on_white : bool, optional
+        If True, creates a white band centered on zero.
+        White band width is ±interval/2. Default is False.
+
+    Returns
+    -------
+    cmap : Colormap
+        The colormap object
+    norm : BoundaryNorm
+        Normalization for discrete levels
+    levels : ndarray
+        The discrete color levels
+
+    Examples
+    --------
+    >>> # Standard discrete colormap
+    >>> cmap, norm, levels = discrete_cmap(-0.3, 0.3, 0.05)
+
+    >>> # With white band at center
+    >>> cmap, norm, levels = discrete_cmap(-0.3, 0.3, 0.05, center_on_white=True)
+
+    Notes
+    -----
+    When center_on_white=True:
+    - White band width is ±interval/2
+    - For interval=0.05, white covers -0.025 to +0.025
+    - Best for difference plots where near-zero values are ambiguous
+    """
+    if center_on_white:
+        # Create levels with white band centered on zero
+        neg_levels = np.arange(vmin, -interval / 10, interval)
+        white_band = np.array([-interval / 2, interval / 2])
+        pos_levels = np.arange(interval, vmax + interval / 2, interval)
+        levels = np.sort(np.concatenate([neg_levels, white_band, pos_levels]))
+    else:
+        # Standard levels
+        levels = np.arange(vmin, vmax + interval / 2, interval)
+
+    # Get base colormap
+    base_cmap = plt.get_cmap(cmap_name)
+
+    # Modify for center-on-white
+    if center_on_white:
+        n_colors = 256
+        colors = base_cmap(np.linspace(0, 1, n_colors))
+        center_idx = n_colors // 2
+        colors[center_idx] = [1.0, 1.0, 1.0, 1.0]  # Pure white
+        cmap = ListedColormap(colors, name=f"{cmap_name}_white_center")
+    else:
+        cmap = base_cmap
+
+    # Create discrete normalization
+    norm = BoundaryNorm(levels, cmap.N, extend=extend)
+
+    return cmap, norm, levels
+
+
+def list_colormaps() -> dict:
+    """
+    List recommended colormaps for climate variables.
+
+    Returns
+    -------
+    dict
+        Mapping of variable types to recommended colormap names
+
+    Examples
+    --------
+    >>> climplot.list_colormaps()
+    {'anomaly': 'RdBu_r', 'temperature': 'RdBu_r', ...}
+    """
+    return CLIMATE_COLORMAPS.copy()

climplot/data/presentation.mplstyle

@@ -0,0 +1,37 @@
+# climplot presentation style
+# For slides/posters: 7" width, 12-16pt fonts, 150 DPI
+# Usage: plt.style.use('climplot/data/presentation.mplstyle')
+
+# Font sizes (larger for readability)
+font.size: 14
+axes.labelsize: 14
+axes.titlesize: 16
+xtick.labelsize: 14
+ytick.labelsize: 14
+legend.fontsize: 12
+
+# Figure settings
+figure.figsize: 7.0, 4.2
+figure.dpi: 150
+savefig.dpi: 150
+savefig.bbox: tight
+savefig.facecolor: white
+
+# Line widths (thicker for visibility)
+axes.linewidth: 1.2
+grid.linewidth: 0.5
+lines.linewidth: 2.5
+
+# Grid
+axes.grid: False
+grid.alpha: 0.3
+
+# Legend
+legend.frameon: False
+legend.loc: best
+
+# PDF output
+pdf.fonttype: 42
+
+# Colors
+axes.prop_cycle: cycler('color', ['1f77b4', 'ff7f0e', '2ca02c', 'd62728', '9467bd', '8c564b', 'e377c2', '7f7f7f', 'bcbd22', '17becf'])

climplot/data/publication.mplstyle

@@ -0,0 +1,37 @@
+# climplot publication style
+# For journal figures: 3.5" width, 8-11pt fonts, 300 DPI
+# Usage: plt.style.use('climplot/data/publication.mplstyle')
+
+# Font sizes
+font.size: 10
+axes.labelsize: 10
+axes.titlesize: 11
+xtick.labelsize: 8
+ytick.labelsize: 8
+legend.fontsize: 8
+
+# Figure settings
+figure.figsize: 3.5, 2.625
+figure.dpi: 300
+savefig.dpi: 300
+savefig.bbox: tight
+savefig.facecolor: white
+
+# Line widths
+axes.linewidth: 0.8
+grid.linewidth: 0.3
+lines.linewidth: 1.5
+
+# Grid
+axes.grid: False
+grid.alpha: 0.3
+
+# Legend
+legend.frameon: False
+legend.loc: best
+
+# PDF output
+pdf.fonttype: 42
+
+# Colors (use colorblind-friendly defaults)
+axes.prop_cycle: cycler('color', ['1f77b4', 'ff7f0e', '2ca02c', 'd62728', '9467bd', '8c564b', 'e377c2', '7f7f7f', 'bcbd22', '17becf'])

climplot/maps.py

@@ -0,0 +1,230 @@
+"""
+Map plotting utilities with Cartopy projections.
+
+This module provides functions for creating publication-quality maps
+with appropriate projections, coastlines, and land overlays.
+
+Examples
+--------
+>>> import climplot
+>>> climplot.publication()
+>>> fig, ax = climplot.map_figure()
+>>> cs = ax.pcolormesh(lon, lat, data, transform=ccrs.PlateCarree())
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+from typing import Tuple, Optional
+
+# Cartopy imports (required dependency)
+import cartopy.crs as ccrs
+import cartopy.feature as cfeature
+
+
+def map_figure(
+    projection: str = "robinson",
+    central_longitude: float = 180,
+    figsize: Optional[Tuple[float, float]] = None,
+    **kwargs,
+) -> Tuple[plt.Figure, plt.Axes]:
+    """
+    Create a map figure with specified projection.
+
+    Parameters
+    ----------
+    projection : str, optional
+        Map projection name. Options:
+        - 'robinson' (default): Good for global maps
+        - 'platecarree': Equirectangular, simple lat/lon
+        - 'mollweide': Equal-area, good for global
+        - 'orthographic': Globe view
+        - 'mercator': Standard navigation projection
+        - 'northpolarstereo': Arctic view
+        - 'southpolarstereo': Antarctic view
+    central_longitude : float, optional
+        Central longitude for projection. Default is 180 (Pacific-centered).
+    figsize : tuple, optional
+        Figure size (width, height) in inches. If None, uses matplotlib defaults.
+    **kwargs
+        Additional arguments passed to plt.figure()
+
+    Returns
+    -------
+    fig : Figure
+        The figure object
+    ax : GeoAxes
+        The map axes with specified projection
+
+    Examples
+    --------
+    >>> # Global Robinson projection (Pacific-centered)
+    >>> fig, ax = climplot.map_figure()
+
+    >>> # Atlantic-centered
+    >>> fig, ax = climplot.map_figure(central_longitude=0)
+
+    >>> # Plate Carree for regional maps
+    >>> fig, ax = climplot.map_figure(projection='platecarree')
+    """
+    # Get projection
+    proj = _get_projection(projection, central_longitude)
+
+    # Create figure
+    if figsize is not None:
+        kwargs["figsize"] = figsize
+    fig = plt.figure(**kwargs)
+    ax = fig.add_subplot(111, projection=proj)
+
+    return fig, ax
+
+
+def _get_projection(name: str, central_longitude: float = 180):
+    """Get a cartopy projection by name."""
+    projections = {
+        "robinson": ccrs.Robinson(central_longitude=central_longitude),
+        "platecarree": ccrs.PlateCarree(central_longitude=central_longitude),
+        "mollweide": ccrs.Mollweide(central_longitude=central_longitude),
+        "orthographic": ccrs.Orthographic(
+            central_longitude=central_longitude, central_latitude=0
+        ),
+        "mercator": ccrs.Mercator(central_longitude=central_longitude),
+        "northpolarstereo": ccrs.NorthPolarStereo(),
+        "southpolarstereo": ccrs.SouthPolarStereo(),
+    }
+
+    name_lower = name.lower().replace("_", "").replace("-", "")
+    if name_lower not in projections:
+        raise ValueError(
+            f"Unknown projection: {name}. "
+            f"Available: {list(projections.keys())}"
+        )
+
+    return projections[name_lower]
+
+
+def add_land_overlay(
+    ax: plt.Axes,
+    lon,
+    lat,
+    wet_mask,
+    land_color: str = "#808080",
+    zorder: int = 10,
+):
+    """
+    Add gray overlay to render land areas.
+
+    Draws a solid color layer over land points (wet=0), ensuring
+    continents appear uniformly regardless of underlying data values.
+
+    Parameters
+    ----------
+    ax : GeoAxes
+        Map axes to add overlay to
+    lon : array-like
+        2D longitude array
+    lat : array-like
+        2D latitude array
+    wet_mask : array-like
+        Wet mask where 1 = ocean, 0 = land
+    land_color : str, optional
+        Color for land. Default is '#808080' (medium gray).
+    zorder : int, optional
+        Drawing order. Default is 10 (on top of most elements).
+
+    Examples
+    --------
+    >>> fig, ax = climplot.map_figure()
+    >>> cs = ax.pcolormesh(lon, lat, data, transform=ccrs.PlateCarree())
+    >>> climplot.add_land_overlay(ax, lon, lat, wet_mask)
+    """
+    import xarray as xr
+    from matplotlib.colors import ListedColormap
+
+    # Create land overlay: 1 where land (wet=0), NaN where ocean
+    land_overlay = xr.where(wet_mask == 0, 1.0, np.nan)
+
+    # Single-color colormap
+    gray_cmap = ListedColormap([land_color])
+
+    # Draw over land
+    ax.pcolormesh(
+        lon,
+        lat,
+        land_overlay,
+        transform=ccrs.PlateCarree(),
+        cmap=gray_cmap,
+        vmin=0,
+        vmax=1,
+        zorder=zorder,
+    )
+
+
+def add_coastlines(
+    ax: plt.Axes,
+    resolution: str = "110m",
+    linewidth: float = 0.5,
+    color: str = "black",
+    **kwargs,
+):
+    """
+    Add coastlines to a map.
+
+    Parameters
+    ----------
+    ax : GeoAxes
+        Map axes
+    resolution : str, optional
+        Resolution: '110m' (default), '50m', or '10m'.
+        Higher resolution = more detail but slower.
+    linewidth : float, optional
+        Line width. Default is 0.5.
+    color : str, optional
+        Line color. Default is 'black'.
+    **kwargs
+        Additional arguments passed to ax.coastlines()
+
+    Examples
+    --------
+    >>> fig, ax = climplot.map_figure()
+    >>> climplot.add_coastlines(ax)
+
+    Notes
+    -----
+    For model data on native grids, consider using add_land_overlay()
+    instead of coastlines, as coastlines may not align with the model grid.
+    """
+    ax.coastlines(resolution=resolution, linewidth=linewidth, color=color, **kwargs)
+
+
+def add_land_feature(
+    ax: plt.Axes,
+    resolution: str = "110m",
+    facecolor: str = "#808080",
+    edgecolor: str = "none",
+    **kwargs,
+):
+    """
+    Add land feature (filled continents) to a map.
+
+    Parameters
+    ----------
+    ax : GeoAxes
+        Map axes
+    resolution : str, optional
+        Resolution: '110m' (default), '50m', or '10m'.
+    facecolor : str, optional
+        Fill color. Default is '#808080' (gray).
+    edgecolor : str, optional
+        Edge color. Default is 'none'.
+    **kwargs
+        Additional arguments passed to ax.add_feature()
+
+    Examples
+    --------
+    >>> fig, ax = climplot.map_figure()
+    >>> climplot.add_land_feature(ax)
+    """
+    land = cfeature.NaturalEarthFeature(
+        "physical", "land", resolution, facecolor=facecolor, edgecolor=edgecolor
+    )
+    ax.add_feature(land, **kwargs)