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)
• finding damage that does not stop a file from opening (a time step written partway, a missing time step) with File.check()
• finding the files that cover a time window by their headers, not their names, with index()

Status

arl-met is in beta. The core API is settled enough to build on, but it may still change before 1.0; breaking changes are marked Breaking in the changelog.

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, with sigma, hybrid and pressure-level heights found as HYSPLIT finds them (the PRES field when a sigma file has it, the virtual temperature, from the ground up, pressure levels below the ground left out)
• tested support for Python 3.11 through 3.14

Known limitations:

• write_dataset() is intentionally conservative and targets the flat common-case Dataset contract
• DIF* records are paired with their parent by HYSPLIT's name table only (DIFW with WWND or DZDT, DIFT with TKEN or TKEU, any surface DIF* with TPP* or PRT*); any other DIF* record is applied to nothing, with a warning, and the writers refuse other pairs
• rotated grids are not implemented
• on WRF hybrid files (vertical flag 5), pressure is the PRES field and heights are found from it as on a sigma file, as HYSPLIT does without WRF's hybrid coefficients, which the ARL file does not hold

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
uv run pre-commit install
just quality-check   # lint, type check, docstrings, tests

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 128 met files for one grid, and 12 when each file is its own grid):

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

Check a file for damage before a HYSPLIT run:

import arlmet

with arlmet.File("20210226_18-23_hrrr") as met:
    print(met.check())  # [] for a whole file

Find the files that cover a time window from their headers, whatever they are named:

import arlmet

idx = arlmet.index("hrrr/")  # reads each file's index records once, then caches them
# arlmet.index("hrrr/", recursive=True) for a copy of NOAA's hrrr/YYYY/MM/ folders
idx.covering("2021-01-14 06:00", "2021-01-15 06:00")  # the files, in time order
idx.missing("2021-01-14 06:00", "2021-01-15 06:00")  # the hours no file holds

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.