tlpr2s 0.2.0__tar.gz

tlpr2s-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: tlpr2s
+Version: 0.2.0
+Summary: 2D-array SSMIS F16 transfer-learning precipitation retrieval and swath statistics
+Author: TLP-R2S research team
+Keywords: precipitation,SSMIS,satellite,XGBoost,remote sensing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.10
+Requires-Dist: xgboost>=2.0
+Provides-Extra: hub
+Requires-Dist: huggingface_hub<2,>=0.24; extra == "hub"
+Provides-Extra: all
+Requires-Dist: huggingface_hub<2,>=0.24; extra == "all"
+Requires-Dist: matplotlib>=3.7; extra == "all"
+Requires-Dist: cartopy>=0.22; extra == "all"
+Requires-Dist: xarray>=2023.1; extra == "all"
+Requires-Dist: netCDF4>=1.6; extra == "all"
+Requires-Dist: h5py>=3.8; extra == "all"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Requires-Dist: cartopy>=0.22; extra == "plot"
+Provides-Extra: io
+Requires-Dist: xarray>=2023.1; extra == "io"
+Requires-Dist: netCDF4>=1.6; extra == "io"
+Requires-Dist: h5py>=3.8; extra == "io"
+Provides-Extra: dev
+Requires-Dist: huggingface_hub<2,>=0.24; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Requires-Dist: xarray>=2023.1; extra == "dev"
+Requires-Dist: netCDF4>=1.6; extra == "dev"
+Requires-Dist: h5py>=3.8; extra == "dev"
+
+# tlpr2s — SSMIS F16 transfer-learning rain and snow retrieval
+
+**Python 3.10+ · 2D S4 swath inputs · original XGBoost models and CDF calibration · Hugging Face hosting · orbit visualization · annual grid · full legacy DAAC-oriented NetCDF**
+
+The scientific model artifacts are hosted separately at [BuddhaSubedi/TLP-R2S](https://huggingface.co/BuddhaSubedi/TLP-R2S) (approximately 6.43 GB). **They are not included in the Python wheel.** The first model initialization downloads and caches the five original files; subsequent runs reuse the cache. No model download occurs when simply importing `tlpr2s`. The model repo must be public, or the user must authenticate with Hugging Face.
+
+> **Scientific status:** This repository is an editable integration release. Real-orbit parity against the original pipeline and NASA DAAC acceptance have not been independently verified. The package is not NASA-endorsed. Do not publish it as validated before testing the actual trained artifacts.
+
+## Installation
+
+```bash
+python -m pip install -e '.[all,dev]'
+python -m pytest -q
+```
+
+For a public release after publishing on PyPI, users would run `pip install 'tlpr2s[all]'`. The package name's availability and release are not guaranteed.
+
+## Download models (once)
+
+```bash
+tlpr2s download-models
+# Better reproducibility: pin an immutable model repository commit SHA
+# tlpr2s download-models --revision FULL_COMMIT_SHA
+```
+
+The downloader retrieves ONLY these files:
+
+```
+xgb_tl_classifier_final.json
+xgb_tl_rain_rate_final.json
+xgb_tl_snow_rate_final_1.json
+cdf_match_for_rain_ssmis.npz
+cdf_match_for_snow_ssmis.npz
+```
+
+**Alternative offline/HPC approach:** download on a login node, or copy the five original files to `/scratch/models/tlpr2s/`, then set `TLPR2S_MODEL_DIR=/scratch/models/tlpr2s` or pass `model_dir=...`. To use a cached model offline, call `PrecipitationRetriever(local_files_only=True)`. To prohibit downloads altogether, call `PrecipitationRetriever(download=False, model_dir=...)`. To select a particular model revision, pass `revision='FULL_COMMIT_SHA'` or set `TLPR2S_MODEL_REVISION`.
+
+## Python API — S4-aligned 2D arrays, not full orbit files
+
+```python
+from tlpr2s import FEATURES, predict, plot_orbit, plot_annual, save_nc
+
+# inputs: dict with 30 predictor keys; each is 2D (npix,nscan),
+# except Month and Day may be scalar. The 11 lower-frequency SSMIS
+# TB channels and 17 ERA5 fields MUST already be mapped to the S4 grid.
+# See docs/INPUT_FORMAT.md for the exact feature names.
+result = predict(inputs, revision='FULL_COMMIT_SHA')
+
+# Result arrays have same (npix,nscan) shape.
+phase = result.phase                 # 0=clear, 1=rain, 2=snow
+rain = result.rain                   # mm/hr
+snow = result.snow                   # mm/hr
+precip = result.surface_precip
+
+# Latitude and longitude must be 2D arrays on the same S4 grid.
+plot_orbit(latitude, longitude, precip, vmax=15, save='orbit.png')
+```
+
+You may also use `PrecipitationRetriever(revision='FULL_COMMIT_SHA')` once and call `.predict(inputs)` on many orbits to avoid reloading multi-GB models for each orbit. The `predict` convenience function initializes the model each call, which is inefficient for batch processing.
+
+### Annual grid and visualization
+
+```python
+from tlpr2s import AnnualAccumulator, plot_annual
+acc = AnnualAccumulator(resolution=0.25)
+for latitude, longitude, result in retrieved_orbits:
+    acc.add(latitude, longitude, result.rain, result.snow)
+annual = acc.result()
+annual.save('annual_stats.npz')
+plot_annual(annual, field='mean_precip', save='annual_mean.png')
+```
+
+Grid is **721 x 1440**: latitudes −90 to +90 inclusive, longitudes −180 to +179.75, with +180 and −180 assigned to the same column. These are swath-sample means and counts, **not unbiased annual accumulation**. See `docs/SCIENTIFIC_LIMITATIONS.md`.
+
+### Save the full legacy DAAC-oriented NetCDF
+
+```python
+from tlpr2s import save_nc
+save_nc('TLP-R2S_orbit.nc', result=result,
+        latitude=latitude, longitude=longitude,
+        input_arrays=original_s4_fields,
+        ssmis_full_filename=original_ssmis_path.name,
+        ssmis_source_path=original_ssmis_path,
+        model_version='TLP-R2S_V01')
+```
+
+The writer preserves the original product layout, SSMIS TB and ERA5 fields, and actual source scan-time metadata. **A complete source SSMIS granule is required** to recover authentic times; a filename alone is insufficient. The NetCDF schema is DAAC-oriented, not formally certified. See `docs/DAAC_NETCDF.md`.
+
+## Command-line tools
+
+```bash
+tlpr2s download-models
+tlpr2s retrieve prepared_s4_arrays.npz --output orbit.npz
+tlpr2s plot-orbit orbit.npz --output orbit.png
+tlpr2s annual orbit1.npz orbit2.npz --output annual.npz
+tlpr2s plot-annual annual.npz --output annual.png
+```
+
+## Publish on GitHub / PyPI
+
+See `docs/PUBLISH_GITHUB_PYPI.md`, `docs/RELEASE_GUIDE.md`, `docs/INPUT_FORMAT.md`, and `examples/`. Keep model artifacts **outside** the GitHub repository and wheel. Review licenses, model provenance, original algorithm numerical parity, and the DAAC's product requirements before publication. The example `CITATION.cff` and `LICENSE-TO-SELECT.txt` need owner review.
+
+## GitHub upload checklist
+
+Start with [docs/GITHUB_UPLOAD_STEPS.md](docs/GITHUB_UPLOAD_STEPS.md) and [docs/MODEL_STORAGE_AND_PROVENANCE.md](docs/MODEL_STORAGE_AND_PROVENANCE.md). The model artifacts are hosted on Hugging Face and must **not** be committed to GitHub.

tlpr2s-0.2.0/README.md

@@ -0,0 +1,105 @@
+# tlpr2s — SSMIS F16 transfer-learning rain and snow retrieval
+
+**Python 3.10+ · 2D S4 swath inputs · original XGBoost models and CDF calibration · Hugging Face hosting · orbit visualization · annual grid · full legacy DAAC-oriented NetCDF**
+
+The scientific model artifacts are hosted separately at [BuddhaSubedi/TLP-R2S](https://huggingface.co/BuddhaSubedi/TLP-R2S) (approximately 6.43 GB). **They are not included in the Python wheel.** The first model initialization downloads and caches the five original files; subsequent runs reuse the cache. No model download occurs when simply importing `tlpr2s`. The model repo must be public, or the user must authenticate with Hugging Face.
+
+> **Scientific status:** This repository is an editable integration release. Real-orbit parity against the original pipeline and NASA DAAC acceptance have not been independently verified. The package is not NASA-endorsed. Do not publish it as validated before testing the actual trained artifacts.
+
+## Installation
+
+```bash
+python -m pip install -e '.[all,dev]'
+python -m pytest -q
+```
+
+For a public release after publishing on PyPI, users would run `pip install 'tlpr2s[all]'`. The package name's availability and release are not guaranteed.
+
+## Download models (once)
+
+```bash
+tlpr2s download-models
+# Better reproducibility: pin an immutable model repository commit SHA
+# tlpr2s download-models --revision FULL_COMMIT_SHA
+```
+
+The downloader retrieves ONLY these files:
+
+```
+xgb_tl_classifier_final.json
+xgb_tl_rain_rate_final.json
+xgb_tl_snow_rate_final_1.json
+cdf_match_for_rain_ssmis.npz
+cdf_match_for_snow_ssmis.npz
+```
+
+**Alternative offline/HPC approach:** download on a login node, or copy the five original files to `/scratch/models/tlpr2s/`, then set `TLPR2S_MODEL_DIR=/scratch/models/tlpr2s` or pass `model_dir=...`. To use a cached model offline, call `PrecipitationRetriever(local_files_only=True)`. To prohibit downloads altogether, call `PrecipitationRetriever(download=False, model_dir=...)`. To select a particular model revision, pass `revision='FULL_COMMIT_SHA'` or set `TLPR2S_MODEL_REVISION`.
+
+## Python API — S4-aligned 2D arrays, not full orbit files
+
+```python
+from tlpr2s import FEATURES, predict, plot_orbit, plot_annual, save_nc
+
+# inputs: dict with 30 predictor keys; each is 2D (npix,nscan),
+# except Month and Day may be scalar. The 11 lower-frequency SSMIS
+# TB channels and 17 ERA5 fields MUST already be mapped to the S4 grid.
+# See docs/INPUT_FORMAT.md for the exact feature names.
+result = predict(inputs, revision='FULL_COMMIT_SHA')
+
+# Result arrays have same (npix,nscan) shape.
+phase = result.phase                 # 0=clear, 1=rain, 2=snow
+rain = result.rain                   # mm/hr
+snow = result.snow                   # mm/hr
+precip = result.surface_precip
+
+# Latitude and longitude must be 2D arrays on the same S4 grid.
+plot_orbit(latitude, longitude, precip, vmax=15, save='orbit.png')
+```
+
+You may also use `PrecipitationRetriever(revision='FULL_COMMIT_SHA')` once and call `.predict(inputs)` on many orbits to avoid reloading multi-GB models for each orbit. The `predict` convenience function initializes the model each call, which is inefficient for batch processing.
+
+### Annual grid and visualization
+
+```python
+from tlpr2s import AnnualAccumulator, plot_annual
+acc = AnnualAccumulator(resolution=0.25)
+for latitude, longitude, result in retrieved_orbits:
+    acc.add(latitude, longitude, result.rain, result.snow)
+annual = acc.result()
+annual.save('annual_stats.npz')
+plot_annual(annual, field='mean_precip', save='annual_mean.png')
+```
+
+Grid is **721 x 1440**: latitudes −90 to +90 inclusive, longitudes −180 to +179.75, with +180 and −180 assigned to the same column. These are swath-sample means and counts, **not unbiased annual accumulation**. See `docs/SCIENTIFIC_LIMITATIONS.md`.
+
+### Save the full legacy DAAC-oriented NetCDF
+
+```python
+from tlpr2s import save_nc
+save_nc('TLP-R2S_orbit.nc', result=result,
+        latitude=latitude, longitude=longitude,
+        input_arrays=original_s4_fields,
+        ssmis_full_filename=original_ssmis_path.name,
+        ssmis_source_path=original_ssmis_path,
+        model_version='TLP-R2S_V01')
+```
+
+The writer preserves the original product layout, SSMIS TB and ERA5 fields, and actual source scan-time metadata. **A complete source SSMIS granule is required** to recover authentic times; a filename alone is insufficient. The NetCDF schema is DAAC-oriented, not formally certified. See `docs/DAAC_NETCDF.md`.
+
+## Command-line tools
+
+```bash
+tlpr2s download-models
+tlpr2s retrieve prepared_s4_arrays.npz --output orbit.npz
+tlpr2s plot-orbit orbit.npz --output orbit.png
+tlpr2s annual orbit1.npz orbit2.npz --output annual.npz
+tlpr2s plot-annual annual.npz --output annual.png
+```
+
+## Publish on GitHub / PyPI
+
+See `docs/PUBLISH_GITHUB_PYPI.md`, `docs/RELEASE_GUIDE.md`, `docs/INPUT_FORMAT.md`, and `examples/`. Keep model artifacts **outside** the GitHub repository and wheel. Review licenses, model provenance, original algorithm numerical parity, and the DAAC's product requirements before publication. The example `CITATION.cff` and `LICENSE-TO-SELECT.txt` need owner review.
+
+## GitHub upload checklist
+
+Start with [docs/GITHUB_UPLOAD_STEPS.md](docs/GITHUB_UPLOAD_STEPS.md) and [docs/MODEL_STORAGE_AND_PROVENANCE.md](docs/MODEL_STORAGE_AND_PROVENANCE.md). The model artifacts are hosted on Hugging Face and must **not** be committed to GitHub.

tlpr2s-0.2.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "tlpr2s"
+version = "0.2.0"
+description = "2D-array SSMIS F16 transfer-learning precipitation retrieval and swath statistics"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "TLP-R2S research team"}]
+keywords = ["precipitation", "SSMIS", "satellite", "XGBoost", "remote sensing"]
+dependencies = ["numpy>=1.24", "pandas>=1.5", "scipy>=1.10", "xgboost>=2.0"]
+[project.optional-dependencies]
+hub = ["huggingface_hub>=0.24,<2"]
+all = ["huggingface_hub>=0.24,<2", "matplotlib>=3.7", "cartopy>=0.22", "xarray>=2023.1", "netCDF4>=1.6", "h5py>=3.8"]
+plot = ["matplotlib>=3.7", "cartopy>=0.22"]
+io = ["xarray>=2023.1", "netCDF4>=1.6", "h5py>=3.8"]
+dev = ["huggingface_hub>=0.24,<2", "pytest>=7", "build", "twine", "matplotlib>=3.7", "xarray>=2023.1", "netCDF4>=1.6", "h5py>=3.8"]
+[project.scripts]
+tlpr2s = "tlpr2s.cli:main"
+[tool.setuptools.packages.find]
+where = ["src"]
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

tlpr2s-0.2.0/setup.cfg

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

tlpr2s-0.2.0/src/tlpr2s/__init__.py

@@ -0,0 +1,11 @@
+"""TLP-R2S: SSMIS F16 S4-swath precipitation retrieval."""
+from .model_download import download_models
+from .features import FEATURES
+from .arrays import feature_frame, save_swath, load_swath
+from .retrieval import PrecipitationRetriever, RetrievalResult
+from .annual import AnnualAccumulator, AnnualStatistics, aggregate_swaths
+from .plotting import plot_orbit, plot_annual
+from .daac import DAAC_compatible_nc
+from .public import predict, save_nc
+__version__ = "0.2.0"
+__all__ = ["download_models", "FEATURES", "feature_frame", "save_swath", "load_swath", "PrecipitationRetriever", "RetrievalResult", "predict", "plot_orbit", "plot_annual", "save_nc", "DAAC_compatible_nc", "AnnualAccumulator", "AnnualStatistics", "aggregate_swaths"]

tlpr2s-0.2.0/src/tlpr2s/annual.py

@@ -0,0 +1,77 @@
+"""Streaming swath-to-grid statistics. A sampling mean, not an annual accumulation."""
+from dataclasses import dataclass
+import numpy as np
+from .arrays import load_swath
+
+@dataclass
+class AnnualStatistics:
+    latitude: np.ndarray
+    longitude: np.ndarray
+    mean_rain: np.ndarray
+    mean_snow: np.ndarray
+    mean_precip: np.ndarray
+    observation_count: np.ndarray
+    swath_coverage_count: np.ndarray
+    @property
+    def shape(self):return self.mean_precip.shape
+    def save(self,path):
+        np.savez_compressed(path,**vars(self))
+    @classmethod
+    def load(cls,path):
+        with np.load(path,allow_pickle=False) as z:return cls(**{k:z[k] for k in cls.__dataclass_fields__})
+
+class AnnualAccumulator:
+    """Periodic longitude grid and inclusive polar latitude nodes.
+
+    Default grid: latitude [-90,90] inclusive (721 points), longitude
+    [-180,180) (1440 points). -180 and +180 map to the SAME column.
+    Observations are assigned to nearest grid node. Each pixel counts once;
+    annual means are sampling means, not time-weighted accumulations.
+    """
+    def __init__(self,resolution=0.25):
+        nlat=180/resolution;nlon=360/resolution
+        if int(nlat)!=nlat or int(nlon)!=nlon:
+            raise ValueError('resolution must divide 180 and 360')
+        self.resolution=float(resolution)
+        self.nlat=int(nlat)+1
+        self.nlon=int(nlon)
+        n=self.nlat*self.nlon
+        self.count=np.zeros(n,dtype=np.int64)
+        self.coverage=np.zeros(n,dtype=np.int64)
+        self.rain_sum=np.zeros(n,dtype=np.float64)
+        self.snow_sum=np.zeros(n,dtype=np.float64)
+    def add(self,latitude,longitude,rain,snow):
+        lat=np.asarray(latitude);lon=np.asarray(longitude)
+        r=np.asarray(rain);s=np.asarray(snow)
+        if lat.ndim!=2 or any(v.shape!=lat.shape for v in (lon,r,s)):
+            raise ValueError('All swath arrays must have identical 2D shape')
+        good=(np.isfinite(lat)&np.isfinite(lon)&np.isfinite(r)&np.isfinite(s)
+              &(lat>=-90)&(lat<=90)&(r>=0)&(s>=0))
+        if not good.any():return 0
+        # Round to nearest latitude node, including both poles.
+        la=np.clip(np.floor((lat[good]+90)/self.resolution+0.5).astype(np.int64),0,self.nlat-1)
+        # Periodic longitude: -180 and +180 map to column 0.
+        lo=(np.floor(((lon[good]+180)%360)/self.resolution+0.5).astype(np.int64))%self.nlon
+        idx=la*self.nlon+lo
+        self.count+=np.bincount(idx,minlength=self.count.size)
+        self.rain_sum+=np.bincount(idx,weights=r[good],minlength=self.count.size)
+        self.snow_sum+=np.bincount(idx,weights=s[good],minlength=self.count.size)
+        self.coverage[np.unique(idx)]+=1
+        return int(good.sum())
+    def add_file(self,path):
+        d=load_swath(path)
+        return self.add(d['latitude'],d['longitude'],d['rain'],d['snow'])
+    def result(self):
+        shape=(self.nlat,self.nlon)
+        def mean(total):
+            return np.divide(total,self.count,out=np.full_like(total,np.nan),where=self.count>0).reshape(shape)
+        lat=-90+np.arange(self.nlat)*self.resolution
+        lon=-180+np.arange(self.nlon)*self.resolution
+        return AnnualStatistics(lat,lon,mean(self.rain_sum),mean(self.snow_sum),mean(self.rain_sum+self.snow_sum),self.count.reshape(shape).copy(),self.coverage.reshape(shape).copy())
+
+def aggregate_swaths(paths,resolution=0.25):
+    acc=AnnualAccumulator(resolution)
+    paths=list(paths)
+    if not paths:raise ValueError('No swath files provided')
+    for p in paths:acc.add_file(p)
+    return acc.result()

tlpr2s-0.2.0/src/tlpr2s/arrays.py

@@ -0,0 +1,56 @@
+"""2D swath input validation. No files are required for inference."""
+import numpy as np
+import pandas as pd
+from .features import FEATURES
+
+def feature_frame(data, feature_names=None):
+    """Return (DataFrame, (height,width)) for dict of 2D features or (30,H,W) array.
+
+    All 30 features must be present in the exact training order. Month/Day may
+    be scalar, while other features must be 2D arrays of identical shape.
+    """
+    if isinstance(data, np.ndarray):
+        a=np.asarray(data)
+        if a.ndim != 3 or a.shape[0] != len(FEATURES):
+            raise ValueError(f'Stacked input must have shape ({len(FEATURES)}, H, W)')
+        if feature_names is not None and list(feature_names) != FEATURES:
+            raise ValueError('feature_names must match the trained 30-feature order')
+        data={name:a[i] for i,name in enumerate(FEATURES)}
+    if not isinstance(data,dict):
+        raise TypeError('Input must be dict[str, 2D array] or ndarray (30,H,W)')
+    missing=[k for k in FEATURES if k not in data]
+    if missing:raise ValueError(f'Missing model features: {missing}')
+    extras=set(data)-set(FEATURES)
+    if extras:raise ValueError(f'Unexpected model features: {sorted(extras)}')
+    shape=None
+    for k in FEATURES:
+        a=np.asarray(data[k])
+        if a.ndim==2:
+            if shape is None:shape=a.shape
+            elif shape!=a.shape:raise ValueError(f'{k} shape {a.shape} != {shape}')
+        elif not (k in ('Month','Day') and a.ndim==0):
+            raise ValueError(f'{k} must be a 2D array'+(' or scalar' if k in ('Month','Day') else ''))
+    if shape is None or min(shape)<1:raise ValueError('No nonempty 2D features')
+    columns={}
+    for k in FEATURES:
+        a=np.asarray(data[k],dtype=np.float32)
+        if a.ndim==0:a=np.full(shape,a.item(),dtype=np.float32)
+        if k in FEATURES[:11]:a=np.where(a<0,np.nan,a)
+        columns[k]=a.ravel(order='C')
+    return pd.DataFrame(columns)[FEATURES],shape
+
+def save_swath(path,latitude,longitude,phase,rain,snow):
+    """Save a complete retrieved swath as portable NPZ."""
+    lat=np.asarray(latitude);lon=np.asarray(longitude)
+    if lat.shape!=lon.shape or any(np.asarray(v).shape!=lat.shape for v in (phase,rain,snow)):
+        raise ValueError('Latitude, longitude, phase, rain and snow must have identical 2D shape')
+    np.savez_compressed(path,latitude=lat,longitude=lon,phase=phase,rain=rain,snow=snow)
+
+def load_swath(path):
+    with np.load(path,allow_pickle=False) as z:
+        required=('latitude','longitude','phase','rain','snow')
+        if any(k not in z for k in required):raise ValueError(f'NPZ must contain {required}')
+        d={k:z[k] for k in required}
+    if d['latitude'].ndim!=2 or any(v.shape!=d['latitude'].shape for v in d.values()):
+        raise ValueError('All swath variables must be matching 2D arrays')
+    return d

tlpr2s-0.2.0/src/tlpr2s/cli.py

@@ -0,0 +1,42 @@
+"""Command line tools for saved array inputs, swath plots and annual gridding."""
+import argparse
+from pathlib import Path
+import numpy as np
+from .arrays import save_swath,load_swath
+from .annual import aggregate_swaths,AnnualStatistics
+
+def main(argv=None):
+    p=argparse.ArgumentParser(prog='tlpr2s',description='SSMIS 2D precipitation retrieval and mapping')
+    sub=p.add_subparsers(dest='cmd',required=True)
+    r=sub.add_parser('retrieve',help='Retrieve from NPZ with 30 feature arrays and latitude/longitude')
+    r.add_argument('input');r.add_argument('--models',default=None);r.add_argument('--cdf',default=None);r.add_argument('--output',required=True);r.add_argument('--threads',type=int,default=1)
+    o=sub.add_parser('plot-orbit');o.add_argument('input');o.add_argument('--output',required=True);o.add_argument('--field',choices=['rain','snow','surface_precip','phase'],default='surface_precip');o.add_argument('--vmax',type=float,default=15)
+    a=sub.add_parser('annual');a.add_argument('files',nargs='+');a.add_argument('--output',required=True);a.add_argument('--resolution',type=float,default=.25)
+    q=sub.add_parser('plot-annual');q.add_argument('input');q.add_argument('--output',required=True);q.add_argument('--field',default='mean_precip')
+    d=sub.add_parser('download-models',help='Download the five official Hugging Face artifacts into the local cache')
+    d.add_argument('--revision',default=None,help='Pin a model repository commit SHA or tag')
+    d.add_argument('--cache-dir',default=None)
+    d.add_argument('--offline',action='store_true',help='Use cache only')
+    args=p.parse_args(argv)
+    if args.cmd=='download-models':
+        from .model_download import download_models
+        print(download_models(revision=args.revision,cache_dir=args.cache_dir,local_files_only=args.offline))
+    elif args.cmd=='retrieve':
+        from .retrieval import PrecipitationRetriever
+        with np.load(args.input,allow_pickle=False) as z:
+            if 'latitude' not in z or 'longitude' not in z:raise ValueError('Need latitude and longitude in NPZ')
+            lat=z['latitude'];lon=z['longitude'];data={k:z[k] for k in z.files if k not in ('latitude','longitude')}
+        result=PrecipitationRetriever(args.models,args.cdf,args.threads).predict(data)
+        save_swath(args.output,lat,lon,result.phase,result.rain,result.snow)
+    elif args.cmd=='plot-orbit':
+        from .plotting import plot_orbit
+        d=load_swath(args.input)
+        field=d['rain']+d['snow'] if args.field=='surface_precip' else d[args.field]
+        plot_orbit(d['latitude'],d['longitude'],field,title=args.field,save=args.output,vmax=args.vmax)
+    elif args.cmd=='annual':
+        stats=aggregate_swaths(args.files,args.resolution);stats.save(args.output)
+        print(f'Saved {args.output}; valid pixels: {int(stats.observation_count.sum())}')
+    elif args.cmd=='plot-annual':
+        from .plotting import plot_annual
+        plot_annual(AnnualStatistics.load(args.input),args.field,save=args.output)
+if __name__=='__main__':main()

tlpr2s-0.2.0/src/tlpr2s/daac.py

@@ -0,0 +1,92 @@
+"""Public interface for full legacy NASA DAAC-oriented SSMIS F16 NetCDF schema.
+
+This writer requires the actual source granule to preserve genuine S4 scan times.
+A full source filename is required and checked against the supplied file path.
+"""
+from pathlib import Path
+import numpy as np
+from .daac_products import netcdf, SSMIS_CHANNELS, ERA5_MAT_FIELDS, ERA5_REFERENCE_MAT_FIELDS
+from .ssmis_source import SOURCE_RE
+
+
+def _as_2d(value, name, shape=None):
+    arr = np.asarray(value)
+    if arr.ndim != 2:
+        raise ValueError(f'{name} must be 2D, got {arr.shape}')
+    if shape is not None and arr.shape != shape:
+        raise ValueError(f'{name} shape {arr.shape} != {shape}')
+    return arr
+
+
+def DAAC_compatible_nc(output_path, *, result, latitude, longitude,
+                       input_arrays, ssmis_full_filename, ssmis_source_path,
+                       source_identifier='2D-array retrieval', model_version='TLP-R2S_V01'):
+    """Save the complete original TLP-R2S DAAC-oriented NetCDF product.
+
+    Parameters
+    ----------
+    output_path : str or Path
+        Destination .nc file.
+    result : RetrievalResult
+        Inference output with phase, rain, snow arrays.
+    latitude, longitude : 2D array
+        SSMIS S4 coordinates, shaped (npix,nscan).
+    input_arrays : dict
+        2D arrays for ALL original SSMIS brightness-temperature and ERA5 fields.
+        Required SSMIS keys: TbS1, TbS2, TbS3, TbS4. Each is a
+        channel-stacked 3D array (npix,nscan,nchannels), OR provide individual
+        2D channel maps under keys such as '19.35V', '183.31±1H'.
+        ERA5 fields are named ERA5_tciw etc. Reference ERA5_msr and
+        ERA5_mtpr are optional, as in the original writer.
+    ssmis_full_filename : str
+        Complete original SSMIS F16 L1C granule filename; validated exactly.
+    ssmis_source_path : str or Path
+        Actual original SSMIS NetCDF file, used to read genuine S4 scan times.
+        Metadata cannot be fully populated from a filename alone.
+    source_identifier : str
+        Provenance identifier for input 2D arrays.
+    model_version : str
+        Retrieval model version.
+
+    Returns
+    -------
+    pathlib.Path
+        Written NetCDF path.
+    """
+    if not isinstance(input_arrays, dict):
+        raise TypeError('input_arrays must be a dictionary of mapped S4 fields')
+    name=Path(ssmis_full_filename).name
+    if name != str(ssmis_full_filename):
+        raise ValueError('ssmis_full_filename must be a filename, not a path')
+    if SOURCE_RE.fullmatch(name) is None:
+        raise ValueError(f'Full SSMIS F16 source filename does not match original pattern: {name}')
+    source=Path(ssmis_source_path)
+    if source.name != name:
+        raise ValueError(f'Source file basename {source.name!r} differs from full filename {name!r}')
+    if not source.is_file():
+        raise FileNotFoundError(f'SSMIS source file required for scan-time metadata: {source}')
+    lat=_as_2d(latitude,'latitude')
+    lon=_as_2d(longitude,'longitude',lat.shape)
+    phase=_as_2d(result.phase,'phase',lat.shape)
+    rain=_as_2d(result.rain,'rain',lat.shape)
+    snow=_as_2d(result.snow,'snow',lat.shape)
+    x=dict(input_arrays)
+    x['LatS4']=lat
+    x['LonS4']=lon
+    for swath,channels in SSMIS_CHANNELS.items():
+        key='Tb'+swath
+        if key in x:
+            continue
+        absent=[ch for ch,_ in channels if ch not in x]
+        if absent:
+            raise KeyError(f'Missing {key} or mapped 2D channel fields: {absent}')
+        x[key]=np.stack([_as_2d(x[ch],ch,lat.shape) for ch,_ in channels],axis=-1)
+    missing=[key for key in ERA5_MAT_FIELDS.values() if key not in x]
+    if missing:
+        raise KeyError(f'Full DAAC product requires original ERA5 input fields: {missing}')
+    for key in list(ERA5_MAT_FIELDS.values())+list(ERA5_REFERENCE_MAT_FIELDS.values()):
+        if key in x: _as_2d(x[key],key,lat.shape)
+    output=Path(output_path)
+    netcdf(output, x, phase, rain, snow, source_identifier,
+           source_ssmis=source, model_version=model_version)
+    return output