noaa-gml-file-reader 2.0.0__py3-none-any.whl

noaa_gml_file_reader/__init__.py

@@ -0,0 +1,16 @@
+"""noaa-gml-file-reader — read NOAA GML trace-gas ASCII files as DataFrames.
+
+Public API: :func:`read_data`. The parsing implementation lives in
+:mod:`noaa_gml_file_reader._reader`; the license is governed by the LICENSE file.
+"""
+
+# Local imports.
+from noaa_gml_file_reader._reader import read_data, UnrecognizedFormatError
+
+# Dunder definitions.
+#  - Versioning system: {major_version}.{minor_version}.{patch}
+#  - Single-sourced here; pyproject.toml reads __version__ from this module.
+__author__  = "Erick Edward Shepherd"
+__version__ = "2.0.0"
+
+__all__ = ["read_data", "UnrecognizedFormatError", "__version__"]

noaa_gml_file_reader/_reader.py

@@ -0,0 +1,138 @@
+"""Internal parsing implementation for noaa-gml-file-reader.
+
+Parses NOAA GML trace-gas ASCII files into pandas DataFrames, auto-detecting the
+header dialect (legacy ``# number_of_header_lines:`` vs current
+``# header_lines :``). See ``docs/format-notes.md`` for the observed grammars.
+"""
+
+# Standard library imports.
+import re
+
+# Third party imports.
+import pandas as pd
+
+# The data section is whitespace-delimited (variable-width columns).
+_DATA_DELIMITER = r"\s+"
+
+# Documented missing-value sentinels (docs/format-notes.md), mapped to NaN so
+# numeric columns parse numeric instead of being dragged to object/float fill.
+_NA_VALUES = ["-999.99", "-999.999", "nan"]
+
+
+class UnrecognizedFormatError(Exception):
+    """Raised when a file's header matches no known NOAA GML dialect.
+
+    Carries the offending ``path`` and the file's ``first_header_line`` so the
+    failure is explicit and diagnosable (replacing v1's silent empty DataFrame).
+    """
+
+    def __init__(self, path: str, first_header_line: str) -> None:
+        self.path = path
+        self.first_header_line = first_header_line
+        super().__init__(
+            f"Unrecognized NOAA GML file format: {path!r} — no "
+            f"'number_of_header_lines'/'header_lines' header key found or the "
+            f"header is truncated (first line: {first_header_line!r})."
+        )
+
+
+# Header-length keys, one per dialect. ``\s*`` around the colon tolerates the
+# observed spacing variants ("number_of_header_lines: N" vs "header_lines : N").
+# The legacy key is tried first: "header_lines" is a substring of
+# "number_of_header_lines", so a legacy line must not fall through to the
+# current pattern.
+_LEGACY_HEADER_RE  = re.compile(r"^#\s*number_of_header_lines\s*:\s*(?P<n>\d+)")
+_CURRENT_HEADER_RE = re.compile(r"^#\s*header_lines\s*:\s*(?P<n>\d+)")
+
+# The legacy dialect conveys column names via a "# data_fields:" header line.
+_DATA_FIELDS_RE = re.compile(r"^#\s*data_fields\s*:\s*(?P<fields>.+)")
+
+
+def _detect_header(lines: list[str]) -> tuple[str | None, int | None]:
+    """Return ``(dialect, header_count)`` from the header, or ``(None, None)``.
+
+    ``dialect`` is ``"legacy"`` or ``"current"``; ``header_count`` is the number
+    of leading header lines (the data section begins on the next line).
+    """
+    for line in lines:
+        match = _LEGACY_HEADER_RE.match(line)
+        if match:
+            return "legacy", int(match.group("n"))
+        match = _CURRENT_HEADER_RE.match(line)
+        if match:
+            return "current", int(match.group("n"))
+    return None, None
+
+
+def _column_names(
+    lines: list[str], dialect: str, header_count: int
+) -> list[str] | None:
+    """Extract the column names per dialect, or ``None`` if absent.
+
+    Legacy: the ``# data_fields:`` header line. Current: the bare (non-``#``)
+    column row that is the last header line (line ``header_count``, 1-indexed).
+    """
+    if dialect == "legacy":
+        for line in lines[:header_count]:
+            match = _DATA_FIELDS_RE.match(line)
+            if match:
+                return match.group("fields").split()
+        return None
+    # Current dialect: names are the last header line. A truncated file whose
+    # declared header extends past EOF has no column row -> unrecognized.
+    if header_count < 1 or header_count > len(lines):
+        return None
+    return lines[header_count - 1].split()
+
+
+def read_data(path: str) -> pd.DataFrame:
+
+    '''
+
+    Read a NOAA GML trace-gas ASCII file into a ``pandas.DataFrame``.
+
+    The header dialect is auto-detected and both are supported: the legacy
+    ``# number_of_header_lines:`` form (column names from ``# data_fields:``)
+    and the current ``# header_lines :`` form (column names from the bare
+    column row that is the last header line). Documented missing-value
+    sentinels (``-999.99``, ``-999.999``, ``nan``) are mapped to ``NaN`` so
+    numeric columns parse numeric.
+
+    :param path: The path to the data file.
+    :type path:  str
+
+    :return:     The parsed file data, one column per header field.
+    :rtype:      pandas.DataFrame
+
+    :raises UnrecognizedFormatError: If no known header dialect is detected or
+        the header is truncated. (In v1 this was a silent empty DataFrame.)
+
+    '''
+
+    with open(path) as file:
+        lines = file.readlines()
+
+    first_header_line = lines[0].rstrip("\n") if lines else ""
+
+    dialect, header_count = _detect_header(lines)
+
+    # No recognized header key: fail loudly instead of returning an empty frame.
+    if dialect is None:
+        raise UnrecognizedFormatError(path, first_header_line)
+
+    names = _column_names(lines, dialect, header_count)
+    if names is None:
+        raise UnrecognizedFormatError(path, first_header_line)
+
+    # One generic read for both dialects: skip the N header lines and apply the
+    # per-dialect column names. engine="python" is required for the regex
+    # separator under pandas >= 2; na_values maps the documented sentinels to
+    # NaN so numeric columns parse numeric.
+    return pd.read_csv(
+        path,
+        sep       = _DATA_DELIMITER,
+        engine    = "python",
+        names     = names,
+        skiprows  = header_count,
+        na_values = _NA_VALUES,
+    )

noaa_gml_file_reader-2.0.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: noaa-gml-file-reader
+Version: 2.0.0
+Summary: Read NOAA GML atmospheric trace-gas ASCII data files as pandas DataFrames.
+Project-URL: Homepage, https://github.com/ErickShepherd/noaa-gml-file-reader
+Author-email: Erick Edward Shepherd <Contact@ErickShepherd.com>
+Maintainer-email: Erick Edward Shepherd <Contact@ErickShepherd.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: CH4,CO2,GMD,GML,NOAA,atmospheric,pandas,trace gases
+Classifier: Development Status :: 5 - Production/Stable
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Requires-Dist: pandas>=2.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# noaa-gml-file-reader
+
+[![CI](https://github.com/ErickShepherd/noaa-gml-file-reader/actions/workflows/ci.yml/badge.svg)](https://github.com/ErickShepherd/noaa-gml-file-reader/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Read [NOAA GML](https://gml.noaa.gov) atmospheric trace-gas ASCII data files as
+[`pandas.DataFrame`](https://pandas.pydata.org/) objects — one function,
+`read_data(path)`.
+
+## What this reads
+
+NOAA's Global Monitoring Laboratory (GML) publishes long-term atmospheric
+trace-gas measurements (CO₂, CH₄, and others) as whitespace-delimited ASCII
+files with a `#`-commented header — surface-flask **event** and **monthly**
+series, in-situ **hourly**/daily series, and more, at
+[gml.noaa.gov/aftp/data/trace_gases](https://gml.noaa.gov/aftp/data/trace_gases/).
+This package turns one of those files into a tidy DataFrame, with the header's
+column names and the documented missing-value sentinels handled for you.
+
+> **Lineage (GMD → GML).** NOAA renamed ESRL's Global Monitoring *Division*
+> (GMD) to the Global Monitoring *Laboratory* (GML) in 2020, and the file header
+> format changed with it. This package was originally `noaa_esrl_gmd_file_reader`
+> (2020); v2 renames it to **noaa-gml-file-reader** (import `noaa_gml_file_reader`)
+> and reads the current header format. See the breaking-change note below.
+
+## Install
+
+```bash
+pip install noaa-gml-file-reader
+```
+
+Requires Python ≥ 3.10 and pandas ≥ 2.0. (Not yet on PyPI — install from source:
+`pip install git+https://github.com/ErickShepherd/noaa-gml-file-reader`.)
+
+## Usage
+
+```python
+from noaa_gml_file_reader import read_data
+
+df = read_data("co2_mlo_surface-flask_1_ccgg_month.txt")
+print(df.head())
+```
+
+Real output (from the committed test fixture of the above Mauna Loa monthly file):
+
+```
+  site  year  month   value
+0  MLO  1969      8  322.50
+1  MLO  1969      9  321.36
+2  MLO  1969     10  320.74
+3  MLO  1969     11  321.98
+4  MLO  1969     12  323.78
+```
+
+Columns come straight from the file's header; numeric columns are numeric
+(`value` is `float64`, `year`/`month` are `int64`), and NOAA's missing-value
+sentinels (`-999.99`, `-999.999`, `nan`) are parsed as `NaN`.
+
+## Supported dialects
+
+`read_data` auto-detects the header dialect — you don't need to know NOAA's
+format history to read a file:
+
+| dialect | header key | column names from | seen in |
+| --- | --- | --- | --- |
+| **current** | `# header_lines : N` | the bare column row that is the last header line | flask **event**, **in-situ** (hourly/daily) |
+| **legacy** (2020) | `# number_of_header_lines: N` | the `# data_fields:` header line | flask **monthly** |
+
+Supported products are those catalogued in [`docs/format-notes.md`](docs/format-notes.md)
+(CO₂/CH₄ surface-flask event + monthly, CO₂ in-situ hourly, at MLO). The header
+grammar is site- and gas-agnostic, so other stations/species in the same product
+families parse the same way.
+
+## Errors
+
+An unparseable file **raises** `UnrecognizedFormatError` (carrying the path and
+the file's first line) rather than returning data:
+
+```python
+from noaa_gml_file_reader import read_data, UnrecognizedFormatError
+
+try:
+    df = read_data("not-a-noaa-file.txt")
+except UnrecognizedFormatError as err:
+    print(err)
+```
+
+## v2 breaking changes
+
+v2 is a breaking release (hence the major bump):
+
+- **Renamed** `noaa_esrl_gmd_file_reader` → `noaa_gml_file_reader`
+  (distribution `noaa-gml-file-reader`).
+- **Raises `UnrecognizedFormatError`** on unrecognized/malformed input. v1
+  returned an *empty DataFrame* on any parse failure — silently indistinguishable
+  from "the file had no data" — which meant v1 failed silently on every current
+  (post-2020) NOAA file. If you relied on the empty-DataFrame behavior, catch the
+  exception instead.
+- **Relicensed** AGPL-3.0 → MIT.
+
+## Data & citation
+
+The data are NOAA GML's, not this package's. Please cite the measurements per
+NOAA GML's guidance — each product directory under
+[gml.noaa.gov/aftp/data/trace_gases](https://gml.noaa.gov/aftp/data/trace_gases/)
+ships a species-specific README with the citation text and data providers (the
+file headers also carry contact and reciprocity information). This library only
+parses the files; it does not download them.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

noaa_gml_file_reader-2.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+noaa_gml_file_reader/__init__.py,sha256=JaXTu57HuAH80ma20HRYK7gYgzWQDWzfj4-6GErhS80,618
+noaa_gml_file_reader/_reader.py,sha256=fvbkVwAx5jGqml7mKe-8HXwK9M4EKWcfOHXpvYZkCVE,5219
+noaa_gml_file_reader-2.0.0.dist-info/METADATA,sha256=BgLyDnLS02N5MT6w0NVf0ofyG5gliSAvHVdeXGvlQI4,5462
+noaa_gml_file_reader-2.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+noaa_gml_file_reader-2.0.0.dist-info/licenses/LICENSE,sha256=5iG7G7gI7_T3kgp5Bwu5KKZCSAdDsChlL6e0v9xwMT8,1083
+noaa_gml_file_reader-2.0.0.dist-info/RECORD,,

noaa_gml_file_reader-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

noaa_gml_file_reader-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Erick Edward Shepherd
+
+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.