🌐 MPAS-Viewer

A Python package for efficient visualization of the MPAS-Atmosphere unstructured mesh

---

📄 Publication

This package has been published in a peer-reviewed software journal:

Mendez and Temimi. (2026). MPAS-viewer: A Python package for an efficient visualization of the MPAS-atmosphere unstructured mesh
SoftwareX.
🔗 https://www.sciencedirect.com/science/article/pii/S2352711025004637

If you use this package in your research, please consider citing the paper.

---

🥈 Award

This tool was selected as one of the award winners, with the presentation, Python-based visualization of MPAS data in its native unstructured grid at the Fifth Symposium on Community Modeling and Innovation, during the 106th Annual Meeting of the American Meteorological Society (AMS2026).
🔗 https://www.linkedin.com/posts/jhbravo_ams2026-activity-7430397403347972096-Khrb

---

🎯 Key Features

• ⚡ Fast rendering on native unstructured MPAS mesh
• 🌍 Supports both global and regional domains
• 📦 Lightweight and easy to install (minimal dependencies)
• 📈 Accurate representation of MPAS-A data without resampling
• 🧩 Compatible with NetCDF outputs from MPAS-A
• 💻 Portable across platforms (Linux, macOS, Windows)

---

📦 Installation

You can install MPAS-Viewer directly from GitHub:

uv add "mpasviewer @ https://github.com/jhbravo/mpasviewer.git"

pip install git+https://github.com/jhbravo/mpasviewer.git

---

🛠️ Prerequisites

To use MPAS-Viewer, you’ll need the following Python packages:

• Python 3.10+ xarray dask numpy matplotlib cartopy

Optional:

• earthcmap — common colormaps for consistent and appropriate visualization
• fsspec — abstract file system layer (e.g. S3, GCS, HTTPS)
• zarr — for chunked, compressed, cloud-optimized data

---

🌍 🌎 🌏 Examples of Use

Below are a few basic examples showing how to use MPAS-Viewer to load and visualize MPAS data, demonstrating different capabilities. To help you get started with MPAS-Viewer, we provide sample MPAS-A datasets that you can download from the following HydroShare repository :

• 00_general_use.ipynb Basic usage example showing how to load MPAS data and generate a simple plot.

• 01_projection.ipynb How to visualize MPAS data in different projections.

• 02_static.ipynb Visualization of standard MPAS invariant variables.

• 03_out.ipynb Visualization of standard MPAS output variables.

• 04_widget.ipynb Interactive visualization using widgets for dynamic variable and time selection.

• 05_out_wofs.ipynb Example using WoFS data, including visualization of forecast output on the MPAS mesh.

• 06_graf15m.ipynb remote access to GRAF ZARR data with 15-minute forecast interval visualization.

• 07_graf05m.ipynb remote access to GRAF ZARR data with 5-minute high-frequency precipitation forecast.

• 08_out_ocean.ipynb Example demonstrating visualization of MPAS-Ocean output.

• 09_out_seaice.ipynb Visualization of MPAS-Seaiceoutputs.

• 10_out_chem.ipynb Example how to visualize MPAS-Chem PM2.5 output.

• 11_out_mpas-jedi.ipynb Visualization of MPAS-JEDI diag output fields.

• 12_out_mpas-jedi-out.ipynb Visualization of MPAS-JEDI mpasout output fields.

• 13_out_mpas-jedi-da_an.ipynb Visualization of MPAS-JEDI data assimilation an fields.

• 14_out_mpas-jedi-da_bg.ipynb Visualization of MPAS-JEDI data assimilation bg fields.

---

🗺️ Basic usage

# Initialize the main object by providing the mesh file (grid or static)
# and the diagnostic output data (single file or directory)
from mpasviewer import scvtmesh

mpasd = scvtmesh(
    grid_file='/path/to/some/file.grid.nc', 
    diag_list='/path/to/some/list/of/files/diag'
)

# Load dataset metadata and variable structure
mpasd.dataset()

# (Optional) Compute rain rate from output variables, if applicable
mpasd.rain_rate()


# Load the full dataset (with Dask support if enabled)
dta = mpasd.load()

# Plot a specific variable as a spatial map at a given time index
mpasd.show(dta, var_name='variable', time_index='yyyy-mm-ddTHH')