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()
• 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)

Alpha status

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

Installation

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

Quick examples

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],
).close()  # returns the new file opened for reading

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").close()

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

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.