Python Hail Retrieval Toolkit (pyhail)
pyhail is a Python library providing hail retrieval algorithms for weather radar data. It supports both the Py-ART and pyodim radar interfaces and operates directly on native polar (PPI) data, with optional Cartesian gridding for MESH.
Retrievals
| Algorithm | Output field | Units | Description |
|---|---|---|---|
| MESH | mesh |
mm | Maximum Expected Size of Hail — column-integrated kinetic energy converted to hail diameter |
| HSDA | hsda |
class | Hail Size Discrimination Algorithm — polarimetric classification of hail size |
| HDR | hdr_size |
mm | Hail Differential Reflectivity — hail size estimate from ZH and ZDR |
| HACC | hacc |
cm/min | Hail Accumulation — surface hail accumulation rate |
MESH formulations
Four calibrations are available via the mesh_method parameter:
mesh_method |
Formula | Calibrated to | Reference |
|---|---|---|---|
witt1998 |
MESH = 2.54 × SHI^0.5 | 147 reports | Witt et al. (1998) |
mh2019_75 |
MESH = 15.096 × SHI^0.206 | 5897 reports, 75th pct | Murillo & Homeyer (2021) |
mh2019_95 |
MESH = 22.157 × SHI^0.212 | 5897 reports, 95th pct | Murillo & Homeyer (2021) |
blend (default) |
Logistic blend of witt1998 → mh2019_75 |
— | — |
The blend formulation transitions smoothly from Witt (1998) at low SHI to Murillo & Homeyer (2021)
at high SHI using a logistic weight, eliminating the discontinuous derivative of a hard piecewise switch.
The crossover point is the analytical intercept of the two power laws (SHI ≈ 429 J m⁻¹ s⁻¹,
MESH ≈ 52.6 mm).
C-band correction
When processing C-band radar data, MESH can apply a reflectivity correction for Mie scattering
and attenuation effects using radar_band='C' and correct_cband_refl=True
(Brook et al. 2023, arXiv:2306.12016).
Note: The HSDA Q confidence vector (Park et al. 2009) is not implemented; all pixels are assigned q = 1.
Installation
From PyPI
pip install pyhail
Conda environment (recommended for notebooks)
A full environment including Py-ART, pyodim, cartopy, and Jupyter is provided:
conda env create -f test_environment.yml
conda activate pyhail-test-env
From source
git clone git@github.com:joshua-wx/pyhail.git
cd pyhail
pip install -e .
Dependencies
Core (installed automatically via pip):
Radar I/O (install separately, choose one or both):
Notebooks only: matplotlib, cartopy, ipywidgets
Key parameters
MESH (mesh_ppi.pyart / mesh_ppi.pyodim)
| Parameter | Default | Description |
|---|---|---|
temp_levels |
— | [freezing_level, minus20_level] in m ASL |
mesh_method |
'blend' |
One of witt1998, mh2019_75, mh2019_95, blend |
radar_band |
'S' |
'S' or 'C' |
correct_cband_refl |
True |
Apply C-band Mie/attenuation correction |
min_range / max_range |
10 / 150 |
Range limits (km) |
transition_width |
200 |
Blend logistic width (J m⁻¹ s⁻¹); smaller = sharper transition |
HSDA (hsda.pyart / hsda.pyodim)
| Parameter | Default | Description |
|---|---|---|
levels |
— | [freezing_level, minus20_level] in m ASL |
hca_hail_idx |
— | HCA class indices to apply HSDA (e.g. [6, 7, 8] for hail classes) |
dzdr |
0 |
ZDR calibration offset (dB) |
HACC (hacc.pyart / hacc.pyodim)
| Parameter | Default | Description |
|---|---|---|
sweep_idx |
— | Sweep index for accumulation calculation |
mesh_idx |
— | Sweep index containing the MESH field |
fz_level |
— | Freezing level height (m) |
pressure |
— | Mean surface-to-freezing-level pressure (hPa) |
Testing
The unit tests cover the pure mathematical functions: MESH calibration formulas, HSDA membership
functions, the trapezoidal MF and aggregate scorer, and safe_log.
Requirements
pytest must be installed in the active environment:
pip install pytest
If you are using the conda environment from test_environment.yml, activate it first:
conda activate pyhail-test-env
pip install pytest
Running the tests
From the repository root:
python -m pytest tests/ -v
To run a single test file:
python -m pytest tests/test_mesh_formulas.py -v
| Test file | What it covers |
|---|---|
tests/test_mesh_formulas.py |
mesh_witt1998, mesh_mh2019_75, mesh_mh2019_95, mesh_smooth_blend |
tests/test_hsda_mf.py |
HSDA scalar membership functions (c, f1–f3, g1–g3) and build_mf for all altitude levels |
tests/test_hsda_core.py |
trapmf, calc_ag (weighting and rule 1), h_sz (rules 2 and 3) |
tests/test_common.py |
safe_log — scalar, array, custom eps, boundary values |
Notebooks
Working examples with bundled data are in notebooks/.
| Notebook | Description |
|---|---|
testing_pyart.ipynb |
All retrievals using the Py-ART interface |
testing_pyodim.ipynb |
All retrievals using the pyodim interface |
compare_mesh_fits.ipynb |
Comparison of the four MESH calibrations |
hybrid_mesh_blend.ipynb |
Interactive exploration of the smooth blend formulation |
c_band_mesh_correction.ipynb |
Effect of C-band correction on MESH (requires external data) |
References
- Witt et al. (1998) doi:10.1175/1520-0434(1998)013<0286:AEHDAF>2.0.CO;2
- Murillo & Homeyer (2021) doi:10.1175/JAMC-D-20-0271.1
- Ortega et al. (2016) doi:10.1175/JAMC-D-15-0203.1
- Ryzhkov et al. (2013) doi:10.1175/JAMC-D-13-074.1
- Depue et al. (2007) doi:10.1175/JAM2529.1
- Wallace et al. (2019) doi:10.1175/WAF-D-18-0053.1
- Kalina et al. (2016) doi:10.1175/WAF-D-15-0037.1
- Brook et al. (2023) arXiv:2306.12016
Issues and contact
Please use the GitHub issue tracker to report bugs or request features. Maintained by Joshua Soderholm (joshua.soderholm@bom.gov.au).
1 maintainer
Metadata
1 maintainer
Release files for pyhail 3.4.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| pyhail-3.4.2.tar.gz | 35.5 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pyhail-3.4.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 68.3 kB
Release files / pyhail-3.4.2.tar.gz
| Download URL | pyhail-3.4.2.tar.gz |
|---|---|
| Size | 35.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5cc23eabb0a7806667872c8b3094c7f753b20eb97c26ebe22c8313ac34e66c1b
|
|
BLAKE2b-256 checksum How to use checksums |
8da9bdab086b77fdd210ccd8101d108986f1d144e32810ed5163ff54d53ffb58
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Release files / pyhail-3.4.2-py3-none-any.whl
| Download URL | pyhail-3.4.2-py3-none-any.whl |
|---|---|
| Size | 32.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b77bfab01d4ae57b92711cd10200104f51c42ffb9c4bf4c0e76453f8eba1314a
|
|
BLAKE2b-256 checksum How to use checksums |
34a35c84862741733e44c43cbcbcdceb3614d633a07fdbc8b2c9ff281fd0442b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Security for pyhail 3.4.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
