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()
• NOAA source fetching helpers for common ARL archives
• 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)

This is an alpha release. The core read/write/subset APIs are usable, but the package is still tightening its high-level contracts and release surface.

Current 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.10 through 3.12

Current 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 is not implemented

Install the core package:

pip install arlmet

Install the optional source-fetching dependencies:

pip install "arlmet[sources]"

For development:

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

Open an ARL file as a Dataset:

import arlmet

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

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],
)

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.VerticalAxis(flag=2, 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")

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.

See CHANGELOG.md for release history.

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

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