eccopy 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. eccopy-1.0.0/LICENSE +39 -0
  2. eccopy-1.0.0/MANIFEST.in +6 -0
  3. eccopy-1.0.0/PKG-INFO +420 -0
  4. eccopy-1.0.0/README.md +387 -0
  5. eccopy-1.0.0/eccopy/__init__.py +46 -0
  6. eccopy-1.0.0/eccopy/core/__init__.py +55 -0
  7. eccopy-1.0.0/eccopy/core/classification.py +1023 -0
  8. eccopy-1.0.0/eccopy/core/colormaps.py +267 -0
  9. eccopy-1.0.0/eccopy/core/convectivity.py +43 -0
  10. eccopy-1.0.0/eccopy/core/coords.py +245 -0
  11. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r15_info.mat +0 -0
  12. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r15_step1.mat +0 -0
  13. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r15_step2.mat +0 -0
  14. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r15_step3.mat +0 -0
  15. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r15_step4.mat +0 -0
  16. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r15_step5.mat +0 -0
  17. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r15_step6.mat +0 -0
  18. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r25_info.mat +0 -0
  19. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r25_step1.mat +0 -0
  20. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r25_step2.mat +0 -0
  21. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r25_step3.mat +0 -0
  22. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r25_step4.mat +0 -0
  23. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r25_step5.mat +0 -0
  24. eccopy-1.0.0/eccopy/core/data/disk_decomp/disk_decomp_r25_step6.mat +0 -0
  25. eccopy-1.0.0/eccopy/core/data/disk_strels/disk_strel_r15.mat +0 -0
  26. eccopy-1.0.0/eccopy/core/data/disk_strels/disk_strel_r25.mat +0 -0
  27. eccopy-1.0.0/eccopy/core/data/disk_strels/disk_strel_r3.mat +0 -0
  28. eccopy-1.0.0/eccopy/core/data/disk_strels/disk_strel_r5.mat +0 -0
  29. eccopy-1.0.0/eccopy/core/debug.py +493 -0
  30. eccopy-1.0.0/eccopy/core/disk.py +178 -0
  31. eccopy-1.0.0/eccopy/core/temperature.py +250 -0
  32. eccopy-1.0.0/eccopy/core/texture.py +1398 -0
  33. eccopy-1.0.0/eccopy/eccopy1d/__init__.py +2 -0
  34. eccopy-1.0.0/eccopy/eccopy1d/classify.py +273 -0
  35. eccopy-1.0.0/eccopy/eccopy2d_h/__init__.py +2 -0
  36. eccopy-1.0.0/eccopy/eccopy2d_h/classify.py +281 -0
  37. eccopy-1.0.0/eccopy/eccopy2d_h/clumping.py +265 -0
  38. eccopy-1.0.0/eccopy/eccopy2d_v/__init__.py +2 -0
  39. eccopy-1.0.0/eccopy/eccopy2d_v/classify.py +288 -0
  40. eccopy-1.0.0/eccopy/eccopy3d/__init__.py +2 -0
  41. eccopy-1.0.0/eccopy/eccopy3d/classify.py +421 -0
  42. eccopy-1.0.0/eccopy/eccopy3d/clumping.py +477 -0
  43. eccopy-1.0.0/eccopy/params/__init__.py +6 -0
  44. eccopy-1.0.0/eccopy/params/classification_params.py +151 -0
  45. eccopy-1.0.0/eccopy/params/texture_params.py +66 -0
  46. eccopy-1.0.0/eccopy/params/vertical_params.py +54 -0
  47. eccopy-1.0.0/eccopy/params/window.py +141 -0
  48. eccopy-1.0.0/eccopy/stats/__init__.py +56 -0
  49. eccopy-1.0.0/eccopy/stats/basic_stats.py +370 -0
  50. eccopy-1.0.0/eccopy/tests/__init__.py +0 -0
  51. eccopy-1.0.0/eccopy/tests/_reference_impls/__init__.py +0 -0
  52. eccopy-1.0.0/eccopy/tests/_reference_impls/isotherm_height_reference.py +54 -0
  53. eccopy-1.0.0/eccopy/tests/_reference_impls/sliding_texture_reference.py +77 -0
  54. eccopy-1.0.0/eccopy/tests/_reference_impls/texture_2d_reference.py +309 -0
  55. eccopy-1.0.0/eccopy/tests/test_classification_1d_filter.py +151 -0
  56. eccopy-1.0.0/eccopy/tests/test_classification_rain_below_melt.py +130 -0
  57. eccopy-1.0.0/eccopy/tests/test_colormaps.py +213 -0
  58. eccopy-1.0.0/eccopy/tests/test_coords.py +127 -0
  59. eccopy-1.0.0/eccopy/tests/test_debug.py +226 -0
  60. eccopy-1.0.0/eccopy/tests/test_disk_generator.py +82 -0
  61. eccopy-1.0.0/eccopy/tests/test_eccopy1d.py +209 -0
  62. eccopy-1.0.0/eccopy/tests/test_eccopy2d_h.py +185 -0
  63. eccopy-1.0.0/eccopy/tests/test_eccopy2d_h_clumping.py +105 -0
  64. eccopy-1.0.0/eccopy/tests/test_eccopy2d_v.py +359 -0
  65. eccopy-1.0.0/eccopy/tests/test_eccopy3d.py +282 -0
  66. eccopy-1.0.0/eccopy/tests/test_examples.py +84 -0
  67. eccopy-1.0.0/eccopy/tests/test_min_valid_dbz.py +144 -0
  68. eccopy-1.0.0/eccopy/tests/test_notebooks.py +111 -0
  69. eccopy-1.0.0/eccopy/tests/test_numba_cross_validation.py +331 -0
  70. eccopy-1.0.0/eccopy/tests/test_packaging.py +144 -0
  71. eccopy-1.0.0/eccopy/tests/test_refl_texture_1d.py +167 -0
  72. eccopy-1.0.0/eccopy/tests/test_stats.py +117 -0
  73. eccopy-1.0.0/eccopy/tests/test_stats_sentinel.py +74 -0
  74. eccopy-1.0.0/eccopy/tests/test_temperature.py +207 -0
  75. eccopy-1.0.0/eccopy/tests/test_texture_kernel_modes.py +82 -0
  76. eccopy-1.0.0/eccopy/tests/test_texture_params_implemented.py +148 -0
  77. eccopy-1.0.0/eccopy/tests/test_vert_levels_type.py +180 -0
  78. eccopy-1.0.0/eccopy/tests/test_window.py +80 -0
  79. eccopy-1.0.0/eccopy.egg-info/PKG-INFO +420 -0
  80. eccopy-1.0.0/eccopy.egg-info/SOURCES.txt +83 -0
  81. eccopy-1.0.0/eccopy.egg-info/dependency_links.txt +1 -0
  82. eccopy-1.0.0/eccopy.egg-info/requires.txt +12 -0
  83. eccopy-1.0.0/eccopy.egg-info/top_level.txt +1 -0
  84. eccopy-1.0.0/pyproject.toml +71 -0
  85. eccopy-1.0.0/setup.cfg +4 -0
eccopy-1.0.0/LICENSE ADDED
@@ -0,0 +1,39 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Ian Christian Cornejo
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ 3. Neither the name of the copyright holder nor the names of its
16
+ contributors may be used to endorse or promote products derived from
17
+ this software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29
+
30
+ ---
31
+
32
+ EccoPy is an independent Python implementation of the ECCO algorithm.
33
+ Portions are ported from work by the NSF National Center for Atmospheric
34
+ Research, distributed under BSD licenses:
35
+
36
+ NCAR/lrose-ecco (MATLAB ECCO-V) BSD 2-Clause,
37
+ Copyright (c) 2024 NSF NCAR
38
+ NCAR/lrose-core (C++ ConvStratFinder) LROSE BSD License,
39
+ Copyright (c) 1990-2023 UCAR
@@ -0,0 +1,6 @@
1
+ include LICENSE
2
+ include README.md
3
+ include pyproject.toml
4
+ recursive-include eccopy/core/data *.mat
5
+ recursive-exclude * __pycache__
6
+ recursive-exclude * *.py[cod]
eccopy-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,420 @@
1
+ Metadata-Version: 2.4
2
+ Name: eccopy
3
+ Version: 1.0.0
4
+ Summary: Data-agnostic Python implementation of the ECCO / ConvStratFinder radar echo classification algorithm (1-D, 2-D-V, 2-D-H, 3-D). Operates purely on numpy arrays, with no file I/O.
5
+ Author-email: NCAR-EOL <romatschke@ucar.edu>
6
+ Maintainer: Ian Christian Cornejo
7
+ License-Expression: BSD-3-Clause
8
+ Project-URL: Repository, https://github.com/iancornejo/EccoPy
9
+ Project-URL: Algorithm Reference, https://doi.org/10.1175/JTECH-D-22-0019.1
10
+ Keywords: radar,meteorology,precipitation,convection,echo-classification
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: numpy>=1.24
23
+ Requires-Dist: scipy>=1.10
24
+ Requires-Dist: numba>=0.58
25
+ Provides-Extra: plot
26
+ Requires-Dist: matplotlib>=3.7; extra == "plot"
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest>=7.4; extra == "dev"
29
+ Requires-Dist: pytest-cov; extra == "dev"
30
+ Requires-Dist: matplotlib>=3.7; extra == "dev"
31
+ Requires-Dist: build>=1.0; extra == "dev"
32
+ Dynamic: license-file
33
+
34
+ # EccoPy
35
+
36
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21840860.svg)](https://doi.org/10.5281/zenodo.21840860)
37
+
38
+ Data-agnostic Python implementation of **ECCO** (Echo Classification from
39
+ COnvectivity), which separates convective from stratiform radar echo.
40
+
41
+ EccoPy operates purely on NumPy arrays. It never reads or writes files and
42
+ makes no assumption about coordinate system, file format, or radar type: you
43
+ supply reflectivity plus coordinate or spacing arrays, and get back
44
+ classification arrays of the same shape.
45
+
46
+ ```python
47
+ from eccopy import eccopy3d
48
+ from eccopy.params import WindowSpec
49
+
50
+ result = eccopy3d.run(dbz, coords_z=z_km, coords_y=y_km, coords_x=x_km,
51
+ height=height_km, temp=temp_c,
52
+ window=WindowSpec((7, "km")))
53
+
54
+ result.echo_type # classification codes, same shape as dbz
55
+ result.convectivity # 0-1 continuous score
56
+ result.texture # reflectivity variability
57
+ ```
58
+
59
+ ## Algorithm references
60
+
61
+ Dixon, M. J., and U. Romatschke, 2022: *Three-Dimensional
62
+ Convective-Stratiform Echo-Type Classification and Convectivity Retrieval
63
+ from Radar Reflectivity.* J. Atmos. Oceanic Technol., **39**, 11.
64
+ [doi:10.1175/JTECH-D-22-0018.1](https://doi.org/10.1175/JTECH-D-22-0018.1)
65
+
66
+ Romatschke, U., and M. J. Dixon, 2022: *Vertically Resolved
67
+ Convective-Stratiform Echo-Type Identification and Convectivity Retrieval
68
+ for Vertically Pointing Radars.* J. Atmos. Oceanic Technol., **39**, 11,
69
+ 1705-1716.
70
+ [doi:10.1175/JTECH-D-22-0019.1](https://doi.org/10.1175/JTECH-D-22-0019.1)
71
+
72
+ Reference implementations, which EccoPy ports:
73
+ [NCAR/lrose-ecco](https://github.com/NCAR/lrose-ecco) (MATLAB ECCO-V) and
74
+ [NCAR/lrose-core](https://github.com/NCAR/lrose-core) (C++ ConvStratFinder).
75
+
76
+ ## Installation
77
+
78
+ ```bash
79
+ pip install eccopy
80
+ pip install "eccopy[plot]" # adds matplotlib for eccopy.core.colormaps
81
+ ```
82
+
83
+ Requires Python 3.10+, NumPy, SciPy and Numba.
84
+
85
+ ## The workflow
86
+
87
+ Every module runs the same three stages.
88
+
89
+ ```mermaid
90
+ flowchart LR
91
+ A["reflectivity<br/>(dBZ)"] --> B["<b>texture</b><br/>variability in a<br/>sliding window"]
92
+ B --> C["<b>convectivity</b><br/>texture / texture_limit_high,<br/>clipped to 0-1"]
93
+ C --> D["<b>echo type</b><br/>thresholded, cleaned,<br/>sub-classified"]
94
+ ```
95
+
96
+ **Texture** measures how much reflectivity varies within a window, after a
97
+ local linear trend is removed. Convection is spatially rough; stratiform
98
+ precipitation is smooth. Removing the trend stops a broad, uniform gradient
99
+ from registering as roughness.
100
+
101
+ **Convectivity** rescales texture onto 0-1 by dividing by
102
+ `texture_limit_high` and clipping. With the default of 30, a texture of 15
103
+ gives exactly 0.5. An error of *e* in texture therefore produces an error of
104
+ *e*/30 in convectivity.
105
+
106
+ **Echo type** thresholds convectivity into stratiform, mixed and convective,
107
+ then cleans the result up - by morphological closing in the 1-D and 2-D-V
108
+ paths, by dual-threshold clumping in 2-D-H and 3-D. Where the necessary
109
+ fields are available, categories are further split by sub-type.
110
+
111
+ ## The four modules
112
+
113
+ | Module | Input shape | For |
114
+ |---|---|---|
115
+ | `eccopy1d` | `(N,)` | A single ordered sequence: a disdrometer or profiler time series, one radar ray, a transect through a grid. |
116
+ | `eccopy2d_v` | `(Z, X)` | A vertical cross-section: an RHI, a gridded cross-section, a column-versus-time curtain. |
117
+ | `eccopy2d_h` | `(Y, X)` | A horizontal field: a composite reflectivity mosaic, a single CAPPI level. |
118
+ | `eccopy3d` | `(Z, Y, X)` | A full Cartesian volume. |
119
+
120
+ They share the texture and convectivity stages and differ in how
121
+ classification is finished:
122
+
123
+ - **`eccopy1d` and `eccopy2d_v`** follow the MATLAB ECCO-V path. Texture
124
+ slides along one axis, and the classification is cleaned with
125
+ morphological closing. `eccopy2d_v` sub-classifies from the melting layer
126
+ and temperature when `height`, `melt` and `temp` are supplied together.
127
+ - **`eccopy2d_h` and `eccopy3d`** follow the C++ ConvStratFinder path.
128
+ Texture uses a 2-D radial kernel, and contiguous convective regions become
129
+ *clumps* that are split by a secondary threshold. `eccopy3d` sub-classifies
130
+ each clump from its own geometry - how tall it is, and what fraction sits
131
+ above the shallow and deep boundaries.
132
+
133
+ ### Echo type codes
134
+
135
+ Basic, returned when the fields needed for sub-classification are absent:
136
+
137
+ ```
138
+ 1 Stratiform 2 Mixed 3 Convective
139
+ ```
140
+
141
+ Sub-classified, from `eccopy2d_v` and `eccopy3d`:
142
+
143
+ ```
144
+ 14 Stratiform Low 16 Stratiform Mid 18 Stratiform High
145
+ 25 Mixed
146
+ 32 Convective Elevated 34 Convective Shallow
147
+ 36 Convective Mid 38 Convective Deep
148
+ ```
149
+
150
+ Codes are non-contiguous because they come from the reference
151
+ implementations. `eccopy.core.colormaps.remap_echo_type()` converts them to
152
+ contiguous indices for plotting.
153
+
154
+ `eccopy3d` returns `int16` with `0` marking no echo; the other three return
155
+ float arrays using `NaN`. Mask 3-D output with
156
+ `np.isin(echo_type, CLASSES)`, not `np.isfinite()`.
157
+
158
+ ## Coordinates and windows
159
+
160
+ Coordinates may be positions or per-point spacings, in kilometres, and may be
161
+ 1-D per axis or full 2-D/3-D fields. `coord_mode` controls the
162
+ interpretation: `"auto"` (default), `"position"`, or `"spacing"`.
163
+
164
+ `WindowSpec` sizes the texture window in physical units, resolved against the
165
+ spacing you supplied:
166
+
167
+ ```python
168
+ WindowSpec((7, "km")) # 7 km radius
169
+ WindowSpec((15, "min")) # 15-minute radius; coords in seconds
170
+ WindowSpec(28) # 28 samples, regardless of spacing
171
+ ```
172
+
173
+ For geographic grids, `latlon_to_xy_spacing()` converts 2-D latitude and
174
+ longitude fields to north-south and east-west spacings, and
175
+ `time_to_distance_km()` converts a time axis to wind-advected distance.
176
+
177
+ ### `kernel_mode`
178
+
179
+ On a grid whose spacing is not uniform - a lat/lon mesh, or range gates that
180
+ change with elevation angle - a fixed physical window covers different
181
+ numbers of cells in different places. `kernel_mode` decides how that is
182
+ handled:
183
+
184
+ - **`"uniform"`** (default) resolves one kernel from the domain's median
185
+ spacing and applies it everywhere. This is what the reference
186
+ implementations do: `f_reflTexture.m` takes a single scalar `pixRad`, and
187
+ ConvStratFinder builds one kernel for the grid.
188
+ - **`"varying"`** resolves the kernel separately at each point from that
189
+ point's local spacing.
190
+
191
+ The two are identical on evenly spaced grids. On a non-uniform grid they
192
+ differ, and neither is a ground truth for the other - `"uniform"` reproduces
193
+ the reference, `"varying"` is arguably closer to the physical intent. Treat
194
+ any comparison between them as a sensitivity study.
195
+
196
+ ## Parameters
197
+
198
+ Defaults come from the reference implementations. Columns mark which modules
199
+ read each parameter.
200
+
201
+ ### `TextureParams`
202
+
203
+ | Parameter | Default | 1D | 2D-V | 2D-H | 3D |
204
+ |---|---|:-:|:-:|:-:|:-:|
205
+ | `dbz_base` | `0.0` | X | X | X | X |
206
+ | `texture_limit_high` | `30.0` | X | X | X | X |
207
+ | `min_valid_dbz` | `None` | X | X | X | X |
208
+ | `min_frac_texture` | `0.25` | | | X | X |
209
+ | `min_frac_fit` | `0.67` | | | X | X |
210
+ | `texture_limit_low` | `0.0` | X | X | X | X |
211
+ | `use_dbz_col_max` | `False` | | | | X |
212
+ | `dbz_for_echo_tops` | `18.0` | | | | X |
213
+
214
+ Convectivity is scaled across `[texture_limit_low, texture_limit_high]`;
215
+ texture below the low limit gives missing convectivity rather than zero.
216
+ `use_dbz_col_max` computes texture once from column-maximum reflectivity
217
+ and copies it to every level. `dbz_for_echo_tops` sets the reflectivity
218
+ threshold defining `Result3D.echo_top_km`.
219
+
220
+ `min_valid_dbz` nulls reflectivity below the threshold before texture is
221
+ computed. `None` means "use this module's reference default": `0.0` for
222
+ `eccopy2d_h` and `eccopy3d`, matching ConvStratFinder's prefilter, and no
223
+ gating for `eccopy1d` and `eccopy2d_v`, matching `f_reflTexture.m`, which has
224
+ no equivalent. An explicit value is honoured everywhere.
225
+
226
+ ### `ClassificationParams`
227
+
228
+ | Parameter | Default | 1D | 2D-V | 2D-H | 3D |
229
+ |---|---|:-:|:-:|:-:|:-:|
230
+ | `max_convectivity_for_stratiform` | `0.4` | X | X | X | X |
231
+ | `min_convectivity_for_convective` | `0.5` | X | X | X | X |
232
+ | `enlarge_mixed` | `5` | X | X | | |
233
+ | `enlarge_conv` | `5` | X | X | | |
234
+ | `surf_alt_lim` | `0.0` | | X | | |
235
+ | `use_dual_thresholds` | `True` | | | X | X |
236
+ | `secondary_convectivity` | `0.65` | | | X | X |
237
+ | `all_subclumps_min_area_frac` | `0.33` | | | X | X |
238
+ | `each_subclump_min_area_frac` | `0.02` | | | X | X |
239
+ | `each_subclump_min_area_km2` | `2.0` | | | X | X |
240
+ | `min_valid_volume_for_convective` | `20.0` | | | | X |
241
+ | `min_vert_extent_for_convective` | `1.0` | | | | X |
242
+ | `min_conv_fraction_for_shallow` | `0.95` | | | | X |
243
+ | `min_conv_fraction_for_deep` | `0.05` | | | | X |
244
+ | `max_shallow_conv_fraction_for_elevated` | `0.05` | | | | X |
245
+ | `max_deep_conv_fraction_for_elevated` | `0.25` | | | | X |
246
+ | `min_strat_fraction_for_strat_below` | `0.9` | | | | X |
247
+ | `min_ht_km_agl_for_mid` | `2.0` | | | | X |
248
+ | `min_ht_km_agl_for_deep` | `4.0` | | | | X |
249
+ | `min_overlap_for_convective_clumps` | `1` | | | X | X |
250
+
251
+ Convectivity below `max_convectivity_for_stratiform` is stratiform, at or
252
+ above `min_convectivity_for_convective` is convective, and the gap between
253
+ them is mixed.
254
+
255
+ `enlarge_mixed` and `enlarge_conv` are **pixel counts**, as in
256
+ `f_classBasic.m` - so on a non-uniform grid the same value spans a different
257
+ physical distance in different places.
258
+
259
+ `each_subclump_min_area_km2` denotes a true **area** in `eccopy2d_h` and a
260
+ pseudo-**volume** in `eccopy3d`. A single `ClassificationParams` shared
261
+ between the two will not behave identically at the same numeric value.
262
+
263
+ `min_ht_km_agl_for_mid` and `min_ht_km_agl_for_deep` apply only when
264
+ `terrain_ht` is supplied, where they raise the boundaries to
265
+ `max(threshold, terrain + value)`.
266
+
267
+ Only `min_overlap_for_convective_clumps = 1` is implemented, where interval
268
+ clumping and 6-/4-connectivity coincide; other values raise.
269
+
270
+ ### `VerticalParams` (`eccopy3d` only)
271
+
272
+ | Parameter | Default |
273
+ |---|---|
274
+ | `vert_levels_type` | `"by_height"` |
275
+ | `shallow_threshold_ht` | `4.5` km |
276
+ | `deep_threshold_ht` | `9.0` km |
277
+ | `shallow_threshold_temp` | `0.0` °C |
278
+ | `deep_threshold_temp` | `-12.0` °C |
279
+ | `min_valid_height` | `0.0` km |
280
+ | `max_valid_height` | `25.0` km |
281
+
282
+ `vert_levels_type` selects whether clump sub-typing uses the height or the
283
+ temperature pair. Under `"by_temp"` a supplied `height` field is not used for
284
+ that purpose, and EccoPy warns to say so. The height band is inert at its
285
+ defaults, which span any realistic grid.
286
+
287
+ ### `run()` arguments
288
+
289
+ Every module takes `window`, `coord_mode`, `kernel_mode` and
290
+ `return_intermediates`. Beyond those:
291
+
292
+ | Module | Additional arguments |
293
+ |---|---|
294
+ | `eccopy1d` | `min_convective_length` |
295
+ | `eccopy2d_v` | `height`, `melt`, `temp`, `topo`, `remove_surface_echo` |
296
+ | `eccopy2d_h` | `min_convective_area`, `n_threads` |
297
+ | `eccopy3d` | `height`, `temp`, `terrain_ht`, `n_threads`, `levels` |
298
+
299
+ ## Performance
300
+
301
+ Every hot loop - the sliding-window texture cores, the per-level texture
302
+ computation, coverage-fraction accounting, and isotherm-height search - is
303
+ JIT-compiled with [Numba](https://numba.pydata.org). Each compiled routine is
304
+ cross-validated against a frozen pure-Python reference in the test suite, so
305
+ the acceleration is checked rather than assumed.
306
+
307
+ The first call in a session pays a one-off compilation cost of a few seconds.
308
+ `eccopy2d_h` and `eccopy3d` also accept `n_threads` for the texture stage.
309
+
310
+ For very large grids - full-CONUS MRMS is 3500 x 7000 - process one file at a
311
+ time and reduce as you go rather than opening many at once.
312
+
313
+ ## Plotting
314
+
315
+ EccoPy draws no figures. Every output array has the same shape as the
316
+ reflectivity you passed in, so whatever you already use to plot your data
317
+ works unchanged on `result.echo_type`.
318
+
319
+ What it does provide is `eccopy.core.colormaps`, which supplies matching
320
+ colormaps, norms and labels - the echo-type codes are not contiguous, and the
321
+ convectivity colormap breaks exactly at the classification thresholds:
322
+
323
+ ```python
324
+ from eccopy.core.colormaps import (
325
+ echo_type_cmap, echo_type_norm, ECHO_TYPE_LABELS, remap_echo_type,
326
+ convectivity_cmap, convectivity_norm, draw_window_ring,
327
+ )
328
+
329
+ ax.pcolormesh(x, y, remap_echo_type(result.echo_type),
330
+ cmap=echo_type_cmap(), norm=echo_type_norm())
331
+ ```
332
+
333
+ `draw_window_ring()` overlays the texture-window footprint; pass
334
+ `coord_units="degrees"` on a lat/lon panel.
335
+
336
+ ## Notebooks
337
+
338
+ `notebooks/` holds one worked example per module, each running end-to-end on
339
+ real data bundled under `notebooks/data/` - a disdrometer record, an S-Pol
340
+ RHI with a co-located sounding, an MRMS composite, and a WRF volume. They
341
+ walk the full chain, show every intermediate array, document the parameters
342
+ that module consumes, and end with a helper for sweeping parameters on your
343
+ own data.
344
+
345
+ ## Example scripts
346
+
347
+ `examples/` holds the same four walkthroughs as runnable scripts, for
348
+ anyone who would rather not use Jupyter:
349
+
350
+ ```bash
351
+ python examples/example_2d_v.py # print results
352
+ python examples/example_2d_v.py --outdir figs # also save a figure
353
+ ```
354
+
355
+ ## Statistics
356
+
357
+ `eccopy.stats` works on any classified array:
358
+
359
+ ```python
360
+ from eccopy import stats
361
+
362
+ stats.echo_type_fractions(echo_type) # coverage by category
363
+ stats.convective_percentage(echo_type)
364
+ stats.n_clumps(echo_type, "convective")
365
+ stats.convective_top_height(echo_type, height, axis=0)
366
+ stats.summarize(echo_type, height=height, axis=0)
367
+ ```
368
+
369
+ Height-aware functions need a vertical axis, so they apply to `eccopy2d_v`
370
+ and `eccopy3d` output only.
371
+
372
+ ## Tests
373
+
374
+ ```bash
375
+ pip install -e ".[dev,plot]"
376
+ pytest eccopy/tests/
377
+ ```
378
+
379
+ ## Citing EccoPy
380
+
381
+ Archived on Zenodo. Cite the concept DOI, which always resolves to the
382
+ latest release:
383
+
384
+ > [10.5281/zenodo.21840860](https://doi.org/10.5281/zenodo.21840860)
385
+
386
+ For exact reproducibility, cite the DOI of the specific version you used
387
+ instead - v1.0.0 is [10.5281/zenodo.21840861](https://doi.org/10.5281/zenodo.21840861).
388
+
389
+ `CITATION.cff` in the repository root carries the full software citation,
390
+ which GitHub renders as a "Cite this repository" button. Please cite the
391
+ two algorithm papers above alongside it: EccoPy is an implementation, and
392
+ the method is theirs.
393
+
394
+ ## Acknowledgements
395
+
396
+ The ECCO algorithm is the work of Michael Dixon and Ulrike Romatschke at
397
+ NCAR; EccoPy is a port, not a new method. The sample datasets bundled with
398
+ the notebooks were provided by the individuals and campaigns credited in
399
+ [notebooks/data/README.md](notebooks/data/README.md).
400
+
401
+ Portions of the v1.0 refactor were developed with assistance from
402
+ Anthropic's Claude.
403
+
404
+ ## Contributing
405
+
406
+ Contributions are very welcome - bug reports, new test cases, documentation,
407
+ support for new instruments and file conventions, or performance work. If you
408
+ use EccoPy on a dataset it was not designed around and something breaks or
409
+ looks wrong, that is worth an issue on its own.
410
+
411
+ [CONTRIBUTING.md](CONTRIBUTING.md) describes the development workflow. The one
412
+ thing to read before changing the classification path is the ground-truth
413
+ standard: changes there are verified against real MATLAB or C++ reference
414
+ output, not against physical reasoning alone.
415
+
416
+ Release history is in [CHANGELOG.md](CHANGELOG.md).
417
+
418
+ ## License
419
+
420
+ See [LICENSE](LICENSE).