arlmet 0.1.0a1__tar.gz

arlmet-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 James Mineau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arlmet-0.1.0a1/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: arlmet
+Version: 0.1.0a1
+Summary: Read and write ARL meteorological files.
+Author-email: James Mineau <jameskmineau@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jmineau/arl-met
+Project-URL: Documentation, https://jmineau.github.io/arl-met/
+Project-URL: Repository, https://github.com/jmineau/arl-met
+Project-URL: Issues, https://github.com/jmineau/arl-met/issues
+Keywords: arl,hysplit,meteorology,atmospheric-science,xarray
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyproj>=3.5
+Requires-Dist: xarray>=2023.6
+Provides-Extra: sources
+Requires-Dist: fsspec>=2024.2; extra == "sources"
+Requires-Dist: s3fs>=2024.2; extra == "sources"
+Dynamic: license-file
+
+# arl-met
+
+[![Tests](https://github.com/jmineau/arl-met/actions/workflows/tests.yml/badge.svg)](https://github.com/jmineau/arl-met/actions/workflows/tests.yml)
+[![Documentation](https://github.com/jmineau/arl-met/actions/workflows/docs.yml/badge.svg)](https://github.com/jmineau/arl-met/actions/workflows/docs.yml)
+[![Code Quality](https://github.com/jmineau/arl-met/actions/workflows/quality.yml/badge.svg)](https://github.com/jmineau/arl-met/actions/workflows/quality.yml)
+[![codecov](https://codecov.io/gh/jmineau/arl-met/branch/main/graph/badge.svg)](https://codecov.io/gh/jmineau/arl-met)
+[![PyPI version](https://badge.fury.io/py/arlmet.svg)](https://badge.fury.io/py/arlmet)
+[![Python Version](https://img.shields.io/pypi/pyversions/arlmet.svg)](https://pypi.org/project/arlmet/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Pyright](https://img.shields.io/badge/pyright-checked-brightgreen.svg)](https://github.com/microsoft/pyright)
+
+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()`
+- crop-before-unpack subset extraction with `extract_subset()`
+- NOAA source fetching helpers for common ARL archives
+- vertical helper functions such as `pressure()`, `z_agl()`, and `z_msl()`
+
+## 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:
+
+```bash
+pip install arlmet
+```
+
+Install the optional source-fetching dependencies:
+
+```bash
+pip install "arlmet[sources]"
+```
+
+For development:
+
+```bash
+git clone https://github.com/jmineau/arl-met.git
+cd arl-met
+uv sync --dev
+```
+
+## Quick examples
+
+Open an ARL file as a Dataset:
+
+```python
+import arlmet
+
+ds = arlmet.open_dataset("met.arl")
+print(ds)
+```
+
+Modify a Dataset and write it back:
+
+```python
+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:
+
+```python
+import arlmet
+
+arlmet.extract_subset(
+    "met.arl",
+    "subset.arl",
+    bbox=(-114.0, 39.0, -110.0, 42.0),
+    levels=[0, 1, 2],
+)
+```
+
+Use the low-level writer for irregular layouts:
+
+```python
+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")
+```
+
+## Resources
+
+Documentation is available at https://jmineau.github.io/arl-met/
+
+Useful ARL/HYSPLIT references:
+
+- [HYSPLIT User Guide](https://www.arl.noaa.gov/documents/reports/hysplit_user_guide.pdf) for the broader model and file-format context.
+- [HYSPLIT meteorology page](https://www.ready.noaa.gov/hysplitusersguide/S141.htm) for the ARL meteorology format overview.
+- [READY archive](https://www.ready.noaa.gov/archives.php) for the available meteorology archives.
+- [GDAS1 packing notes](https://www.ready.noaa.gov/gdas1.php) for a concrete example of ARL packing behavior.
+
+Related project:
+
+- [ARLreader](https://github.com/martin-rdz/ARLreader), which focuses on GDAS1 files, while `arl-met` targets a broader ARL/xarray workflow.
+
+## Release notes
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development
+setup and contribution guidelines.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

arlmet-0.1.0a1/README.md

@@ -0,0 +1,161 @@
+# arl-met
+
+[![Tests](https://github.com/jmineau/arl-met/actions/workflows/tests.yml/badge.svg)](https://github.com/jmineau/arl-met/actions/workflows/tests.yml)
+[![Documentation](https://github.com/jmineau/arl-met/actions/workflows/docs.yml/badge.svg)](https://github.com/jmineau/arl-met/actions/workflows/docs.yml)
+[![Code Quality](https://github.com/jmineau/arl-met/actions/workflows/quality.yml/badge.svg)](https://github.com/jmineau/arl-met/actions/workflows/quality.yml)
+[![codecov](https://codecov.io/gh/jmineau/arl-met/branch/main/graph/badge.svg)](https://codecov.io/gh/jmineau/arl-met)
+[![PyPI version](https://badge.fury.io/py/arlmet.svg)](https://badge.fury.io/py/arlmet)
+[![Python Version](https://img.shields.io/pypi/pyversions/arlmet.svg)](https://pypi.org/project/arlmet/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Pyright](https://img.shields.io/badge/pyright-checked-brightgreen.svg)](https://github.com/microsoft/pyright)
+
+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()`
+- crop-before-unpack subset extraction with `extract_subset()`
+- NOAA source fetching helpers for common ARL archives
+- vertical helper functions such as `pressure()`, `z_agl()`, and `z_msl()`
+
+## 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:
+
+```bash
+pip install arlmet
+```
+
+Install the optional source-fetching dependencies:
+
+```bash
+pip install "arlmet[sources]"
+```
+
+For development:
+
+```bash
+git clone https://github.com/jmineau/arl-met.git
+cd arl-met
+uv sync --dev
+```
+
+## Quick examples
+
+Open an ARL file as a Dataset:
+
+```python
+import arlmet
+
+ds = arlmet.open_dataset("met.arl")
+print(ds)
+```
+
+Modify a Dataset and write it back:
+
+```python
+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:
+
+```python
+import arlmet
+
+arlmet.extract_subset(
+    "met.arl",
+    "subset.arl",
+    bbox=(-114.0, 39.0, -110.0, 42.0),
+    levels=[0, 1, 2],
+)
+```
+
+Use the low-level writer for irregular layouts:
+
+```python
+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")
+```
+
+## Resources
+
+Documentation is available at https://jmineau.github.io/arl-met/
+
+Useful ARL/HYSPLIT references:
+
+- [HYSPLIT User Guide](https://www.arl.noaa.gov/documents/reports/hysplit_user_guide.pdf) for the broader model and file-format context.
+- [HYSPLIT meteorology page](https://www.ready.noaa.gov/hysplitusersguide/S141.htm) for the ARL meteorology format overview.
+- [READY archive](https://www.ready.noaa.gov/archives.php) for the available meteorology archives.
+- [GDAS1 packing notes](https://www.ready.noaa.gov/gdas1.php) for a concrete example of ARL packing behavior.
+
+Related project:
+
+- [ARLreader](https://github.com/martin-rdz/ARLreader), which focuses on GDAS1 files, while `arl-met` targets a broader ARL/xarray workflow.
+
+## Release notes
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development
+setup and contribution guidelines.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

arlmet-0.1.0a1/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "arlmet"
+version = "0.1.0a1"
+description = "Read and write ARL meteorological files."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    {name = "James Mineau", email = "jameskmineau@gmail.com"}
+]
+keywords = ["arl", "hysplit", "meteorology", "atmospheric-science", "xarray"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "pyproj>=3.5",
+    "xarray>=2023.6",
+]
+
+[project.optional-dependencies]
+sources = ["fsspec>=2024.2", "s3fs>=2024.2"]
+
+[dependency-groups]
+dev = [
+    "arlmet[sources]",
+    "build>=1.2",
+    "docstr-coverage>=2.0.0",
+    "pydata-sphinx-theme>=0.14.0",
+    "pre-commit>=3.0.0",
+    "pyright>=1.1.0",
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+    "rust-just>=1.42.4",
+    "sphinx>=7.0.0",
+    "sphinx-autodoc-typehints>=1.24.0",
+    "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jmineau/arl-met"
+Documentation = "https://jmineau.github.io/arl-met/"
+Repository = "https://github.com/jmineau/arl-met"
+Issues = "https://github.com/jmineau/arl-met/issues"
+
+[tool.coverage.run]
+source = ["src/arlmet"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.uv]
+required-version = ">=0.10.4"
+
+[tool.coverage.report]
+# Regexes for lines to exclude from consideration
+exclude_also = [
+    # Don't complain about missing debug-only code:
+    "def __repr__",
+    "if self\\.debug",
+
+    # Don't complain if tests don't hit defensive assertion code:
+    "raise AssertionError",
+    "raise NotImplementedError",
+
+    # Don't complain if non-runnable code isn't run:
+    "if 0:",
+    "if __name__ == .__main__.:",
+
+    # Don't complain about abstract methods, they aren't run:
+    "@(abc\\.)?abstractmethod",
+    ]
+
+[tool.pyright]
+include = ["src"]
+exclude = ["**/__pycache__", "**/.venv"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "network: requires live network access to external services such as NOAA S3",
+    "slow: expensive runtime, bandwidth, or disk usage; excluded from default test runs",
+]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle
+    "F",  # Pyflakes
+    "UP",  # pyupgrade
+    "B",  # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "I",  # isort
+    "D213",  # multi-line summary should start at the second line
+]
+ignore = [
+    "D212",  # incompatible with D213; keep summaries on the second line
+    "E501",  # line too long, handled by formatter
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["arlmet"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"arlmet" = ["py.typed", "resources/*"]

arlmet-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

arlmet-0.1.0a1/src/arlmet/__init__.py

@@ -0,0 +1,63 @@
+"""
+arlmet: Python package for reading and analyzing NOAA ARL meteorological files.
+
+This package provides tools to read, parse, and work with ARL (Air Resources Laboratory)
+packed meteorological data files used by HYSPLIT and other atmospheric transport models.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as package_version
+from pathlib import Path
+import re
+
+
+def _detect_version() -> str:
+    try:
+        return package_version("arlmet")
+    except PackageNotFoundError:
+        pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+        match = re.search(
+            r'^version\s*=\s*"([^"]+)"',
+            pyproject.read_text(encoding="utf-8"),
+            flags=re.MULTILINE,
+        )
+        if match is None:
+            return "0+unknown"
+        return match.group(1)
+
+
+__version__ = _detect_version()
+__author__ = "James Mineau"
+__email__ = "jmineau@gmail.com"
+
+from .file import File
+from .grid import Grid, Projection
+from .header import Header
+from .index import IndexRecord
+from .packing import calculate_checksum, pack, unpack
+from .record import DataRecord
+from .recordset import RecordSet
+from .sampling import sample_points
+from .subset import extract_subset
+from .vertical import VerticalAxis
+from .xarray import open_dataset, pressure, write_dataset, z_agl, z_msl
+
+__all__ = [
+    "File",
+    "RecordSet",
+    "DataRecord",
+    "open_dataset",
+    "write_dataset",
+    "pressure",
+    "z_agl",
+    "z_msl",
+    "Projection",
+    "Grid",
+    "VerticalAxis",
+    "Header",
+    "IndexRecord",
+    "calculate_checksum",
+    "pack",
+    "unpack",
+    "extract_subset",
+    "sample_points",
+]

arlmet-0.1.0a1/src/arlmet/_time.py

@@ -0,0 +1,21 @@
+"""Internal timestamp normalization helpers."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import pandas as pd
+
+
+def ensure_timestamp(value: Any, *, floor: str | None = None) -> pd.Timestamp:
+    """Return a concrete pandas.Timestamp, rejecting NaT values."""
+    ts = value if isinstance(value, pd.Timestamp) else pd.Timestamp(value)
+    if pd.isna(ts):
+        raise ValueError(f"Invalid timestamp value: {value!r}")
+    if floor is not None:
+        ts = ts.floor(floor)
+        if pd.isna(ts):
+            raise ValueError(
+                f"Invalid timestamp value after floor({floor!r}): {value!r}"
+            )
+    return cast(pd.Timestamp, ts)