fm35-decoder 1.1__tar.gz → 2.0__tar.gz

{fm35_decoder-1.1 → fm35_decoder-2.0}/.gitignore

@@ -29,4 +29,7 @@ htmlcov/
 
 # OS files
 .DS_Store
-Thumbs.db
+Thumbs.db
+
+lib/
+.gitignore

fm35_decoder-2.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: fm35_decoder
+Version: 2.0
+Summary: Decoder for WMO FM 35 TEMP and FM 32 PILOT upper-air reports, based on the GEMPAK upper-air decoder.
+Project-URL: Homepage, https://github.com/luciodaou/fm35_decoder
+Project-URL: Bug Tracker, https://github.com/luciodaou/fm35_decoder/issues
+Author: Lucio Daou
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: pandas>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FM35 Decoder
+
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-F16061?style=flat&logo=ko-fi&logoColor=white)](https://ko-fi.com/luciodaou)
+[![PyPI - Version](https://img.shields.io/pypi/v/fm35_decoder.svg)](https://pypi.org/project/fm35_decoder)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fm35_decoder.svg)](https://pypi.org/project/fm35_decoder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Python decoder for **WMO FM 35 TEMP** and **FM 32 PILOT** upper-air reports (and their ship and
+dropsonde forms, FM 36 and FM 37), based on the upper-air decoder of
+[Unidata GEMPAK](https://github.com/Unidata/gempak) (`dcuair`, the `RU` bridge library).
+
+For a plain-English guide to the code form, see [TEMP_DECODING.md](TEMP_DECODING.md).
+Version 2.0 changes the decoding rules and part of the API: see [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## Installation
+
+```bash
+pip install fm35_decoder
+```
+
+---
+
+## Quickstart
+
+### The parts of one sounding, as DataFrames
+
+```python
+from fm35_decoder import decode
+
+ttaa = "TTAA 73121 83779 99938 21224 01008 00163 ///// ///// 92843 20019 07506 85570 18650 36008 ..."
+ttbb = "TTBB 73128 83779 00938 21224 11882 16804 22870 19856 33735 11056 44712 08616 55615 01218 ..."
+ttcc = "TTCC 73123 83779 70865 71568 15020 50064 67574 12519 30380 58383 08535 88906 77162 26018 ..."
+ttdd = "TTDD 7312/ 83779 11906 77162 22585 70370 33542 70970 44445 63978 55283 57785 21212 11935 ..."
+
+df_main, df_special = decode(ttaa, ttbb, ttcc, ttdd)
+```
+
+- `df_main` is the profile, surface first: `Pressure` (hPa), `Height` (m), `Temp`, `DewPoint` (°C),
+  `WindDir` (degrees), `WindSpeed` (knots), `Source` (`Surface`, `Standard`, `SigTemp`, `SigWind`,
+  `Tropopause`, `MaxWind`) and `Derived`, which names the columns of the row that were computed
+  rather than reported (`Height,Temp,DewPoint`).
+- `df_special` lists the tropopause, maximum wind, layers of missing data, sounding system and
+  cloud entries as text, with the part each came from.
+
+Options: `decode(..., wind_unit="m/s")` for speeds in m/s, and `decode(..., interpolate=False)` to
+leave temperature, dew point and wind empty where the report gives none. Any argument may hold a
+whole bulletin; every report found in it is used.
+
+### A stream of bulletins, as typed objects
+
+```python
+from datetime import datetime, timezone
+from fm35_decoder import decode_soundings, load_station_table
+
+stations = load_station_table("gempak/tables/stns/snstns.tbl")      # optional
+with open("uair.gts", encoding="latin-1") as stream:
+    soundings = decode_soundings(stream, reference_time=datetime(2026, 11, 13, tzinfo=timezone.utc),
+                                 station_table=stations)
+
+for sounding in soundings:
+    print(sounding.station_id, sounding.timestamp_utc, [part.value for part in sounding.parts])
+    for level in sounding.profile:
+        print(level.pressure_hpa, level.height_m, level.temp_c, level.wind_speed_ms, level.derived)
+```
+
+The steps are available one by one, as generators where the input allows it:
+
+| Function | GEMPAK routines | Result |
+| :--- | :--- | :--- |
+| `iter_bulletins(source)` | `DC_GBUL`, `DC_GHDR` | `Bulletin` (WMO heading and text) |
+| `iter_reports(text)` | `RU_GRPT` | the text of each report |
+| `parse_report(text, header, reference_time)` | `RU_SHDR`, `RU_DECD` and the part routines | `SoundingReport` |
+| `iter_decoded_reports(source, reference_time)` | the three above | `SoundingReport`, one at a time |
+| `merge_reports(reports, station_table)` | — | `MergedSounding` per station and time |
+
+A `SoundingReport` holds the part, the station, the day and hour, the wind unit, its levels
+(`SoundingLevel`, wind speeds always in m/s), the layers of missing data, the sounding system
+group and the regional sections as text. A report whose header cannot be decoded raises
+`DecodeError` in `parse_report` and is logged and skipped by the functions that read a stream.
+A `NIL` report comes back with `nil` set and no levels.
+
+The observation day and hour come from the report; the year and the month come from
+`reference_time` (when the report was received; now, if not given). Parts are merged when they
+share the station and the time rounded to 3 hours.
+
+---
+
+## Decoding rules
+
+The level data is decoded as GEMPAK does. The rules that matter most in practice:
+
+- **Order of the code form.** Standard levels are expected in order (1000, 925, … 100 hPa; 70, 50,
+  … 1 hPa in Part C). After a group that is not the expected level, the decoder looks for the next
+  level that is itself followed by the level after it, and gives up after ten groups. Significant
+  levels are expected in the sequence of `nn`; one out of sequence is taken only if its pressure is
+  lower than the last, and dropped again if the next level does not follow it.
+- **`Id`** gives the last standard level with a wind group (hundreds of hPa in Part A, tens in
+  Part C; `/` for none). In Part C, `1` and `0` give every level a wind group.
+- **Heights** are restored by a fixed rule per level (`RU_HGHT`): `00515` is −15 m, `85570` is
+  1570 m, `70980` is 2980 m, `30970` is 9700 m, `20241` is 12410 m, `50064` in Part C is 20640 m.
+  A standard level without a height is not kept.
+- **Temperature**: negative when the last figure is odd. **Depression**: tenths up to 50, whole
+  degrees plus 50 above (51–55, which WMO does not use, are read as 1–5 °C).
+- **Wind**: `ddfff` with 500 added to `fff` for a direction ending in 5. 360° is given as 0°. A
+  direction above 360° (`99`, variable) gives no wind. Speeds follow `YY` (knots when 50 is added).
+- **Tropopause and maximum wind** (`88`, `77`, `66`) are numeric levels; their pressure is in
+  tenths of hPa in Part C. `88999` and `77999` mean none. A maximum wind without a wind is dropped.
+- **Levels without data** (a significant level whose temperature or wind is `/////`) are not kept.
+
+Two rules differ from GEMPAK, both about where a marker is recognised:
+
+1. `21212` opens the wind section of Parts B and D only where a level group is expected. After
+   `nnPPP` it is a temperature of 21.2 °C with a depression of 1.2 °C.
+2. `51515` after `PPhhh` is a temperature of −51.5 °C with a depression of 1.5 °C. Where a level
+   or a wind is expected it ends the level data.
+
+Added to what GEMPAK decodes (from the WMO Manual on Codes): the `31313` section (radiation
+correction, sounding system, tracking, launch time), the `41414` cloud group of Part B, the
+`4vbvbvava` shear group of a maximum wind, and layers of missing data (`nn/// /////`), which are
+listed and never interpolated across.
+
+---
+
+## Merged profile
+
+GEMPAK stores the parts unmerged, so the merge is this library's own:
+
+- Levels are combined by pressure, to the tenth of hPa. Standard levels come first, then
+  significant temperature levels, significant winds, PILOT winds, tropopause and maximum wind; a
+  value already there is never replaced.
+- One report per part: the first received, unless a later one comes from a bulletin whose `BBB`
+  marks a correction, retransmission or amendment.
+- **Heights** of levels that report none are computed with the hypsometric equation and the
+  virtual temperature. Above the last temperature a height is computed only within the limits of
+  Regulation 35.2.2.4 (25 hPa, and a quarter of the pressure of the level). With a station table,
+  the surface takes the station elevation.
+- **Interpolation** (on request; on by default in `decode`) fills temperature and dew point
+  linearly in ln(p), and the wind by its components, only between observed levels and never inside
+  a layer reported as missing. The dew point never exceeds the temperature.
+- PILOT winds on heights get a pressure from the heights of the profile when they fall inside it.
+
+Every value computed here is named in `SoundingLevel.derived` (the `Derived` column).
+
+---
+
+## License
+
+This project is licensed under the terms of the **MIT License**.
+You are free to use, modify, and distribute this software with attribution to the original author.

fm35_decoder-2.0/README.md

@@ -0,0 +1,151 @@
+# FM35 Decoder
+
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-F16061?style=flat&logo=ko-fi&logoColor=white)](https://ko-fi.com/luciodaou)
+[![PyPI - Version](https://img.shields.io/pypi/v/fm35_decoder.svg)](https://pypi.org/project/fm35_decoder)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fm35_decoder.svg)](https://pypi.org/project/fm35_decoder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Python decoder for **WMO FM 35 TEMP** and **FM 32 PILOT** upper-air reports (and their ship and
+dropsonde forms, FM 36 and FM 37), based on the upper-air decoder of
+[Unidata GEMPAK](https://github.com/Unidata/gempak) (`dcuair`, the `RU` bridge library).
+
+For a plain-English guide to the code form, see [TEMP_DECODING.md](TEMP_DECODING.md).
+Version 2.0 changes the decoding rules and part of the API: see [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## Installation
+
+```bash
+pip install fm35_decoder
+```
+
+---
+
+## Quickstart
+
+### The parts of one sounding, as DataFrames
+
+```python
+from fm35_decoder import decode
+
+ttaa = "TTAA 73121 83779 99938 21224 01008 00163 ///// ///// 92843 20019 07506 85570 18650 36008 ..."
+ttbb = "TTBB 73128 83779 00938 21224 11882 16804 22870 19856 33735 11056 44712 08616 55615 01218 ..."
+ttcc = "TTCC 73123 83779 70865 71568 15020 50064 67574 12519 30380 58383 08535 88906 77162 26018 ..."
+ttdd = "TTDD 7312/ 83779 11906 77162 22585 70370 33542 70970 44445 63978 55283 57785 21212 11935 ..."
+
+df_main, df_special = decode(ttaa, ttbb, ttcc, ttdd)
+```
+
+- `df_main` is the profile, surface first: `Pressure` (hPa), `Height` (m), `Temp`, `DewPoint` (°C),
+  `WindDir` (degrees), `WindSpeed` (knots), `Source` (`Surface`, `Standard`, `SigTemp`, `SigWind`,
+  `Tropopause`, `MaxWind`) and `Derived`, which names the columns of the row that were computed
+  rather than reported (`Height,Temp,DewPoint`).
+- `df_special` lists the tropopause, maximum wind, layers of missing data, sounding system and
+  cloud entries as text, with the part each came from.
+
+Options: `decode(..., wind_unit="m/s")` for speeds in m/s, and `decode(..., interpolate=False)` to
+leave temperature, dew point and wind empty where the report gives none. Any argument may hold a
+whole bulletin; every report found in it is used.
+
+### A stream of bulletins, as typed objects
+
+```python
+from datetime import datetime, timezone
+from fm35_decoder import decode_soundings, load_station_table
+
+stations = load_station_table("gempak/tables/stns/snstns.tbl")      # optional
+with open("uair.gts", encoding="latin-1") as stream:
+    soundings = decode_soundings(stream, reference_time=datetime(2026, 11, 13, tzinfo=timezone.utc),
+                                 station_table=stations)
+
+for sounding in soundings:
+    print(sounding.station_id, sounding.timestamp_utc, [part.value for part in sounding.parts])
+    for level in sounding.profile:
+        print(level.pressure_hpa, level.height_m, level.temp_c, level.wind_speed_ms, level.derived)
+```
+
+The steps are available one by one, as generators where the input allows it:
+
+| Function | GEMPAK routines | Result |
+| :--- | :--- | :--- |
+| `iter_bulletins(source)` | `DC_GBUL`, `DC_GHDR` | `Bulletin` (WMO heading and text) |
+| `iter_reports(text)` | `RU_GRPT` | the text of each report |
+| `parse_report(text, header, reference_time)` | `RU_SHDR`, `RU_DECD` and the part routines | `SoundingReport` |
+| `iter_decoded_reports(source, reference_time)` | the three above | `SoundingReport`, one at a time |
+| `merge_reports(reports, station_table)` | — | `MergedSounding` per station and time |
+
+A `SoundingReport` holds the part, the station, the day and hour, the wind unit, its levels
+(`SoundingLevel`, wind speeds always in m/s), the layers of missing data, the sounding system
+group and the regional sections as text. A report whose header cannot be decoded raises
+`DecodeError` in `parse_report` and is logged and skipped by the functions that read a stream.
+A `NIL` report comes back with `nil` set and no levels.
+
+The observation day and hour come from the report; the year and the month come from
+`reference_time` (when the report was received; now, if not given). Parts are merged when they
+share the station and the time rounded to 3 hours.
+
+---
+
+## Decoding rules
+
+The level data is decoded as GEMPAK does. The rules that matter most in practice:
+
+- **Order of the code form.** Standard levels are expected in order (1000, 925, … 100 hPa; 70, 50,
+  … 1 hPa in Part C). After a group that is not the expected level, the decoder looks for the next
+  level that is itself followed by the level after it, and gives up after ten groups. Significant
+  levels are expected in the sequence of `nn`; one out of sequence is taken only if its pressure is
+  lower than the last, and dropped again if the next level does not follow it.
+- **`Id`** gives the last standard level with a wind group (hundreds of hPa in Part A, tens in
+  Part C; `/` for none). In Part C, `1` and `0` give every level a wind group.
+- **Heights** are restored by a fixed rule per level (`RU_HGHT`): `00515` is −15 m, `85570` is
+  1570 m, `70980` is 2980 m, `30970` is 9700 m, `20241` is 12410 m, `50064` in Part C is 20640 m.
+  A standard level without a height is not kept.
+- **Temperature**: negative when the last figure is odd. **Depression**: tenths up to 50, whole
+  degrees plus 50 above (51–55, which WMO does not use, are read as 1–5 °C).
+- **Wind**: `ddfff` with 500 added to `fff` for a direction ending in 5. 360° is given as 0°. A
+  direction above 360° (`99`, variable) gives no wind. Speeds follow `YY` (knots when 50 is added).
+- **Tropopause and maximum wind** (`88`, `77`, `66`) are numeric levels; their pressure is in
+  tenths of hPa in Part C. `88999` and `77999` mean none. A maximum wind without a wind is dropped.
+- **Levels without data** (a significant level whose temperature or wind is `/////`) are not kept.
+
+Two rules differ from GEMPAK, both about where a marker is recognised:
+
+1. `21212` opens the wind section of Parts B and D only where a level group is expected. After
+   `nnPPP` it is a temperature of 21.2 °C with a depression of 1.2 °C.
+2. `51515` after `PPhhh` is a temperature of −51.5 °C with a depression of 1.5 °C. Where a level
+   or a wind is expected it ends the level data.
+
+Added to what GEMPAK decodes (from the WMO Manual on Codes): the `31313` section (radiation
+correction, sounding system, tracking, launch time), the `41414` cloud group of Part B, the
+`4vbvbvava` shear group of a maximum wind, and layers of missing data (`nn/// /////`), which are
+listed and never interpolated across.
+
+---
+
+## Merged profile
+
+GEMPAK stores the parts unmerged, so the merge is this library's own:
+
+- Levels are combined by pressure, to the tenth of hPa. Standard levels come first, then
+  significant temperature levels, significant winds, PILOT winds, tropopause and maximum wind; a
+  value already there is never replaced.
+- One report per part: the first received, unless a later one comes from a bulletin whose `BBB`
+  marks a correction, retransmission or amendment.
+- **Heights** of levels that report none are computed with the hypsometric equation and the
+  virtual temperature. Above the last temperature a height is computed only within the limits of
+  Regulation 35.2.2.4 (25 hPa, and a quarter of the pressure of the level). With a station table,
+  the surface takes the station elevation.
+- **Interpolation** (on request; on by default in `decode`) fills temperature and dew point
+  linearly in ln(p), and the wind by its components, only between observed levels and never inside
+  a layer reported as missing. The dew point never exceeds the temperature.
+- PILOT winds on heights get a pressure from the heights of the profile when they fall inside it.
+
+Every value computed here is named in `SoundingLevel.derived` (the `Derived` column).
+
+---
+
+## License
+
+This project is licensed under the terms of the **MIT License**.
+You are free to use, modify, and distribute this software with attribution to the original author.

{fm35_decoder-1.1 → fm35_decoder-2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "fm35_decoder"
-version = "1.1"
-description = "A Python tool to decode standard FM35 TEMP weather messages from upper-air observations."
+version = "2.0"
+description = "Decoder for WMO FM 35 TEMP and FM 32 PILOT upper-air reports, based on the GEMPAK upper-air decoder."
 readme = "README.md"
 requires-python = ">=3.12"
 classifiers = [
@@ -14,7 +14,6 @@ authors = [
 ]
 dependencies = [
     "pandas>=3.0.0",
-    "numpy>=2.0.0",
 ]
 
 [project.optional-dependencies]

fm35_decoder-2.0/src/fm35_decoder/__init__.py

@@ -0,0 +1,53 @@
+"""
+Decoder of WMO FM 35 TEMP and FM 32 PILOT upper-air reports (and their ship and dropsonde
+forms), based on the GEMPAK upper-air decoder.
+"""
+
+from .bulletin import Bulletin, iter_bulletins, iter_reports
+from .decoder import decode, decode_full, decode_soundings, iter_decoded_reports, to_dataframes
+from .merge import merge_parts, merge_reports
+from .models import (
+    DecodeError,
+    LevelType,
+    MergedSounding,
+    MissingLayer,
+    Platform,
+    ReportPart,
+    SoundingLevel,
+    SoundingReport,
+    SoundingSystem,
+    StationMetadata,
+    WindUnit,
+    WmoHeader,
+)
+from .parts import parse_report
+from .stations import load_station_table
+
+__version__ = "2.0"
+
+__all__ = [
+    "Bulletin",
+    "DecodeError",
+    "LevelType",
+    "MergedSounding",
+    "MissingLayer",
+    "Platform",
+    "ReportPart",
+    "SoundingLevel",
+    "SoundingReport",
+    "SoundingSystem",
+    "StationMetadata",
+    "WindUnit",
+    "WmoHeader",
+    "decode",
+    "decode_full",
+    "decode_soundings",
+    "iter_bulletins",
+    "iter_decoded_reports",
+    "iter_reports",
+    "load_station_table",
+    "merge_parts",
+    "merge_reports",
+    "parse_report",
+    "to_dataframes",
+]

fm35_decoder-2.0/src/fm35_decoder/bulletin.py

@@ -0,0 +1,224 @@
+"""
+Bulletins, reports and report headers, ported from GEMPAK: DC_GBUL and DC_GHDR (bridge/dc),
+RU_GRPT, RU_SHDR, RU_RTIM and RU_ADJT (bridge/ru).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Iterable, Iterator, List, Optional, Tuple, Union
+
+from .groups import Fields, clean_text, decode_position, to_int
+from .models import DecodeError, Platform, ReportPart, SoundingReport, WindUnit, WmoHeader
+
+SOH, ETX = "\x01", "\x03"
+
+# TTAAii CCCC YYGGgg (BBB); DC_GHDR also takes MMDDHHMM, DDHHMMZ and "UTC" before BBB
+_HEADING = re.compile(r"^([A-Z]{4}\d{0,2}) ([A-Z]{4}) (\d{6}Z?|\d{8})(?: UTC)?(?: ([A-Z]{3}))?$")
+_PART_NAME = re.compile(r"^(TT|PP|UU|XX)(AA|BB|CC|DD)")
+_SEQUENCE = re.compile(r"^\d{3,5}$")
+
+
+@dataclass(frozen=True)
+class Bulletin:
+    header: Optional[WmoHeader]
+    text: str
+
+
+def _parse_heading(line: str, sequence: str) -> Optional[WmoHeader]:
+    """DC_GHDR: the heading line, with a valid day (01-31) and time (0000-2359)."""
+    m = _HEADING.match(line)
+    if m is None or _PART_NAME.match(line):
+        return None
+    time = m.group(3)
+    time = time[2:] if len(time) == 8 else time[:6]
+    if not (1 <= int(time[:2]) <= 31 and int(time[2:]) <= 2359):
+        return None
+    return WmoHeader(m.group(1), m.group(2), time, m.group(4) or "", sequence)
+
+
+def iter_bulletins(source: Union[str, Iterable[str]]) -> Iterator[Bulletin]:
+    """
+    The bulletins of a text, a file object or any iterable of lines, one at a time. A bulletin
+    starts at SOH or at a WMO abbreviated heading and ends at ETX, at the next start or at the
+    end of the input. Text without any of those is one bulletin without a header.
+    """
+    lines = source.splitlines() if isinstance(source, str) else source
+    header: Optional[WmoHeader] = None
+    sequence = ""
+    body: List[str] = []
+
+    def flush() -> Iterator[Bulletin]:
+        nonlocal header, sequence, body
+        text = clean_text(" ".join(body))
+        if text:
+            yield Bulletin(header, text)
+        header, sequence, body = None, "", []
+
+    for raw in lines:
+        for piece in re.split(f"({SOH}|{ETX})", raw):
+            if piece in (SOH, ETX):
+                yield from flush()
+                continue
+            line = clean_text(piece)
+            if not line:
+                continue
+            if header is None and not body and _SEQUENCE.match(line):
+                sequence = line
+                continue
+            heading = _parse_heading(line, sequence)
+            if heading is not None:
+                kept = sequence
+                yield from flush()
+                header = WmoHeader(heading.ttaaii, heading.cccc, heading.yygggg, heading.bbb, kept)
+                continue
+            body.append(line)
+    yield from flush()
+
+
+_REPORT_START = re.compile(r"TT|PP|UU|XX")
+_REPORT_END = re.compile(r"TT|PP|UU|XX|=")
+# A dropsonde report may hold text, so only another dropsonde report or "=" ends it
+_REPORT_END_XX = re.compile(r"XXAA|XXBB|XXCC|XXDD|=")
+
+
+def iter_reports(text: str) -> Iterator[str]:
+    """
+    RU_GRPT: the reports of a bulletin. A report starts at TT, PP, UU or XX followed by AA, BB,
+    CC or DD and runs up to "=", the start of another report or the end of the bulletin.
+    """
+    text = clean_text(text)
+    pos, end = 0, len(text)
+    while pos < end:
+        search = pos
+        while True:
+            m = _REPORT_START.search(text, search)
+            if m is None:
+                return
+            start = m.start()
+            if text[start + 2 : start + 4] in ("AA", "BB", "CC", "DD"):
+                break
+            search = start + 1
+        pattern = _REPORT_END_XX if m.group() == "XX" else _REPORT_END
+        stop = pattern.search(text, start + 2)
+        if stop is None:
+            yield text[start:]
+            return
+        yield text[start : stop.start()]
+        pos = stop.start() + (1 if stop.group() == "=" else 0)
+
+
+def parse_header(text: str, fields: Fields) -> SoundingReport:
+    """
+    RU_SHDR: MiMiMjMj (call sign) YYGGId IIiii, or the position groups of a ship or dropsonde.
+    `fields` is left on the first group after the header. XX and UU parts are decoded as TT.
+    Raises DecodeError when the header is not one.
+    """
+    name = text[fields.pos : fields.pos + 4]
+    fields.pos += 4
+    p1, p2 = name[:2], name[2:]
+    if p1 in ("TT", "PP") and p2 in ("AA", "BB", "CC", "DD"):
+        platform = Platform.LAND
+    elif p1 == "XX" and p2 in ("AA", "BB"):
+        platform = Platform.DROPSONDE
+    elif p1 == "UU" and p2 in ("AA", "BB", "CC", "DD"):
+        platform = Platform.SHIP
+    else:
+        raise DecodeError(f"not an upper-air part: {name!r}")
+    part = ReportPart(name if platform is Platform.LAND else "TT" + p2)
+
+    call_sign = ""
+    if platform is Platform.SHIP:
+        call_sign = fields.next() or ""
+        if not call_sign or len(call_sign) > 8:
+            raise DecodeError(f"invalid call sign in {text[:24]!r}")
+
+    fld = fields.next()
+    if fld is None or len(fld) < 5:
+        raise DecodeError(f"no YYGGId group in {text[:24]!r}")
+    day, hour = to_int(fld[0:2]), to_int(fld[2:4])
+    if day is None or hour is None:
+        raise DecodeError(f"invalid YYGGId group {fld!r}")
+    unit = WindUnit.METERS_PER_SECOND
+    if day > 50:
+        day -= 50
+        unit = WindUnit.KNOTS
+    report = SoundingReport(
+        part=part,
+        station_id="",
+        obs_day=day,
+        obs_hour=hour,
+        wind_unit=unit,
+        platform=platform,
+        top_wind_indicator=to_int(fld[4:5]),
+        text=text,
+    )
+
+    if platform is Platform.LAND:
+        fld = fields.next()
+        number = to_int(fld[0:5]) if fld is not None and len(fld) >= 5 else None
+        if number is None:
+            raise DecodeError(f"invalid station number in {text[:24]!r}")
+        report.station_id = f"{number:05d}"
+    else:
+        position = decode_position(fields)
+        if position is None:
+            raise DecodeError(f"invalid position groups in {text[:40]!r}")
+        report.latitude, report.longitude = position
+        if platform is Platform.DROPSONDE:
+            # The identifier comes from the 61616 section; until then it is the hour
+            report.station_id = str(hour)
+        elif call_sign == "SHIP":
+            lat, lon = position
+            report.station_id = f"S{int(abs(lat * 10)) * 10000 + int(abs(lon * 10)):07d}"
+        else:
+            report.station_id = f"{call_sign[:6]}{hour:02d}"
+
+    rest = text[fields.pos :].lstrip()
+    report.nil = rest[:3] == "NIL" and rest[3:].strip(" =") == ""
+    return report
+
+
+def observation_time(reference: datetime, day: int, hour: int) -> Optional[datetime]:
+    """
+    RU_RTIM: the observation time from the day and hour of the report, taking the year and the
+    month from `reference` (the time the report was received). A day after the 27th received
+    on the 1st belongs to the month before; hour 24 is 00 of the next day. None when the hour
+    or the date is not valid.
+    """
+    add_day = hour == 24
+    if add_day:
+        hour = 0
+    elif not 0 <= hour < 24:
+        return None
+    year, month = reference.year, reference.month
+    if day > 27 and reference.day == 1:
+        month -= 1
+        if month == 0:
+            year, month = year - 1, 12
+    try:
+        obs = datetime(year, month, day, hour, tzinfo=timezone.utc)
+    except ValueError:
+        return None
+    return obs + timedelta(days=1) if add_day else obs
+
+
+def nominal_time(obs: datetime) -> datetime:
+    """RU_ADJT: the time rounded to the nearest 3 hours."""
+    diff = obs.hour % 3
+    if diff == 1:
+        return obs - timedelta(hours=1)
+    if diff == 2:
+        return obs + timedelta(hours=1)
+    return obs
+
+
+def station_key(report: SoundingReport) -> Tuple[str, Optional[datetime], int, int]:
+    """What the parts of one sounding share: station and nominal time (day and hour without one)."""
+    if report.nominal_time is not None:
+        return report.station_id, report.nominal_time, 0, 0
+    hour = report.obs_hour
+    hour += {0: 0, 1: -1, 2: 1}[hour % 3]
+    return report.station_id, None, report.obs_day, hour