arlmet.extract_subset#

arlmet.extract_subset(path, dest, *, bbox=None, levels=None, variables=None)[source]#

Extract a spatial/vertical subset from an ARL file into a new ARL file.

Parameters:

  • path (path-like) – Input ARL file.

  • dest (path-like) – Output ARL file. Overwrites any existing file. Must not be path.

  • bbox (tuple[float, float, float, float], optional) – Geographic bounding box (west, south, east, north) in degrees.

  • levels (iterable of int, optional) – ARL level indices to keep. Output levels are compacted and renumbered from zero while preserving the selected level heights.

  • variables (iterable of str, optional) – Variable names to keep. All variables are included by default.

Returns:

The output path, Path(dest). Open it with File or open_dataset() to read the subset.

Return type:

pathlib.Path

Raises:

ValueError – If dest is the same file as path, or the cropped grid is too small to hold the ARL index record.

Notes

The subset is written to a temporary file next to dest and renamed into place once complete, so an interrupted run never leaves a truncated file under the final name.

Without a horizontal crop (bbox is None or covers the whole grid), the selected records are copied byte for byte, with only their level numbers and the index records rewritten, which is much faster than unpacking and re-packing them. A crop re-packs each record’s window.

Examples

>>> import arlmet
>>> out = arlmet.extract_subset(
...     "met.arl",
...     "subset.arl",
...     bbox=(-114.0, 39.0, -110.0, 42.0),
...     levels=[0, 1, 2],
... )
>>> ds = arlmet.open_dataset(out)