climplot 0.1.0__py3-none-any.whl

climplot/style.py

@@ -0,0 +1,201 @@
+"""
+Style management for publication and presentation figures.
+
+This module provides functions to configure matplotlib for publication-quality
+or presentation-quality figures with appropriate font sizes, DPI, and other
+settings.
+
+Examples
+--------
+>>> import climplot
+>>> climplot.publication()  # For journal figures
+>>> climplot.presentation()  # For slides/posters
+"""
+
+import matplotlib.pyplot as plt
+from pathlib import Path
+from typing import Optional
+
+# Track current mode
+_current_mode: Optional[str] = None
+
+# Style file directory
+_STYLE_DIR = Path(__file__).parent / "data"
+
+
+def publication(
+    width: float = 3.5,
+    for_pdf: bool = False,
+    font_family: Optional[str] = None,
+):
+    """
+    Configure matplotlib for publication-quality figures.
+
+    Sets up small font sizes and high DPI appropriate for journal figures.
+    Single-column figures are 3.5 inches wide (89 mm).
+
+    Parameters
+    ----------
+    width : float, optional
+        Default figure width in inches. Default is 3.5 (single-column).
+        Use 7.0 for two-column figures.
+    for_pdf : bool, optional
+        If True, configure for PDF output with embedded fonts.
+        Uses Myriad Pro font family by default.
+    font_family : str, optional
+        Font family to use. If None and for_pdf=True, uses 'Myriad Pro'.
+
+    Examples
+    --------
+    >>> import climplot
+    >>> climplot.publication()  # Standard PNG output
+    >>> climplot.publication(for_pdf=True)  # PDF with embedded fonts
+    >>> climplot.publication(width=7.0)  # Two-column width
+
+    Notes
+    -----
+    Publication mode settings:
+    - Figure width: 3.5" (single-column) or 7.0" (two-column)
+    - DPI: 300
+    - Axis labels: 10 pt
+    - Tick labels: 8 pt
+    - Title: 11 pt
+    - Legend: 8 pt
+    """
+    global _current_mode
+
+    settings = {
+        # Font sizes (publication: smaller, dense)
+        "font.size": 10,
+        "axes.labelsize": 10,
+        "axes.titlesize": 11,
+        "xtick.labelsize": 8,
+        "ytick.labelsize": 8,
+        "legend.fontsize": 8,
+        # Figure settings
+        "figure.figsize": (width, width * 0.75),
+        "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,
+        # PDF settings
+        "pdf.fonttype": 42,  # TrueType for editability
+    }
+
+    if for_pdf:
+        if font_family is None:
+            font_family = "Myriad Pro"
+        settings["font.family"] = font_family
+
+    plt.rcParams.update(settings)
+    _current_mode = "publication"
+
+
+def presentation(
+    width: float = 7.0,
+    for_pdf: bool = False,
+    font_family: Optional[str] = None,
+):
+    """
+    Configure matplotlib for presentation-quality figures.
+
+    Sets up larger font sizes and moderate DPI appropriate for slides
+    and posters. Default width is 7.0 inches for good visibility.
+
+    Parameters
+    ----------
+    width : float, optional
+        Default figure width in inches. Default is 7.0.
+    for_pdf : bool, optional
+        If True, configure for PDF output with embedded fonts.
+    font_family : str, optional
+        Font family to use. If None and for_pdf=True, uses 'Myriad Pro'.
+
+    Examples
+    --------
+    >>> import climplot
+    >>> climplot.presentation()  # Standard output
+    >>> climplot.presentation(for_pdf=True)  # PDF for slides
+
+    Notes
+    -----
+    Presentation mode settings:
+    - Figure width: 7.0" (full slide width)
+    - DPI: 150
+    - Axis labels: 14 pt
+    - Tick labels: 14 pt
+    - Title: 16 pt
+    - Legend: 12 pt
+    """
+    global _current_mode
+
+    settings = {
+        # Font sizes (presentation: larger, readable)
+        "font.size": 14,
+        "axes.labelsize": 14,
+        "axes.titlesize": 16,
+        "xtick.labelsize": 14,
+        "ytick.labelsize": 14,
+        "legend.fontsize": 12,
+        # Figure settings
+        "figure.figsize": (width, width * 0.6),
+        "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,
+        # PDF settings
+        "pdf.fonttype": 42,
+    }
+
+    if for_pdf:
+        if font_family is None:
+            font_family = "Myriad Pro"
+        settings["font.family"] = font_family
+
+    plt.rcParams.update(settings)
+    _current_mode = "presentation"
+
+
+def reset_style():
+    """
+    Reset matplotlib to default settings.
+
+    Restores all rcParams to their default values and clears the
+    current mode tracker.
+
+    Examples
+    --------
+    >>> climplot.publication()
+    >>> # ... make some figures ...
+    >>> climplot.reset_style()  # Back to defaults
+    """
+    global _current_mode
+
+    plt.rcdefaults()
+    _current_mode = None
+
+
+def get_current_mode() -> Optional[str]:
+    """
+    Get the currently active style mode.
+
+    Returns
+    -------
+    str or None
+        'publication', 'presentation', or None if no mode is set.
+
+    Examples
+    --------
+    >>> climplot.publication()
+    >>> climplot.get_current_mode()
+    'publication'
+    """
+    return _current_mode

climplot/timeseries.py

@@ -0,0 +1,110 @@
+"""
+Time series plotting utilities.
+
+This module provides functions for creating publication-quality time series
+plots with consistent styling.
+
+Examples
+--------
+>>> import climplot
+>>> climplot.publication()
+>>> fig, ax = climplot.timeseries_figure()
+>>> ax.plot(time, data)
+"""
+
+import matplotlib.pyplot as plt
+from typing import Tuple, Optional
+
+
+# Standard colors for model configurations
+CONFIG_COLORS = {
+    "obs": "#000000",  # Black - observations
+    "model": "#1f77b4",  # Blue - default model
+    "model1": "#1f77b4",  # Blue
+    "model2": "#ff7f0e",  # Orange
+    "model3": "#2ca02c",  # Green
+    "model4": "#d62728",  # Red
+    "model5": "#9467bd",  # Purple
+}
+
+# Standard line styles
+CONFIG_LINESTYLES = {
+    "obs": "--",  # Dashed for observations
+    "model": "-",  # Solid for models
+    "model1": "-",
+    "model2": "-",
+    "model3": "-",
+    "model4": "-",
+    "model5": "-",
+}
+
+
+def timeseries_figure(
+    figsize: Optional[Tuple[float, float]] = None,
+    grid: bool = True,
+    grid_alpha: float = 0.3,
+    **kwargs,
+) -> Tuple[plt.Figure, plt.Axes]:
+    """
+    Create a figure sized for time series plots.
+
+    Parameters
+    ----------
+    figsize : tuple, optional
+        Figure size (width, height) in inches. If None, uses (7.0, 3.5).
+    grid : bool, optional
+        Whether to add grid lines. Default is True.
+    grid_alpha : float, optional
+        Grid transparency. Default is 0.3.
+    **kwargs
+        Additional arguments passed to plt.subplots()
+
+    Returns
+    -------
+    fig : Figure
+        The figure object
+    ax : Axes
+        The axes object
+
+    Examples
+    --------
+    >>> fig, ax = climplot.timeseries_figure()
+    >>> ax.plot(time, data, label='Model')
+    >>> ax.set_xlabel('Year')
+    >>> ax.set_ylabel('Sea Level (m)')
+    >>> ax.legend()
+    """
+    if figsize is None:
+        figsize = (7.0, 3.5)
+
+    fig, ax = plt.subplots(figsize=figsize, **kwargs)
+
+    if grid:
+        ax.grid(True, alpha=grid_alpha, linewidth=0.3)
+
+    return fig, ax
+
+
+def get_config_style(config: str) -> dict:
+    """
+    Get standard style parameters for a configuration name.
+
+    Parameters
+    ----------
+    config : str
+        Configuration name (e.g., 'obs', 'model', 'model1')
+
+    Returns
+    -------
+    dict
+        Style parameters with 'color' and 'linestyle' keys
+
+    Examples
+    --------
+    >>> style = get_config_style('obs')
+    >>> ax.plot(time, data, **style)
+    """
+    return {
+        "color": CONFIG_COLORS.get(config, "#1f77b4"),
+        "linestyle": CONFIG_LINESTYLES.get(config, "-"),
+    }

climplot-0.1.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: climplot
+Version: 0.1.0
+Summary: Publication-quality climate science plotting utilities
+Author-email: John Krasting <john.krasting@noaa.gov>
+License: MIT
+Project-URL: Homepage, https://github.com/jkrasting/climplot
+Project-URL: Documentation, https://climplot.readthedocs.io
+Project-URL: Repository, https://github.com/jkrasting/climplot
+Keywords: climate,plotting,visualization,cartopy,xarray,oceanography
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: xarray>=2023.1
+Requires-Dist: cartopy>=0.21
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3; extra == "docs"
+Requires-Dist: sphinx-gallery>=0.14; extra == "docs"
+Requires-Dist: nbsphinx>=0.9; extra == "docs"
+Provides-Extra: all
+Requires-Dist: climplot[dev,docs]; extra == "all"
+Dynamic: license-file
+
+# climplot
+
+Publication-quality climate science plotting utilities for Python.
+
+**Mission:** Help climate science beginners make beautiful, publication-ready plots with minimal effort.
+
+## Features
+
+- **Style Modes**: Switch between publication and presentation styles with one function call
+- **Climate Colormaps**: Discrete colormaps optimized for anomaly fields, with center-on-white option
+- **Map Utilities**: Easy map creation with Cartopy projections
+- **Multi-panel Figures**: Consistent panel labeling and colorbars
+- **Area-weighted Metrics**: Accurate statistics for gridded climate data
+
+## Installation
+
+```bash
+pip install climplot
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/jkrasting/climplot.git
+cd climplot
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import climplot
+import matplotlib.pyplot as plt
+
+# Set publication style
+climplot.publication()
+
+# Create a map figure
+fig, ax = climplot.map_figure()
+
+# Plot with discrete colormap
+cmap, norm, levels = climplot.anomaly_cmap(-0.3, 0.3, 0.05)
+cs = ax.pcolormesh(lon, lat, data, cmap=cmap, norm=norm, transform=ccrs.PlateCarree())
+
+# Add colorbar
+climplot.add_colorbar(cs, ax, 'SSH Anomaly (m)')
+
+# Save
+climplot.save_figure('my_figure.png')
+plt.close()
+```
+
+## Style Modes
+
+### Publication Mode
+For journal figures with small, dense typography:
+- 3.5" width (single-column), 7.0" (two-column)
+- 8-11pt fonts
+- 300 DPI
+
+```python
+climplot.publication()  # Single column
+climplot.publication(width=7.0)  # Two-column
+climplot.publication(for_pdf=True)  # PDF with embedded fonts
+```
+
+### Presentation Mode
+For slides and posters with larger, readable typography:
+- 7.0" width
+- 12-16pt fonts
+- 150 DPI
+
+```python
+climplot.presentation()
+climplot.presentation(for_pdf=True)  # PDF for slides
+```
+
+## Colormaps
+
+### Anomaly Colormap
+Red-blue diverging, centered on zero:
+
+```python
+cmap, norm, levels = climplot.anomaly_cmap(-0.3, 0.3, 0.05)
+```
+
+### Center-on-White
+For difference plots where near-zero values should appear neutral:
+
+```python
+cmap, norm, levels = climplot.anomaly_cmap(-0.3, 0.3, 0.05, center_on_white=True)
+```
+
+## Maps
+
+```python
+# Robinson projection (Pacific-centered)
+fig, ax = climplot.map_figure()
+
+# Atlantic-centered
+fig, ax = climplot.map_figure(central_longitude=0)
+
+# Different projection
+fig, ax = climplot.map_figure(projection='mollweide')
+```
+
+## Multi-panel Figures
+
+```python
+# 2x3 panel figure
+fig, axes = climplot.panel_figure(2, 3)
+
+# Add panel labels (a. b. c. etc.)
+climplot.add_panel_labels(axes.flatten())
+
+# Single colorbar below all panels
+climplot.bottom_colorbar(cs, fig, axes, 'Temperature (K)')
+```
+
+## Area-weighted Metrics
+
+**Why area weighting matters:** Simple averaging over-weights polar regions.
+This can produce errors of ~1 cm in global sea level means.
+
+```python
+import climplot
+
+# Area-weighted mean (CORRECT)
+gmsl = climplot.area_weighted_mean(ssh, areacello, dim=['yh', 'xh'])
+
+# Simple mean (WRONG - ~1 cm error)
+# gmsl = ssh.mean(dim=['yh', 'xh'])
+
+# Other metrics
+bias = climplot.area_weighted_bias(model, obs, areacello, dim=['yh', 'xh'])
+rmse = climplot.area_weighted_rmse(model, obs, areacello, dim=['yh', 'xh'])
+corr = climplot.area_weighted_corr(model, obs, areacello, dim=['yh', 'xh'])
+
+# Comprehensive summary
+metrics = climplot.metrics_summary(model, obs, areacello, dim=['yh', 'xh'])
+climplot.print_metrics_summary(metrics, name='My Model')
+```
+
+## Dependencies
+
+- matplotlib >= 3.7
+- numpy >= 1.24
+- xarray >= 2023.1
+- cartopy >= 0.21
+
+## License
+
+MIT License - see [LICENSE](LICENSE)
+
+## Contributing
+
+Contributions are welcome! Please see our [contributing guide](CONTRIBUTING.md).

climplot-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+climplot/__init__.py,sha256=G2AtbrQNibpC_nTL7mQXtwxb-YR5GgOcywNmPM3kJv8,2399
+climplot/colormaps.py,sha256=HGqJ97OO00joQt0txTXJ96OW6f7oAtAAzHSirA5dnSM,7351
+climplot/maps.py,sha256=soGyPmfb1agkrFmW1W-Mh1z28gsrmtXKovd2n2DHk_Y,6412
+climplot/metrics.py,sha256=6TT9owbt0Wpm5M_pSeAoeuTs2W230gOMAYEqHIprbVw,10486
+climplot/panels.py,sha256=XRDUunjEMxE8WGuG8uiy_h8EahRkjkd3lbnCAfdbAG4,7375
+climplot/style.py,sha256=h2eShIWmoEvJiAgYMZIp6_uT8cTY8CDAhMkcNkqGZGE,5253
+climplot/timeseries.py,sha256=3GKaiLI1Mu8lk6dDSYtPFXB8PC5NA0-WhrO9qstP-xE,2564
+climplot/data/presentation.mplstyle,sha256=7HglEd230iXcig3WlDpelzkIrDfEvE4BOS3mL5bpbS8,787
+climplot/data/publication.mplstyle,sha256=yCPZbqRW2-ZK-00FXO_Ddzc-_lhQiYAKhftIcRrWIKY,771
+climplot-0.1.0.dist-info/licenses/LICENSE,sha256=ZiKJpFHnFzvheHo0qXxeGQFJYayoUCGRr9WIE3AAemM,1070
+climplot-0.1.0.dist-info/METADATA,sha256=q_eOT9SRaY_oDcskX-E-mb4qObDPAmirfCV_Bup7qgY,5316
+climplot-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+climplot-0.1.0.dist-info/top_level.txt,sha256=3b48RU3qa_y6oEFVqhZn5X_RsePmwRRjkuOQD0myfdM,9
+climplot-0.1.0.dist-info/RECORD,,

climplot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

climplot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Krasting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

climplot-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+climplot