Metadata-Version: 2.4
Name: metvision
Version: 2.0.0
Summary: CF-compliant meteorological data visualization toolkit
Author-email: Annick Terpstra <annick.terpstra@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/aterpstra/metvision
Project-URL: Documentation, https://metvision.readthedocs.io
Project-URL: Repository, https://github.com/aterpstra/metvision
Project-URL: Bug Tracker, https://github.com/aterpstra/metvision/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: xarray>=2023.1.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: cartopy>=0.22.0
Requires-Dist: netCDF4>=1.6.0
Requires-Dist: cmaps>=1.0.0
Requires-Dist: metpy>=1.5.0
Requires-Dist: cf-xarray>=0.8.0
Requires-Dist: pint-xarray>=0.3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.3.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: ruff>=0.0.282; extra == "dev"
Requires-Dist: mypy>=1.4.0; extra == "dev"
Requires-Dist: pre-commit>=3.3.0; extra == "dev"
Requires-Dist: ipykernel>=6.25.0; extra == "dev"
Requires-Dist: jupyterlab>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == "docs"

# 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)

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

### From PyPI (when released)

```bash
pip install metvision
```

### From Conda

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

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

Once built, install the package:

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

## Quick Start

```python
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/`:

```yaml
# 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
```python
# 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
```python
# 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
```python
# 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

```bash
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](https://xarray.dev/) - Labeled multi-dimensional arrays
- [cartopy](https://scitools.org.uk/cartopy/) - Geospatial data processing
- [matplotlib](https://matplotlib.org/) - Visualization
- [MetPy](https://unidata.github.io/MetPy/) - Meteorological calculations
- [cmaps](https://github.com/hhuangwx/cmaps) - Scientific colormaps

Aggregates >10 years of experience with gridded meteorological visualizations.
