MetVision

CF-compliant meteorological data visualization toolkit

MetVision provides a modern, Pythonic interface for creating publication-quality visualizations of numerical weather prediction (NWP) model output and observational data. Built on xarray, cartopy, and matplotlib, it handles the complexities of map projections, coordinate systems, and time handling so you can focus on your science.

Features

• 🗺️ Smart projection handling - Automatically infers projections from CF-compliant datasets
• 🎨 Flexible styling - YAML-based configuration for consistent, reusable plot settings
• ⏰ Robust time handling - Works with datetime, numpy.datetime64, pandas.Timestamp, or integer indices
• 🌍 Global coverage - Handles dateline crossing, polar regions, and various coordinate systems
• 📊 Publication ready - High-quality output with sensible defaults
• 🔧 Extensible - Clean API for custom overlays and extensions

Installation

From source (development)

git clone https://github.com/aterpstra/metvision.git
cd metvision
pip install -e ".[dev]"

From PyPI (when released)

pip install metvision

From Conda

To install the package using conda, first ensure you have conda-build installed. Then, build the package:

conda build conda-recipe --output-folder ~/conda-local

Once built, install the package:

conda install --use-local -c ~/conda-local metvision

Quick Start

import xarray as xr
from metvision import MetVisionFigure

# Load your CF-compliant dataset
ds = xr.open_dataset("model_output.nc")

# Create figure with automatic projection detection
fig = MetVisionFigure(ds, config="wrf.sfc")

# Build your visualization
fig.create_basemap()
fig.add_heatmap("t2m", time=0, cmap="RdYlBu_r")
fig.add_contours("slp", time=0, colors="black")
fig.add_wind_barbs("u10", "v10", time=0, thin=10)
fig.add_title("t2m", time=0)

# Save or display
fig.save("output.png", dpi=300)
# or: fig.show()

Architecture

metvision/
├── src/metvision/          # Main package
│   ├── __init__.py         # Public API
│   ├── figure.py           # MetVisionFigure class
│   ├── exceptions.py       # Custom exceptions
│   ├── logger.py           # Logging configuration
│   ├── time_utils.py       # Time handling utilities
│   ├── projections.py      # Projection utilities
│   ├── config/             # Configuration management
│   │   ├── loader.py       # YAML config loading
│   │   └── __init__.py
│   ├── overlays/           # Overlay modules (future)
│   ├── plt_settings/       # Plot configuration files
│   └── color_maps/         # Custom colormaps
├── tests/                  # Test suite
├── examples/               # Example notebooks
└── docs/                   # Documentation

Configuration

Plot settings (colormaps, contour levels, etc.) are defined in YAML files in plt_settings/:

# plt_settings/wrf.sfc.yaml
t2m:
    cmap: MPL_coolwarm
    bounds:
        min: 260
        max: 295
        step: 1

slp:
    cmap: MPL_ocean
    bounds:
        min: 980
        max: 1030
        step: 2
    colors: darkgrey

Core Overlay Methods

MetVisionFigure provides intuitive methods for building complex visualizations:

Heatmaps & Contours

# Heatmap (pcolormesh)
fig.add_heatmap("t2m", time=0, cmap="RdYlBu_r", alpha=0.8)

# Contour lines
fig.add_contours("slp", time=0, levels=np.arange(980, 1030, 4), colors="black")

# Filled contours
fig.add_contourf("slp", time=0, cmap="viridis", extend="both")

Wind Vectors

# Wind barbs (meteorological convention)
fig.add_wind_barbs("u10", "v10", time=0, thin=10, color="black")

# Quiver arrows
fig.add_quiver("u10", "v10", time=0, thin=8, scale=100)

Annotations

# Points (stations, cities, etc.)
fig.add_points(lons, lats, color="red", size=50, marker="^")

# Bounding boxes
fig.add_bbox(lon_min, lon_max, lat_min, lat_max, color="red", linewidth=2)

All methods support:

• Automatic config loading from YAML
• Manual override of any parameter
• Full matplotlib customization via **kwargs
• Proper coordinate transformations

What's New in v2.0

Complete rewrite with modern Python best practices:

• ✅ Proper package structure with pyproject.toml
• ✅ Type hints throughout
• ✅ Comprehensive error handling with custom exceptions
• ✅ Improved time handling (supports multiple formats)
• ✅ Safe configuration loading (no more eval())
• ✅ Better projection detection
• ✅ Cleaner API with MetVisionFigure class
• ✅ Upgraded Cross-section class
• ✅ Test suite with pytest

Breaking changes from v1.x:

• New import: from metvision import MetVisionFigure
• Configuration loading moved to internal module
• Simplified function signatures

Development

Running Tests

pytest tests/

Contributing

Contributions welcome! This is actively being refactored. Please open an issue to discuss major changes.

License

MIT License - See LICENSE file for details

Authors

• Annick Terpstra (@aterpstra)

Acknowledgments

Built with:

• xarray - Labeled multi-dimensional arrays
• cartopy - Geospatial data processing
• matplotlib - Visualization
• MetPy - Meteorological calculations
• cmaps - Scientific colormaps

Aggregates >10 years of experience with gridded meteorological visualizations.