fm35-decoder 1.0__tar.gz → 1.2__tar.gz

{fm35_decoder-1.0 → fm35_decoder-1.2}/.gitignore

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

{fm35_decoder-1.0 → fm35_decoder-1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fm35_decoder
-Version: 1.0
+Version: 1.2
 Summary: A Python tool to decode standard FM35 TEMP weather messages from upper-air observations.
 Project-URL: Homepage, https://github.com/luciodaou/fm35_decoder
 Project-URL: Bug Tracker, https://github.com/luciodaou/fm35_decoder/issues
@@ -55,11 +55,14 @@ ttdd = "TTDD 7312/ 83779 11906 77162 22585 70370 33542 70970 44445 63978 55283 5
 df_main, df_special = decode(ttaa, ttbb, ttcc, ttdd)
 
 # df_main: Clean vertical sounding profile (Pressure, Height, Temp, DewPoint, WindDir, WindSpeed)
-# df_special: Metadata, Tropopause, Maximum Wind, and Cloud groups
+# df_special: Metadata, Tropopause, Maximum Wind, and Cloud groups, with the part each came from
 print(df_main)
 print(df_special)
 ```
 
+Any argument may also hold a whole bulletin with several parts: `decode(bulletin)` splits it and
+decodes each part once (`split_bulletin` and `route_parts` do the splitting on their own).
+
 ---
 
 ## Handling Non-Standard and Extreme Meteorological Data
@@ -72,6 +75,24 @@ Real-world atmospheric soundings and teletype GTS transmissions frequently conta
   In WMO FM 35, when the units digit of wind direction is $5^\circ$ (e.g., $275^\circ$), $500$ is added to the reported wind speed ($fff$) across both standard levels and maximum wind groups ($77P_mP_mP_m$). The decoder accurately separates the $5^\circ$ direction component from the true wind speed, avoiding the common $500\text{ kt}$ speed inflation bug.
 - **Calm Wind ($0^\circ, 0\text{ kt}$)**:
   Calm wind is represented as `WindDir = 0.0, WindSpeed = 0.0`. True non-calm winds blowing from North are assigned `360.0°`.
+- **Wind Groups Follow $I_d$**:
+  The header's $I_d$ (Code Table 1734) names the last standard level that carries a wind group ($2$ covers $250$ and $200\text{ hPa}$, $1$ covers $150$ and $100\text{ hPa}$; tens of hPa in Part C). Levels above it are read as `PPhhh TTTDD` only, so the next group is never taken for their wind; with $I_d$ = `/` only the surface has a wind group.
+- **Temperatures That Look Like Indicators**:
+  $-66.x$ and $-77.x\,^\circ\text{C}$ (common at $150$ and $100\text{ hPa}$ in the tropics) are coded `66xxx` and `77xxx`, like the maximum wind indicators, and `21212` ($21.2\,^\circ\text{C}$) or `31313` ($-31.3\,^\circ\text{C}$) look like section markers. The group after `PPhhh` is read as the temperature by its position; only groups that cannot be a temperature and depression (`88999`, `77999`, `66999`, `41414`, `52525`, `54545`, `55555`, `56565`, `58585`) end a level early.
+- **Maximum Wind Shear**:
+  The cloud section (`41414`) belongs to Part B, so in Parts A and C a `41414` after a maximum wind is the shear group ($14\text{ kt}$ below and above).
+- **Wind Speed Units**:
+  `YY` is the day plus $50$ when speeds are in knots and the day itself when they are in m/s. m/s speeds are converted to knots in `df_main`; `df_special` keeps the reported value and unit (`240/23m/s`).
+- **Regional and National Sections**:
+  `51515`–`59595` and `61616`–`69696` come last in a part; the groups after them are never read as levels (`55555` stays a significant level in Parts B and D, `66666` a maximum wind at $666\text{ hPa}$).
+- **Part B Without Part A**:
+  A `TTBB` decodes on its own: the profile has no heights, which only Parts A and C report. A message with fewer than two temperatures (only the surface) raises `ValueError`.
+- **Part C Special Levels in Tenths of hPa**:
+  In `TTCC`, `88PtPtPt` and `77PmPmPm` give the pressure in tenths of a hectopascal (`88906` is $90.6\text{ hPa}$).
+- **Pressures Keep Their Tenths**:
+  Part D levels are reported in tenths of a hectopascal, and `df_main` keeps them (`70.7` and `70.0 hPa` stay two levels). Round for display in your own code.
+- **Repeated Sections**:
+  The `31313` and cloud sections repeat in every part and are listed once. Tropopause and maximum wind entries are all kept: a sounding may report two tropopauses (one in Part A, one in Part C). The `Part` column of `df_special` tells them apart.
 - **GTS Transmission Sequence Breaks**:
   If network or teletype line noise drops an intermediate significant level in `TTBB` or `TTDD` (e.g., group sequence jumps directly from `22` to `44`), the decoder recovers automatically rather than terminating or discarding the remainder of the sounding.
 - **Negative Geopotential Heights ($1000\text{ hPa}$ below sea level)**:
@@ -86,14 +107,16 @@ Real-world atmospheric soundings and teletype GTS transmissions frequently conta
 ## Meteorological Methodology
 
 ### Vertical Interpolation
-- **Temperature & Dewpoint**: Missing intermediate levels are filled via linear interpolation with respect to the **natural logarithm of pressure** ($\ln P$). This aligns with atmospheric thermodynamics on Skew-T / Log-P diagrams where temperature varies approximately linearly with $\ln P$.
-- **Wind Vectors**: Wind speed and direction are decomposed into orthogonal **$U$ (zonal)** and **$V$ (meridional)** vector components. Each component is interpolated independently in $\ln P$ space before being recombined, preventing boundary artifacts across the $0^\circ/360^\circ$ North transition.
+- **Temperature & Dewpoint**: Missing intermediate levels are filled via linear interpolation with respect to the **natural logarithm of pressure** ($\ln P$), only between two observed levels: nothing is extrapolated above the last observation or below the first (a top level reported as `/////` stays empty). This aligns with atmospheric thermodynamics on Skew-T / Log-P diagrams where temperature varies approximately linearly with $\ln P$.
+- **Wind Vectors**: Wind speed and direction are decomposed into orthogonal **$U$ (zonal)** and **$V$ (meridional)** vector components. Each component is interpolated independently in $\ln P$ space (again only between observed winds) before being recombined, preventing boundary artifacts across the $0^\circ/360^\circ$ North transition. A variable wind keeps its speed and no direction.
 
 ### Hypsometric Geopotential Calculation
 Missing geopotential heights are computed using the Hypsometric Equation:
 $$Z_2 - Z_1 = \frac{R_d \cdot \bar{T}_v}{g_0} \ln\left(\frac{P_1}{P_2}\right)$$
 The decoder incorporates **virtual temperature ($T_v$)** when moisture data is available, accounting for air density variations in warm and humid tropical boundary layers.
 
+A level without a temperature takes one for this calculation only: interpolated in $\ln P$ between observed temperatures, and the top temperature above the last one. 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 level's pressure); further up a level keeps no height unless the report gives it. Under the same rule, a standard level just above the top of the sounding that the report does not hold is added with its geopotential only (`Source` = `Extrapolated`).
+
 ---
 
 ## Performance & Architecture
@@ -108,38 +131,38 @@ The decoder incorporates **virtual temperature ($T_v$)** when moisture data is a
 ### `df_main` (Vertical Profile)
 ```
   Pressure  Height  Temp  DewPoint  WindDir  WindSpeed
-      1000     163  20.4      18.0     10.0        8.0
-       938     714  21.2      18.8     10.0        8.0
-       925     843  20.0      18.1     75.0        6.0
-       882    1249  16.8      16.4     23.0        8.5
-       870    1366  19.8      13.8     15.0       10.0
-       850    1570  18.6      13.6    360.0        8.0
+    1000.0     163  20.4      18.0     10.0        8.0
+     938.0     714  21.2      18.8     10.0        8.0
+     925.0     843  20.0      18.1     75.0        6.0
+     882.0    1249  16.8      16.4     23.0        8.5
+     870.0    1366  19.8      13.8     15.0       10.0
+     850.0    1570  18.6      13.6    360.0        8.0
        ...     ...   ...       ...      ...        ...
-        30   23800 -58.3     -91.3     85.0       35.0
-        20   26480 -55.2     -89.0     90.0       38.0
-        10   31020 -44.1       NaN     95.0       42.0
+      30.0   23800 -58.3     -91.3     85.0       35.0
+      20.0   26480 -55.2     -89.0     90.0       38.0
+      10.0   31020 -44.1       NaN     95.0       42.0
 ```
 
 ### `df_special` (Metadata & Special Levels)
 ```
-    Symbol     Subject    Description                                    Value
-         h       Cloud    Base Height                  600-1000m (2000-3300ft)
-        Nh       Cloud         Amount                                  8 oktas
-        CL       Cloud       Low Type  Stratus nebulosus and/or Stratus fractus
-        CM       Cloud       Mid Type                             No CM clouds
-        CH       Cloud      High Type                             No CH clouds
-        sr  Solar/Inst     Solar Corr                     NOAA solar corrected
-      rara  Solar/Inst     Sonde Type     Vaisala RS41/DigiCORA MW41 (Finland)
-      sasa  Solar/Inst       Tracking                               Radar (5 cm)
-     8GGgg  Solar/Inst           Time                                    11:31
-    PtPtPt  Tropopause       Pressure                                   906hPa
-    TtTtTt  Tropopause    Temperature                                   -77.1C
-      DtDt  Tropopause       Dewpoint                                   -89.1C
-  dtdtftft  Tropopause           Wind                                 260/18kt
-    PmPmPm    Max Wind       Pressure                                   200hPa
-dmdmfmfmfm    Max Wind           Wind                                275/120kt
-      vbvb    Max Wind    Shear Below                                     14kt
-      vava    Max Wind    Shear Above                                     14kt
+    Symbol     Subject    Description                                    Value  Part
+         h       Cloud    Base Height                  600-1000m (2000-3300ft)  TTBB
+        Nh       Cloud         Amount                                  8 oktas  TTBB
+        CL       Cloud       Low Type  Stratus nebulosus and/or Stratus fractus  TTBB
+        CM       Cloud       Mid Type                             No CM clouds  TTBB
+        CH       Cloud      High Type                             No CH clouds  TTBB
+        sr  Solar/Inst     Solar Corr  Solar and infrared corrected automatically by radiosonde system  TTAA
+      rara  Solar/Inst     Sonde Type     Vaisala RS41/DigiCORA MW41 (Finland)  TTAA
+      sasa  Solar/Inst       Tracking            Automatic satellite navigation  TTAA
+     8GGgg  Solar/Inst           Time                                    11:31  TTAA
+    PtPtPt  Tropopause       Pressure                                  90.6hPa  TTCC
+    TtTtTt  Tropopause    Temperature                                   -77.1C  TTCC
+      DtDt  Tropopause       Dewpoint                                   -89.1C  TTCC
+  dtdtftft  Tropopause           Wind                                 260/18kt  TTCC
+    PmPmPm    Max Wind       Pressure                                   200hPa  TTAA
+dmdmfmfmfm    Max Wind           Wind                                275/120kt  TTAA
+      vbvb    Max Wind    Shear Below                                     14kt  TTAA
+      vava    Max Wind    Shear Above                                     14kt  TTAA
 ```
 
 ---

{fm35_decoder-1.0 → fm35_decoder-1.2}/README.md

@@ -37,11 +37,14 @@ ttdd = "TTDD 7312/ 83779 11906 77162 22585 70370 33542 70970 44445 63978 55283 5
 df_main, df_special = decode(ttaa, ttbb, ttcc, ttdd)
 
 # df_main: Clean vertical sounding profile (Pressure, Height, Temp, DewPoint, WindDir, WindSpeed)
-# df_special: Metadata, Tropopause, Maximum Wind, and Cloud groups
+# df_special: Metadata, Tropopause, Maximum Wind, and Cloud groups, with the part each came from
 print(df_main)
 print(df_special)
 ```
 
+Any argument may also hold a whole bulletin with several parts: `decode(bulletin)` splits it and
+decodes each part once (`split_bulletin` and `route_parts` do the splitting on their own).
+
 ---
 
 ## Handling Non-Standard and Extreme Meteorological Data
@@ -54,6 +57,24 @@ Real-world atmospheric soundings and teletype GTS transmissions frequently conta
   In WMO FM 35, when the units digit of wind direction is $5^\circ$ (e.g., $275^\circ$), $500$ is added to the reported wind speed ($fff$) across both standard levels and maximum wind groups ($77P_mP_mP_m$). The decoder accurately separates the $5^\circ$ direction component from the true wind speed, avoiding the common $500\text{ kt}$ speed inflation bug.
 - **Calm Wind ($0^\circ, 0\text{ kt}$)**:
   Calm wind is represented as `WindDir = 0.0, WindSpeed = 0.0`. True non-calm winds blowing from North are assigned `360.0°`.
+- **Wind Groups Follow $I_d$**:
+  The header's $I_d$ (Code Table 1734) names the last standard level that carries a wind group ($2$ covers $250$ and $200\text{ hPa}$, $1$ covers $150$ and $100\text{ hPa}$; tens of hPa in Part C). Levels above it are read as `PPhhh TTTDD` only, so the next group is never taken for their wind; with $I_d$ = `/` only the surface has a wind group.
+- **Temperatures That Look Like Indicators**:
+  $-66.x$ and $-77.x\,^\circ\text{C}$ (common at $150$ and $100\text{ hPa}$ in the tropics) are coded `66xxx` and `77xxx`, like the maximum wind indicators, and `21212` ($21.2\,^\circ\text{C}$) or `31313` ($-31.3\,^\circ\text{C}$) look like section markers. The group after `PPhhh` is read as the temperature by its position; only groups that cannot be a temperature and depression (`88999`, `77999`, `66999`, `41414`, `52525`, `54545`, `55555`, `56565`, `58585`) end a level early.
+- **Maximum Wind Shear**:
+  The cloud section (`41414`) belongs to Part B, so in Parts A and C a `41414` after a maximum wind is the shear group ($14\text{ kt}$ below and above).
+- **Wind Speed Units**:
+  `YY` is the day plus $50$ when speeds are in knots and the day itself when they are in m/s. m/s speeds are converted to knots in `df_main`; `df_special` keeps the reported value and unit (`240/23m/s`).
+- **Regional and National Sections**:
+  `51515`–`59595` and `61616`–`69696` come last in a part; the groups after them are never read as levels (`55555` stays a significant level in Parts B and D, `66666` a maximum wind at $666\text{ hPa}$).
+- **Part B Without Part A**:
+  A `TTBB` decodes on its own: the profile has no heights, which only Parts A and C report. A message with fewer than two temperatures (only the surface) raises `ValueError`.
+- **Part C Special Levels in Tenths of hPa**:
+  In `TTCC`, `88PtPtPt` and `77PmPmPm` give the pressure in tenths of a hectopascal (`88906` is $90.6\text{ hPa}$).
+- **Pressures Keep Their Tenths**:
+  Part D levels are reported in tenths of a hectopascal, and `df_main` keeps them (`70.7` and `70.0 hPa` stay two levels). Round for display in your own code.
+- **Repeated Sections**:
+  The `31313` and cloud sections repeat in every part and are listed once. Tropopause and maximum wind entries are all kept: a sounding may report two tropopauses (one in Part A, one in Part C). The `Part` column of `df_special` tells them apart.
 - **GTS Transmission Sequence Breaks**:
   If network or teletype line noise drops an intermediate significant level in `TTBB` or `TTDD` (e.g., group sequence jumps directly from `22` to `44`), the decoder recovers automatically rather than terminating or discarding the remainder of the sounding.
 - **Negative Geopotential Heights ($1000\text{ hPa}$ below sea level)**:
@@ -68,14 +89,16 @@ Real-world atmospheric soundings and teletype GTS transmissions frequently conta
 ## Meteorological Methodology
 
 ### Vertical Interpolation
-- **Temperature & Dewpoint**: Missing intermediate levels are filled via linear interpolation with respect to the **natural logarithm of pressure** ($\ln P$). This aligns with atmospheric thermodynamics on Skew-T / Log-P diagrams where temperature varies approximately linearly with $\ln P$.
-- **Wind Vectors**: Wind speed and direction are decomposed into orthogonal **$U$ (zonal)** and **$V$ (meridional)** vector components. Each component is interpolated independently in $\ln P$ space before being recombined, preventing boundary artifacts across the $0^\circ/360^\circ$ North transition.
+- **Temperature & Dewpoint**: Missing intermediate levels are filled via linear interpolation with respect to the **natural logarithm of pressure** ($\ln P$), only between two observed levels: nothing is extrapolated above the last observation or below the first (a top level reported as `/////` stays empty). This aligns with atmospheric thermodynamics on Skew-T / Log-P diagrams where temperature varies approximately linearly with $\ln P$.
+- **Wind Vectors**: Wind speed and direction are decomposed into orthogonal **$U$ (zonal)** and **$V$ (meridional)** vector components. Each component is interpolated independently in $\ln P$ space (again only between observed winds) before being recombined, preventing boundary artifacts across the $0^\circ/360^\circ$ North transition. A variable wind keeps its speed and no direction.
 
 ### Hypsometric Geopotential Calculation
 Missing geopotential heights are computed using the Hypsometric Equation:
 $$Z_2 - Z_1 = \frac{R_d \cdot \bar{T}_v}{g_0} \ln\left(\frac{P_1}{P_2}\right)$$
 The decoder incorporates **virtual temperature ($T_v$)** when moisture data is available, accounting for air density variations in warm and humid tropical boundary layers.
 
+A level without a temperature takes one for this calculation only: interpolated in $\ln P$ between observed temperatures, and the top temperature above the last one. 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 level's pressure); further up a level keeps no height unless the report gives it. Under the same rule, a standard level just above the top of the sounding that the report does not hold is added with its geopotential only (`Source` = `Extrapolated`).
+
 ---
 
 ## Performance & Architecture
@@ -90,38 +113,38 @@ The decoder incorporates **virtual temperature ($T_v$)** when moisture data is a
 ### `df_main` (Vertical Profile)
 ```
   Pressure  Height  Temp  DewPoint  WindDir  WindSpeed
-      1000     163  20.4      18.0     10.0        8.0
-       938     714  21.2      18.8     10.0        8.0
-       925     843  20.0      18.1     75.0        6.0
-       882    1249  16.8      16.4     23.0        8.5
-       870    1366  19.8      13.8     15.0       10.0
-       850    1570  18.6      13.6    360.0        8.0
+    1000.0     163  20.4      18.0     10.0        8.0
+     938.0     714  21.2      18.8     10.0        8.0
+     925.0     843  20.0      18.1     75.0        6.0
+     882.0    1249  16.8      16.4     23.0        8.5
+     870.0    1366  19.8      13.8     15.0       10.0
+     850.0    1570  18.6      13.6    360.0        8.0
        ...     ...   ...       ...      ...        ...
-        30   23800 -58.3     -91.3     85.0       35.0
-        20   26480 -55.2     -89.0     90.0       38.0
-        10   31020 -44.1       NaN     95.0       42.0
+      30.0   23800 -58.3     -91.3     85.0       35.0
+      20.0   26480 -55.2     -89.0     90.0       38.0
+      10.0   31020 -44.1       NaN     95.0       42.0
 ```
 
 ### `df_special` (Metadata & Special Levels)
 ```
-    Symbol     Subject    Description                                    Value
-         h       Cloud    Base Height                  600-1000m (2000-3300ft)
-        Nh       Cloud         Amount                                  8 oktas
-        CL       Cloud       Low Type  Stratus nebulosus and/or Stratus fractus
-        CM       Cloud       Mid Type                             No CM clouds
-        CH       Cloud      High Type                             No CH clouds
-        sr  Solar/Inst     Solar Corr                     NOAA solar corrected
-      rara  Solar/Inst     Sonde Type     Vaisala RS41/DigiCORA MW41 (Finland)
-      sasa  Solar/Inst       Tracking                               Radar (5 cm)
-     8GGgg  Solar/Inst           Time                                    11:31
-    PtPtPt  Tropopause       Pressure                                   906hPa
-    TtTtTt  Tropopause    Temperature                                   -77.1C
-      DtDt  Tropopause       Dewpoint                                   -89.1C
-  dtdtftft  Tropopause           Wind                                 260/18kt
-    PmPmPm    Max Wind       Pressure                                   200hPa
-dmdmfmfmfm    Max Wind           Wind                                275/120kt
-      vbvb    Max Wind    Shear Below                                     14kt
-      vava    Max Wind    Shear Above                                     14kt
+    Symbol     Subject    Description                                    Value  Part
+         h       Cloud    Base Height                  600-1000m (2000-3300ft)  TTBB
+        Nh       Cloud         Amount                                  8 oktas  TTBB
+        CL       Cloud       Low Type  Stratus nebulosus and/or Stratus fractus  TTBB
+        CM       Cloud       Mid Type                             No CM clouds  TTBB
+        CH       Cloud      High Type                             No CH clouds  TTBB
+        sr  Solar/Inst     Solar Corr  Solar and infrared corrected automatically by radiosonde system  TTAA
+      rara  Solar/Inst     Sonde Type     Vaisala RS41/DigiCORA MW41 (Finland)  TTAA
+      sasa  Solar/Inst       Tracking            Automatic satellite navigation  TTAA
+     8GGgg  Solar/Inst           Time                                    11:31  TTAA
+    PtPtPt  Tropopause       Pressure                                  90.6hPa  TTCC
+    TtTtTt  Tropopause    Temperature                                   -77.1C  TTCC
+      DtDt  Tropopause       Dewpoint                                   -89.1C  TTCC
+  dtdtftft  Tropopause           Wind                                 260/18kt  TTCC
+    PmPmPm    Max Wind       Pressure                                   200hPa  TTAA
+dmdmfmfmfm    Max Wind           Wind                                275/120kt  TTAA
+      vbvb    Max Wind    Shear Below                                     14kt  TTAA
+      vava    Max Wind    Shear Above                                     14kt  TTAA
 ```
 
 ---

{fm35_decoder-1.0 → fm35_decoder-1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fm35_decoder"
-version = "1.0"
+version = "1.2"
 description = "A Python tool to decode standard FM35 TEMP weather messages from upper-air observations."
 readme = "README.md"
 requires-python = ">=3.12"

fm35_decoder-1.2/src/fm35_decoder/__init__.py

@@ -0,0 +1,3 @@
+from .decoder import decode, decode_full, route_parts, split_bulletin
+
+__all__ = ["decode", "decode_full", "route_parts", "split_bulletin"]