pvtend 0.7.1__tar.gz

pvtend-0.7.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xingjian Yan
+
+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.

pvtend-0.7.1/PKG-INFO

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: pvtend
+Version: 0.7.1
+Summary: PV tendency decomposition diagnostics for blocking and weather extremes
+Author: Xingjian Yan
+License: MIT License
+        
+        Copyright (c) 2026 Xingjian Yan
+        
+        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.
+        
+Project-URL: Documentation, https://pvtend.readthedocs.io/
+Project-URL: Repository, https://github.com/yanxingjianken/pvtend
+Project-URL: Bug Tracker, https://github.com/yanxingjianken/pvtend/issues
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy
+Requires-Dist: xarray
+Requires-Dist: pandas
+Requires-Dist: netCDF4
+Requires-Dist: tqdm
+Requires-Dist: matplotlib
+Requires-Dist: scikit-image
+Requires-Dist: cdsapi
+Provides-Extra: maps
+Requires-Dist: cartopy; extra == "maps"
+Provides-Extra: sip
+Requires-Dist: numba; extra == "sip"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: dask; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: ipykernel; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pvtend[docs,sip,test]; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# pvtend
+
+[![Tests](https://github.com/yanxingjianken/pvtend/actions/workflows/test.yml/badge.svg)](https://github.com/yanxingjianken/pvtend/actions)
+[![Documentation](https://readthedocs.org/projects/pvtend/badge/?version=latest)](https://pvtend.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**PV tendency decomposition for atmospheric blocking, propagating anticyclones, and all synoptic-scale cyclonic event lifecycle analysis.**
+
+`pvtend` diagnoses the growth, propagation, and decay of mid-latitude weather events by decomposing potential vorticity (PV) tendencies from ERA5 pressure-level data onto physically meaningful components using an orthogonal basis framework. This is the Part I work of Yan et al. (in prep.) about blocking lifecycle analyses on onset, peak, decay stages.
+
+## Gallery
+
+<table>
+<tr>
+<td width="50%" align="center">
+<img src="docs/_static/reconstruction_demo.png" alt="Idealized four-basis reconstruction" width="100%"/><br/>
+<em>Idealized validation — a Gaussian PV anomaly with prescribed propagation,
+intensification, and deformation is decomposed into four orthogonal bases
+and reconstructed with near-zero residual.</em>
+</td>
+<td width="50%" align="center">
+<img src="docs/_static/lifecycle_demo.gif" alt="Real blocking lifecycle decomposition" width="100%"/><br/>
+<em>Real ERA5 blocking event (track 425) — animated lifecycle showing
+total PV on a cartopy map (left) and the four projected basis components
+(right) evolving from 13 h pre-onset to 12 h post-onset.
+The analysis is done on a weighted average surface across 300, 250, 200 hPa levels.</em>
+</td>
+</tr>
+<tr>
+<td colspan="2" align="center">
+<img src="docs/_static/z_lifecycle_demo.gif" alt="Geopotential-height lifecycle decomposition" width="100%"/><br/>
+<em>Geopotential-height (Z500) variant of the four-basis decomposition
+(track 425) — animated lifecycle showing Z anomaly from the 1990–2020
+hourly climatology, with adaptive prenorm and blockid contour overlay.
+See notebook <code>03z_four_basis_projection_geopotential</code>.</em>
+</td>
+</tr>
+</table>
+
+### Event catalogues
+
+Blocking and PRP-high events are identified as persistent anticyclonic anomalies in 500 hPa geopotential height.
+We are using [**TempestExtremes** v2.1](https://gmd.copernicus.org/articles/14/5023/2021/) to track contiguous Z500 anomaly features that exceed a fixed threshold for ≥5 days, producing CSV catalogues with columns for event ID, centre lat/lon, onset/peak/decay timestamps, and area. Following the threshold as in [Drouard et al. (2021)](https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2020JD034082), we separate the tracked features into blocking and propagating (prp) high pressure systems.
+
+> **Sample catalogue (ERA5, 1990–2020 blocking):** [`ERA5_TempestExtremes_z500_anticyclone_blocking.csv`](https://github.com/yanxingjianken/pvtend/raw/main/docs/_static/ERA5_TempestExtremes_z500_anticyclone_blocking.csv)
+
+The CSVs are the inputs for `pvtend-pipeline compute`, which extracts event-centred patches and runs the full PV-tendency decomposition for each event in the blocking/prp catalogue.
+
+## Features
+
+- **PV tendency computation**: RHS has zonal advection, baroclinic counter propagation, vertical advection, and approximated diabatic heating terms.
+- **QG omega solver**: Hoskins Q-vector formulation with **two methods**: FFT+Thomas (default, fast) and 3-D direct/iterative (BiCGSTAB+ILU, full horizontal Laplacian). Optional `center_lat` for dynamic f₀ (Li & O'Gorman 2020).
+- **Helmholtz decomposition**: 4 backends (direct, FFT, DCT, SOR) for limited-area domains
+- **Moist/dry omega splitting**: Decomposes vertical motion into moist and dry contributions
+- **Orthogonal basis decomposition**: Projects PV tendency onto intensification (β), propagation (αx, αy), and deformation (γ) modes
+- **RWB detection**: Two classification methods — **bay** (path-order, recommended with circumpolar-cropped contours) and **tilt** (centerline slope ±0.15 dead zone). Circumpolar-first contour extraction for robust NH analysis.
+- **Composite lifecycle**: Multi-stage ensemble averaging with onset/peak/decay staging
+- **CLI pipeline**: End-to-end processing via `pvtend-pipeline` command
+
+## Installation
+
+```bash
+# From source
+git clone https://github.com/yanxingjianken/pvtend.git
+cd pvtend
+pip install -e ".[dev]"
+
+# With micromamba
+micromamba create -f environment.yml
+micromamba activate pvtend_env
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from pvtend import NHGrid, ddx, ddy, compute_orthogonal_basis, project_field
+
+# Grid setup
+grid = NHGrid(lat=np.linspace(90, 0, 61), lon=np.linspace(-180, 178.5, 240))
+dx_arr = grid.dx_arr  # zonal spacing per latitude [m]
+dy = grid.dy           # meridional spacing [m]
+
+# Compute zonal derivative
+dfdx = ddx(field, dx_arr, periodic=False)
+
+# Orthogonal basis decomposition
+basis = compute_orthogonal_basis(pv_anom, pv_dx, pv_dy, x_rel, y_rel)
+result = project_field(tendency, basis)
+print(f"β = {result['beta']:.3e}")  # intensification rate
+```
+
+### CLI Pipeline
+
+```bash
+# Step 1: Compute PV tendencies → per-event NPZ files
+pvtend-pipeline compute \
+    --event-type blocking \
+    --events-csv events.csv \
+    --era5-dir /data/era5/ \
+    --clim-path /data/climatology/era5_hourly_clim.nc \
+    --out-dir /data/composite_blocking_tempest/ \
+    --dh-range=-49:25 --skip-existing
+
+# Step 2: RWB classification → variant tracksets PKL
+pvtend-pipeline classify \
+    --npz-dir /data/composite_blocking_tempest/ \
+    --output /data/outputs/rwb_variant_tracksets.pkl \
+    --stages onset peak decay \
+    --levels 500 400 300 200 --threshold 3
+
+# Step 3: Variant-aware composite accumulation → composite PKL
+pvtend-pipeline composite \
+    --npz-dir /data/composite_blocking_tempest/ \
+    --rwb-pkl /data/outputs/rwb_variant_tracksets.pkl \
+    --pkl-out /data/outputs/composite.pkl
+
+# Step 4 (optional): Orthogonal-basis decomposition
+pvtend-pipeline decompose \
+    --pkl-in /data/outputs/composite.pkl \
+    --out-dir /data/outputs/decomp/
+```
+
+## Workflow
+
+```mermaid
+graph TD
+    A[ERA5 Monthly NetCDF] --> B[pvtend.preprocessing]
+    B --> C[Regridded NH Grid]
+    C --> D[pvtend.climatology]
+    D --> E[Monthly Climatology]
+    C & E --> F[pvtend.tendency.TendencyComputer]
+    F --> G[PV Tendency Terms]
+    G --> H[pvtend.omega — QG ω solver]
+    G --> I[pvtend.helmholtz — Helmholtz decomp.]
+    H & I --> J[pvtend.moist_dry — ω splitting]
+    G & J --> K[Per-event NPZ patches]
+    K --> L1[pvtend.classify — RWB Pass 1]
+    L1 --> L1a[rwb_variant_tracksets.pkl]
+    K & L1a --> L2[pvtend.composite_builder — Pass 2]
+    L2 --> L2a[composite.pkl]
+    L2a --> M[pvtend.decomposition — Orthogonal basis]
+    M --> N[β, αx, αy, γ coefficients]
+    N --> O[pvtend.plotting — Publication figures]
+```
+
+## Package Structure
+
+```
+src/pvtend/
+├── __init__.py          # Public API
+├── _version.py          # Version
+├── cli.py               # CLI entry point (compute, classify, composite, decompose)
+├── constants.py         # Physical constants
+├── grid.py              # NH grid & event patches
+├── preprocessing.py     # ERA5 loading & regridding
+├── derivatives.py       # Finite difference operators
+├── climatology.py       # Fourier-filtered climatology
+├── omega.py             # QG omega solver (FFT+Thomas or 3-D direct)
+├── helmholtz.py         # Helmholtz decomposition (direct/FFT/DCT/SOR)
+├── moist_dry.py         # Moist/dry omega split
+├── isentropic.py        # Isentropic PV-tendency diagnostics
+├── tendency.py          # Main pipeline: data loading, derivatives, cross-terms, NPZ output
+├── classify.py          # RWB classification Pass 1 (AWB/CWB/NEUTRAL → variant PKL)
+├── composite_builder.py # Variant-aware composite accumulation Pass 2
+├── rwb.py               # RWB detection (bay & tilt methods, circumpolar-first)
+├── composites.py        # Legacy composite lifecycle
+├── data/                # Bundled sample data
+│   ├── __init__.py      # load_idealized_pv() loader
+│   └── idealized_pv.npz # Synthetic Gaussian PV evolution
+├── decomposition/       # Orthogonal basis framework
+│   ├── __init__.py
+│   ├── smoothing.py
+│   ├── basis.py
+│   └── projection.py
+├── plotting/            # Visualization
+│   ├── __init__.py
+│   ├── basis_plots.py
+│   ├── coefficient_plots.py
+│   ├── field_plots.py
+│   ├── composite_explorer.py  # plot_var: single-variable composite explorer with bootstrap
+│   └── baroclinic.py          # plot_baroclinic_tilt: two-level v′ overlay
+└── io/                  # File I/O
+    ├── __init__.py
+    ├── era5.py
+    ├── npz.py
+    └── pkl.py
+```
+
+## Example Notebooks
+
+Notebooks using **real ERA5 blocking event data** from the `composite_blocking_tempest`, `composite_prp_tempest` (single event npz), `tempest_extreme_4_basis/outputs`, and `tempest_extreme_4_basis/outputs_prp` (composite pkl) pipeline:
+
+| Notebook | Description |
+|----------|-------------|
+| [`00_idealized_pvtend_decomp`](examples/00_idealized_pvtend_decomp.ipynb) | Idealized Gaussian PV anomaly: prescribed β/αx/αy/γ at two timesteps, basis visualisation, Gram-Schmidt, projection & reconstruction |
+| [`01_rwb_and_derivatives`](examples/01_rwb_and_derivatives.ipynb) | Grid setup, `ddx`/`ddy`/`ddp` derivatives, RWB detection on a real event |
+| [`02_helmholtz_and_qg_omega`](examples/02_helmholtz_and_qg_omega.ipynb) | 3-D Helmholtz decomposition, QG omega (FFT vs 3-D direct), moist/dry ω split |
+| [`03_four_basis_projection`](examples/03_four_basis_projection.ipynb) | Orthogonal basis (Φ₁–Φ₄), project dq'/dt → β/αx/αy/γ, lifecycle curves |
+| [`03z_four_basis_projection_geopotential`](examples/03z_four_basis_projection_geopotential.ipynb) | ↳ *Supplement*: same 4-basis projection using **geopotential height Z** instead of PV |
+| [`04_single_var_composite`](examples/04_single_var_composite.ipynb) | Single-variable composite explorer on pressure levels using `pvtend.plotting.plot_var` |
+| [`04i_single_var_isentropic_composite`](examples/04i_single_var_isentropic_composite.ipynb) | ↳ *Supplement*: same as 04 but on **isentropic (θ) surfaces** |
+| [`05_stacked_bar_beta`](examples/05_stacked_bar_beta.ipynb) | Stacked-bar β decomposition by PV-tendency term across lifecycle hours |
+| [`05b_grouped_terms_bootstrap`](examples/05b_grouped_terms_bootstrap.ipynb) | ↳ *Supplement*: grouped PV-tendency terms with **bootstrap resampling & significance** |
+| [`06_baroclinic_structure`](examples/06_baroclinic_structure.ipynb) | 3-D composite PV anomaly, lon–p cross-sections, 2-PVU tropopause, v′ tilt via `plot_baroclinic_tilt` |
+| [`07_facet_blocking_vs_prp`](examples/07_facet_blocking_vs_prp.ipynb) | Facet comparison of blocking vs PRP: bar charts with bootstrap significance, shared-cbar spatial maps, baroclinic tilt |
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## Documentation
+
+Full documentation at [pvtend.readthedocs.io](https://pvtend.readthedocs.io).
+
+Build locally:
+
+```bash
+cd docs && make html
+```
+
+## Citation
+
+If you use this package in your research, please cite:
+
+```bibtex
+@software{yan2025pvtend,
+  author = {Yan, Xingjian},
+  title = {pvtend: PV tendency decomposition for atmospheric blocking},
+  year = {2025},
+  url = {https://github.com/yanxingjianken/pvtend}
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pvtend-0.7.1/README.md

@@ -0,0 +1,240 @@
+# pvtend
+
+[![Tests](https://github.com/yanxingjianken/pvtend/actions/workflows/test.yml/badge.svg)](https://github.com/yanxingjianken/pvtend/actions)
+[![Documentation](https://readthedocs.org/projects/pvtend/badge/?version=latest)](https://pvtend.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**PV tendency decomposition for atmospheric blocking, propagating anticyclones, and all synoptic-scale cyclonic event lifecycle analysis.**
+
+`pvtend` diagnoses the growth, propagation, and decay of mid-latitude weather events by decomposing potential vorticity (PV) tendencies from ERA5 pressure-level data onto physically meaningful components using an orthogonal basis framework. This is the Part I work of Yan et al. (in prep.) about blocking lifecycle analyses on onset, peak, decay stages.
+
+## Gallery
+
+<table>
+<tr>
+<td width="50%" align="center">
+<img src="docs/_static/reconstruction_demo.png" alt="Idealized four-basis reconstruction" width="100%"/><br/>
+<em>Idealized validation — a Gaussian PV anomaly with prescribed propagation,
+intensification, and deformation is decomposed into four orthogonal bases
+and reconstructed with near-zero residual.</em>
+</td>
+<td width="50%" align="center">
+<img src="docs/_static/lifecycle_demo.gif" alt="Real blocking lifecycle decomposition" width="100%"/><br/>
+<em>Real ERA5 blocking event (track 425) — animated lifecycle showing
+total PV on a cartopy map (left) and the four projected basis components
+(right) evolving from 13 h pre-onset to 12 h post-onset.
+The analysis is done on a weighted average surface across 300, 250, 200 hPa levels.</em>
+</td>
+</tr>
+<tr>
+<td colspan="2" align="center">
+<img src="docs/_static/z_lifecycle_demo.gif" alt="Geopotential-height lifecycle decomposition" width="100%"/><br/>
+<em>Geopotential-height (Z500) variant of the four-basis decomposition
+(track 425) — animated lifecycle showing Z anomaly from the 1990–2020
+hourly climatology, with adaptive prenorm and blockid contour overlay.
+See notebook <code>03z_four_basis_projection_geopotential</code>.</em>
+</td>
+</tr>
+</table>
+
+### Event catalogues
+
+Blocking and PRP-high events are identified as persistent anticyclonic anomalies in 500 hPa geopotential height.
+We are using [**TempestExtremes** v2.1](https://gmd.copernicus.org/articles/14/5023/2021/) to track contiguous Z500 anomaly features that exceed a fixed threshold for ≥5 days, producing CSV catalogues with columns for event ID, centre lat/lon, onset/peak/decay timestamps, and area. Following the threshold as in [Drouard et al. (2021)](https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2020JD034082), we separate the tracked features into blocking and propagating (prp) high pressure systems.
+
+> **Sample catalogue (ERA5, 1990–2020 blocking):** [`ERA5_TempestExtremes_z500_anticyclone_blocking.csv`](https://github.com/yanxingjianken/pvtend/raw/main/docs/_static/ERA5_TempestExtremes_z500_anticyclone_blocking.csv)
+
+The CSVs are the inputs for `pvtend-pipeline compute`, which extracts event-centred patches and runs the full PV-tendency decomposition for each event in the blocking/prp catalogue.
+
+## Features
+
+- **PV tendency computation**: RHS has zonal advection, baroclinic counter propagation, vertical advection, and approximated diabatic heating terms.
+- **QG omega solver**: Hoskins Q-vector formulation with **two methods**: FFT+Thomas (default, fast) and 3-D direct/iterative (BiCGSTAB+ILU, full horizontal Laplacian). Optional `center_lat` for dynamic f₀ (Li & O'Gorman 2020).
+- **Helmholtz decomposition**: 4 backends (direct, FFT, DCT, SOR) for limited-area domains
+- **Moist/dry omega splitting**: Decomposes vertical motion into moist and dry contributions
+- **Orthogonal basis decomposition**: Projects PV tendency onto intensification (β), propagation (αx, αy), and deformation (γ) modes
+- **RWB detection**: Two classification methods — **bay** (path-order, recommended with circumpolar-cropped contours) and **tilt** (centerline slope ±0.15 dead zone). Circumpolar-first contour extraction for robust NH analysis.
+- **Composite lifecycle**: Multi-stage ensemble averaging with onset/peak/decay staging
+- **CLI pipeline**: End-to-end processing via `pvtend-pipeline` command
+
+## Installation
+
+```bash
+# From source
+git clone https://github.com/yanxingjianken/pvtend.git
+cd pvtend
+pip install -e ".[dev]"
+
+# With micromamba
+micromamba create -f environment.yml
+micromamba activate pvtend_env
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from pvtend import NHGrid, ddx, ddy, compute_orthogonal_basis, project_field
+
+# Grid setup
+grid = NHGrid(lat=np.linspace(90, 0, 61), lon=np.linspace(-180, 178.5, 240))
+dx_arr = grid.dx_arr  # zonal spacing per latitude [m]
+dy = grid.dy           # meridional spacing [m]
+
+# Compute zonal derivative
+dfdx = ddx(field, dx_arr, periodic=False)
+
+# Orthogonal basis decomposition
+basis = compute_orthogonal_basis(pv_anom, pv_dx, pv_dy, x_rel, y_rel)
+result = project_field(tendency, basis)
+print(f"β = {result['beta']:.3e}")  # intensification rate
+```
+
+### CLI Pipeline
+
+```bash
+# Step 1: Compute PV tendencies → per-event NPZ files
+pvtend-pipeline compute \
+    --event-type blocking \
+    --events-csv events.csv \
+    --era5-dir /data/era5/ \
+    --clim-path /data/climatology/era5_hourly_clim.nc \
+    --out-dir /data/composite_blocking_tempest/ \
+    --dh-range=-49:25 --skip-existing
+
+# Step 2: RWB classification → variant tracksets PKL
+pvtend-pipeline classify \
+    --npz-dir /data/composite_blocking_tempest/ \
+    --output /data/outputs/rwb_variant_tracksets.pkl \
+    --stages onset peak decay \
+    --levels 500 400 300 200 --threshold 3
+
+# Step 3: Variant-aware composite accumulation → composite PKL
+pvtend-pipeline composite \
+    --npz-dir /data/composite_blocking_tempest/ \
+    --rwb-pkl /data/outputs/rwb_variant_tracksets.pkl \
+    --pkl-out /data/outputs/composite.pkl
+
+# Step 4 (optional): Orthogonal-basis decomposition
+pvtend-pipeline decompose \
+    --pkl-in /data/outputs/composite.pkl \
+    --out-dir /data/outputs/decomp/
+```
+
+## Workflow
+
+```mermaid
+graph TD
+    A[ERA5 Monthly NetCDF] --> B[pvtend.preprocessing]
+    B --> C[Regridded NH Grid]
+    C --> D[pvtend.climatology]
+    D --> E[Monthly Climatology]
+    C & E --> F[pvtend.tendency.TendencyComputer]
+    F --> G[PV Tendency Terms]
+    G --> H[pvtend.omega — QG ω solver]
+    G --> I[pvtend.helmholtz — Helmholtz decomp.]
+    H & I --> J[pvtend.moist_dry — ω splitting]
+    G & J --> K[Per-event NPZ patches]
+    K --> L1[pvtend.classify — RWB Pass 1]
+    L1 --> L1a[rwb_variant_tracksets.pkl]
+    K & L1a --> L2[pvtend.composite_builder — Pass 2]
+    L2 --> L2a[composite.pkl]
+    L2a --> M[pvtend.decomposition — Orthogonal basis]
+    M --> N[β, αx, αy, γ coefficients]
+    N --> O[pvtend.plotting — Publication figures]
+```
+
+## Package Structure
+
+```
+src/pvtend/
+├── __init__.py          # Public API
+├── _version.py          # Version
+├── cli.py               # CLI entry point (compute, classify, composite, decompose)
+├── constants.py         # Physical constants
+├── grid.py              # NH grid & event patches
+├── preprocessing.py     # ERA5 loading & regridding
+├── derivatives.py       # Finite difference operators
+├── climatology.py       # Fourier-filtered climatology
+├── omega.py             # QG omega solver (FFT+Thomas or 3-D direct)
+├── helmholtz.py         # Helmholtz decomposition (direct/FFT/DCT/SOR)
+├── moist_dry.py         # Moist/dry omega split
+├── isentropic.py        # Isentropic PV-tendency diagnostics
+├── tendency.py          # Main pipeline: data loading, derivatives, cross-terms, NPZ output
+├── classify.py          # RWB classification Pass 1 (AWB/CWB/NEUTRAL → variant PKL)
+├── composite_builder.py # Variant-aware composite accumulation Pass 2
+├── rwb.py               # RWB detection (bay & tilt methods, circumpolar-first)
+├── composites.py        # Legacy composite lifecycle
+├── data/                # Bundled sample data
+│   ├── __init__.py      # load_idealized_pv() loader
+│   └── idealized_pv.npz # Synthetic Gaussian PV evolution
+├── decomposition/       # Orthogonal basis framework
+│   ├── __init__.py
+│   ├── smoothing.py
+│   ├── basis.py
+│   └── projection.py
+├── plotting/            # Visualization
+│   ├── __init__.py
+│   ├── basis_plots.py
+│   ├── coefficient_plots.py
+│   ├── field_plots.py
+│   ├── composite_explorer.py  # plot_var: single-variable composite explorer with bootstrap
+│   └── baroclinic.py          # plot_baroclinic_tilt: two-level v′ overlay
+└── io/                  # File I/O
+    ├── __init__.py
+    ├── era5.py
+    ├── npz.py
+    └── pkl.py
+```
+
+## Example Notebooks
+
+Notebooks using **real ERA5 blocking event data** from the `composite_blocking_tempest`, `composite_prp_tempest` (single event npz), `tempest_extreme_4_basis/outputs`, and `tempest_extreme_4_basis/outputs_prp` (composite pkl) pipeline:
+
+| Notebook | Description |
+|----------|-------------|
+| [`00_idealized_pvtend_decomp`](examples/00_idealized_pvtend_decomp.ipynb) | Idealized Gaussian PV anomaly: prescribed β/αx/αy/γ at two timesteps, basis visualisation, Gram-Schmidt, projection & reconstruction |
+| [`01_rwb_and_derivatives`](examples/01_rwb_and_derivatives.ipynb) | Grid setup, `ddx`/`ddy`/`ddp` derivatives, RWB detection on a real event |
+| [`02_helmholtz_and_qg_omega`](examples/02_helmholtz_and_qg_omega.ipynb) | 3-D Helmholtz decomposition, QG omega (FFT vs 3-D direct), moist/dry ω split |
+| [`03_four_basis_projection`](examples/03_four_basis_projection.ipynb) | Orthogonal basis (Φ₁–Φ₄), project dq'/dt → β/αx/αy/γ, lifecycle curves |
+| [`03z_four_basis_projection_geopotential`](examples/03z_four_basis_projection_geopotential.ipynb) | ↳ *Supplement*: same 4-basis projection using **geopotential height Z** instead of PV |
+| [`04_single_var_composite`](examples/04_single_var_composite.ipynb) | Single-variable composite explorer on pressure levels using `pvtend.plotting.plot_var` |
+| [`04i_single_var_isentropic_composite`](examples/04i_single_var_isentropic_composite.ipynb) | ↳ *Supplement*: same as 04 but on **isentropic (θ) surfaces** |
+| [`05_stacked_bar_beta`](examples/05_stacked_bar_beta.ipynb) | Stacked-bar β decomposition by PV-tendency term across lifecycle hours |
+| [`05b_grouped_terms_bootstrap`](examples/05b_grouped_terms_bootstrap.ipynb) | ↳ *Supplement*: grouped PV-tendency terms with **bootstrap resampling & significance** |
+| [`06_baroclinic_structure`](examples/06_baroclinic_structure.ipynb) | 3-D composite PV anomaly, lon–p cross-sections, 2-PVU tropopause, v′ tilt via `plot_baroclinic_tilt` |
+| [`07_facet_blocking_vs_prp`](examples/07_facet_blocking_vs_prp.ipynb) | Facet comparison of blocking vs PRP: bar charts with bootstrap significance, shared-cbar spatial maps, baroclinic tilt |
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## Documentation
+
+Full documentation at [pvtend.readthedocs.io](https://pvtend.readthedocs.io).
+
+Build locally:
+
+```bash
+cd docs && make html
+```
+
+## Citation
+
+If you use this package in your research, please cite:
+
+```bibtex
+@software{yan2025pvtend,
+  author = {Yan, Xingjian},
+  title = {pvtend: PV tendency decomposition for atmospheric blocking},
+  year = {2025},
+  url = {https://github.com/yanxingjianken/pvtend}
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pvtend-0.7.1/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pvtend"
+version = "0.7.1"
+authors = [
+    { name = "Xingjian Yan" },
+]
+description = "PV tendency decomposition diagnostics for blocking and weather extremes"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = [
+    "numpy>=1.22",
+    "scipy",
+    "xarray",
+    "pandas",
+    "netCDF4",
+    "tqdm",
+    "matplotlib",
+    "scikit-image",
+    "cdsapi",
+]
+
+[project.optional-dependencies]
+maps = ["cartopy"]
+sip = ["numba"]
+test = ["pytest", "dask"]
+docs = ["sphinx", "sphinx-rtd-theme", "nbsphinx", "ipykernel"]
+dev = ["pvtend[test,docs,sip]", "pre-commit", "ruff"]
+
+[project.urls]
+Documentation = "https://pvtend.readthedocs.io/"
+Repository = "https://github.com/yanxingjianken/pvtend"
+"Bug Tracker" = "https://github.com/yanxingjianken/pvtend/issues"
+
+[project.scripts]
+pvtend-pipeline = "pvtend.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"pvtend.data" = ["*.npz"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"

pvtend-0.7.1/setup.cfg

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