arl-met

Read, write, subset, and sample NOAA ARL meteorological files.

arl-met provides a Python-first interface to the ARL packed meteorology format used by HYSPLIT and related workflows. It supports:

• low-level record-preserving reads and writes through File, RecordSet, and DataRecord
• xarray Dataset reads and common-case writes through open_dataset() and write_dataset(), plus an xarray backend (xr.open_dataset(path, engine="arl"))
• downloading from NOAA's ARL archives (HRRR, NAM, GDAS, GFS, ...) with optional crop-on-download
• crop-before-unpack subset extraction with extract_subset()
• vertical helper functions such as pressure(), z_agl(), and z_msl()
• point sampling with sample_points()
• joining files with concat() and concat_by_time() (e.g. 6-hourly into daily)

Status and stability

arl-met is in beta: the public API (everything in arlmet.__all__, the arlmet.archives module, the ds.arl accessor, and the engine="arl" xarray backend) is frozen, and breaking changes are rare and always flagged in the changelog. See the API stability policy for what counts as public and how versions change.

Strengths:

• low-level ARL fidelity, including preservation of trailing DIF* records
• xarray-native analysis workflow for common ARL files
• direct subset extraction and point sampling
• tested support for Python 3.11 through 3.14

Known limitations:

• write_dataset() is intentionally conservative and targets the flat common-case Dataset contract
• complex multi-record DIFF chains are not tested
• WRF vertical flag 5 and rotated grids are not implemented

Installation

Install the core package:

pip install arlmet

Install the optional archive-download dependencies:

pip install "arlmet[archives]"

For development:

git clone https://github.com/jmineau/arl-met.git
cd arl-met
uv sync --dev

Quick examples

Open an ARL file as a Dataset:

import arlmet

ds = arlmet.open_dataset("met.arl")
print(ds)

# or through xarray, e.g. to get dask-backed arrays
import xarray as xr
ds = xr.open_dataset("met.arl", engine="arl", chunks={"time": 1})

Modify a Dataset and write it back:

import arlmet

ds = arlmet.open_dataset("met.arl")
ds["TEMP"] = ds["TEMP"] - 273.15
ds["WWND"].attrs["diff"] = "DIFW"
arlmet.write_dataset(ds, "edited.arl")

Extract a subset without unpacking the full file first:

import arlmet

arlmet.extract_subset(
    "met.arl",
    "subset.arl",
    bbox=(-114.0, 39.0, -110.0, 42.0),
    levels=[0, 1, 2],
)  # returns the output path (a pathlib.Path)

Join short files into longer ones (HYSPLIT accepts at most 12 met files per run):

import arlmet

# join a list of files into one (ordered by valid time)
arlmet.concat(["20240101_00_hrrr", "20240101_06_hrrr"], "20240101_hrrr")

# or batch a whole directory into daily files
arlmet.concat_by_time(
    "hrrr/", "daily/", freq="1D", pattern="*_hrrr", template="{time:%Y%m%d}_hrrr"
)

Use the low-level writer for irregular layouts:

import numpy as np
import pandas as pd
import arlmet

grid = arlmet.Grid(
    projection=arlmet.Projection(
        pole_lat=90.0,
        pole_lon=0.0,
        tangent_lat=1.0,
        tangent_lon=1.0,
        grid_size=0.0,
        orientation=0.0,
        cone_angle=0.0,
        sync_x=1.0,
        sync_y=1.0,
        sync_lat=-10.0,
        sync_lon=20.0,
    ),
    nx=20,
    ny=20,
)
vertical_axis = arlmet.PressureAxis(levels=[0.0, 1000.0])
time = pd.Timestamp("2024-07-18 00:00")

prss = np.ones((grid.ny, grid.nx), dtype=np.float32)
wwnd = np.ones((grid.ny, grid.nx), dtype=np.float32)

with arlmet.File("custom.arl", mode="w", source="TEST", grid=grid, vertical_axis=vertical_axis) as arl:
    rs = arl.create_recordset(time, forecast=0)
    rs.create_datarecord("PRSS", level=0, forecast=0, data=prss)
    rs.create_datarecord("WWND", level=1, forecast=0, data=wwnd, diff="DIFW")

Records are held in memory until the file is flushed or closed. When writing many time steps, call arl.flush() after filling each one so memory stays bounded by a single time step.

Resources

Documentation is available at https://jmineau.github.io/arl-met/

Useful ARL/HYSPLIT references:

• HYSPLIT User Guide for the broader model and file-format context.
• HYSPLIT meteorology page for the ARL meteorology format overview.
• READY archive for the available meteorology archives.
• GDAS1 packing notes for a concrete example of ARL packing behavior.

Related project:

• ARLreader, which focuses on GDAS1 files, while arl-met targets a broader ARL/xarray workflow.

Release notes

See CHANGELOG.md for release history.

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup and contribution guidelines.

Use of AI coding agents

This project is developed with the help of AI coding agents, directed and reviewed by the maintainer, who owns the design and the science.

License

This project is licensed under the MIT License. See LICENSE.