eccopy 1.0.0__py3-none-any.whl

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 (79) hide show
  1. eccopy/__init__.py +46 -0
  2. eccopy/core/__init__.py +55 -0
  3. eccopy/core/classification.py +1023 -0
  4. eccopy/core/colormaps.py +267 -0
  5. eccopy/core/convectivity.py +43 -0
  6. eccopy/core/coords.py +245 -0
  7. eccopy/core/data/disk_decomp/disk_decomp_r15_info.mat +0 -0
  8. eccopy/core/data/disk_decomp/disk_decomp_r15_step1.mat +0 -0
  9. eccopy/core/data/disk_decomp/disk_decomp_r15_step2.mat +0 -0
  10. eccopy/core/data/disk_decomp/disk_decomp_r15_step3.mat +0 -0
  11. eccopy/core/data/disk_decomp/disk_decomp_r15_step4.mat +0 -0
  12. eccopy/core/data/disk_decomp/disk_decomp_r15_step5.mat +0 -0
  13. eccopy/core/data/disk_decomp/disk_decomp_r15_step6.mat +0 -0
  14. eccopy/core/data/disk_decomp/disk_decomp_r25_info.mat +0 -0
  15. eccopy/core/data/disk_decomp/disk_decomp_r25_step1.mat +0 -0
  16. eccopy/core/data/disk_decomp/disk_decomp_r25_step2.mat +0 -0
  17. eccopy/core/data/disk_decomp/disk_decomp_r25_step3.mat +0 -0
  18. eccopy/core/data/disk_decomp/disk_decomp_r25_step4.mat +0 -0
  19. eccopy/core/data/disk_decomp/disk_decomp_r25_step5.mat +0 -0
  20. eccopy/core/data/disk_decomp/disk_decomp_r25_step6.mat +0 -0
  21. eccopy/core/data/disk_strels/disk_strel_r15.mat +0 -0
  22. eccopy/core/data/disk_strels/disk_strel_r25.mat +0 -0
  23. eccopy/core/data/disk_strels/disk_strel_r3.mat +0 -0
  24. eccopy/core/data/disk_strels/disk_strel_r5.mat +0 -0
  25. eccopy/core/debug.py +493 -0
  26. eccopy/core/disk.py +178 -0
  27. eccopy/core/temperature.py +250 -0
  28. eccopy/core/texture.py +1398 -0
  29. eccopy/eccopy1d/__init__.py +2 -0
  30. eccopy/eccopy1d/classify.py +273 -0
  31. eccopy/eccopy2d_h/__init__.py +2 -0
  32. eccopy/eccopy2d_h/classify.py +281 -0
  33. eccopy/eccopy2d_h/clumping.py +265 -0
  34. eccopy/eccopy2d_v/__init__.py +2 -0
  35. eccopy/eccopy2d_v/classify.py +288 -0
  36. eccopy/eccopy3d/__init__.py +2 -0
  37. eccopy/eccopy3d/classify.py +421 -0
  38. eccopy/eccopy3d/clumping.py +477 -0
  39. eccopy/params/__init__.py +6 -0
  40. eccopy/params/classification_params.py +151 -0
  41. eccopy/params/texture_params.py +66 -0
  42. eccopy/params/vertical_params.py +54 -0
  43. eccopy/params/window.py +141 -0
  44. eccopy/stats/__init__.py +56 -0
  45. eccopy/stats/basic_stats.py +370 -0
  46. eccopy/tests/__init__.py +0 -0
  47. eccopy/tests/_reference_impls/__init__.py +0 -0
  48. eccopy/tests/_reference_impls/isotherm_height_reference.py +54 -0
  49. eccopy/tests/_reference_impls/sliding_texture_reference.py +77 -0
  50. eccopy/tests/_reference_impls/texture_2d_reference.py +309 -0
  51. eccopy/tests/test_classification_1d_filter.py +151 -0
  52. eccopy/tests/test_classification_rain_below_melt.py +130 -0
  53. eccopy/tests/test_colormaps.py +213 -0
  54. eccopy/tests/test_coords.py +127 -0
  55. eccopy/tests/test_debug.py +226 -0
  56. eccopy/tests/test_disk_generator.py +82 -0
  57. eccopy/tests/test_eccopy1d.py +209 -0
  58. eccopy/tests/test_eccopy2d_h.py +185 -0
  59. eccopy/tests/test_eccopy2d_h_clumping.py +105 -0
  60. eccopy/tests/test_eccopy2d_v.py +359 -0
  61. eccopy/tests/test_eccopy3d.py +282 -0
  62. eccopy/tests/test_examples.py +84 -0
  63. eccopy/tests/test_min_valid_dbz.py +144 -0
  64. eccopy/tests/test_notebooks.py +111 -0
  65. eccopy/tests/test_numba_cross_validation.py +331 -0
  66. eccopy/tests/test_packaging.py +144 -0
  67. eccopy/tests/test_refl_texture_1d.py +167 -0
  68. eccopy/tests/test_stats.py +117 -0
  69. eccopy/tests/test_stats_sentinel.py +74 -0
  70. eccopy/tests/test_temperature.py +207 -0
  71. eccopy/tests/test_texture_kernel_modes.py +82 -0
  72. eccopy/tests/test_texture_params_implemented.py +148 -0
  73. eccopy/tests/test_vert_levels_type.py +180 -0
  74. eccopy/tests/test_window.py +80 -0
  75. eccopy-1.0.0.dist-info/METADATA +420 -0
  76. eccopy-1.0.0.dist-info/RECORD +79 -0
  77. eccopy-1.0.0.dist-info/WHEEL +5 -0
  78. eccopy-1.0.0.dist-info/licenses/LICENSE +39 -0
  79. eccopy-1.0.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,1023 @@
1
+ """
2
+ Basic and sub-classification functions.
3
+
4
+ class_basic() - port of f_classBasic.m (EccoPy-1D / EccoPy-2D)
5
+ class_sub_2d() - port of f_classSub.m (EccoPy-1D / EccoPy-2D)
6
+ set_echo_type_3d() - port of ConvStratFinder::_setEchoType3D() + StormClump
7
+
8
+ Upstream analogues:
9
+ lrose-ecco @ ad85c56 f_classBasic.m, f_classSub.m
10
+ lrose-core @ b29264bf ConvStratFinder.cc
11
+
12
+ Echo type codes (matching f_classSub.m and the C++ enum values)
13
+ ---------------------------------------------------------------
14
+ 14 CATEGORY_STRATIFORM_LOW
15
+ 16 CATEGORY_STRATIFORM_MID
16
+ 18 CATEGORY_STRATIFORM_HIGH
17
+ 25 CATEGORY_MIXED
18
+ 30 CATEGORY_CONVECTIVE (airborne-radar branch; see class_sub_2d)
19
+ 32 CATEGORY_CONVECTIVE_ELEVATED
20
+ 34 CATEGORY_CONVECTIVE_SHALLOW
21
+ 36 CATEGORY_CONVECTIVE_MID
22
+ 38 CATEGORY_CONVECTIVE_DEEP
23
+ 0 CATEGORY_MISSING
24
+
25
+ Morphology conventions
26
+ ----------------------
27
+ Two details of this file's morphological logic differ from a naive
28
+ translation and are load-bearing:
29
+
30
+ - `binary_erosion` / `binary_closing` are called with `border_value=1`.
31
+ SciPy defaults to 0, which erodes inward from every array edge and
32
+ removes near-surface regions that MATLAB's imclose retains.
33
+
34
+ - Closing runs through `_sequential_close()`, which applies MATLAB's
35
+ own strel decomposition primitives (from `getsequence()`) one at a
36
+ time, each as edge-pad, dilate, erode, crop - see `_edge_pad_close()`.
37
+ A single dilate-then-erode with the full disk gives a different
38
+ result.
39
+
40
+ `class_basic_isotropic()` uses `scipy.ndimage.binary_closing()` directly
41
+ rather than `_sequential_close()`, so the second point above does not
42
+ apply to it.
43
+
44
+ Structuring elements
45
+ --------------------
46
+ `_disk()` and `_sequential_close()` obtain their `strel('disk', r)`
47
+ neighbourhoods and `getsequence()` decompositions from `eccopy.core.disk`,
48
+ which reproduces MATLAB's default n=4 periodic-line octagon (Adams 1993)
49
+ in pure Python at any radius.
50
+
51
+ The octagon is not a Euclidean circle, and the difference is not
52
+ cosmetic: `strel('disk', 25)` has a 49x49 bounding box, not 51x51, so a
53
+ literal `x^2 + y^2 <= r^2` mask over-reaches MATLAB's shape at every
54
+ radius. `eccopy.core.disk` produces the octagon; Euclidean (n=0) is
55
+ available there as an explicit opt-in.
56
+
57
+ Because shapes are generated on demand, `enlarge_mixed` / `enlarge_conv`
58
+ are not restricted to any pre-exported set of radii. The `.mat` files
59
+ bundled under `core/data/` are optional: `_disk()` and `_load_decomp()`
60
+ use one as an override when present - byte-identical to the generator -
61
+ and otherwise generate. They serve as regression fixtures; see
62
+ `tests/test_disk_generator.py`.
63
+
64
+ Data-file paths are anchored to this module's location
65
+ (`Path(__file__).parent / "data" / ...`), not the caller's working
66
+ directory. The fixtures ship via `pyproject.toml` package-data and
67
+ `MANIFEST.in`.
68
+
69
+ enlarge_mixed / enlarge_conv are pixel counts
70
+ ---------------------------------------------
71
+ Both default to 5, matching f_classBasic.m, and are read as gate/pixel
72
+ counts exactly as the MATLAB source does - not as physical distances.
73
+
74
+ On a non-uniform grid (an RHI whose range-gate spacing changes with
75
+ elevation angle, or any axis whose spacing varies by row) the same
76
+ `enlarge_conv=5` therefore represents a different physical radius at
77
+ different rows. That is the upstream behaviour. A spacing-aware cleanup
78
+ would need a distinct disk at every local spacing, which no upstream
79
+ source specifies.
80
+ """
81
+
82
+ from __future__ import annotations
83
+ from pathlib import Path
84
+ from typing import Optional, Tuple
85
+ import numpy as np
86
+ from scipy.io import loadmat
87
+ from scipy.ndimage import (
88
+ label, binary_dilation, binary_erosion,
89
+ binary_fill_holes,
90
+ )
91
+
92
+ # Integer echo-type codes
93
+ CATEGORY_MISSING = 0
94
+ CATEGORY_STRATIFORM_LOW = 14
95
+ CATEGORY_STRATIFORM_MID = 16
96
+ CATEGORY_STRATIFORM_HIGH = 18
97
+ CATEGORY_MIXED = 25
98
+ CATEGORY_CONVECTIVE = 30 # near-aircraft override, both branches
99
+ CATEGORY_CONVECTIVE_ELEVATED = 32
100
+ CATEGORY_CONVECTIVE_SHALLOW = 34
101
+ CATEGORY_CONVECTIVE_MID = 36
102
+ CATEGORY_CONVECTIVE_DEEP = 38
103
+
104
+ _CONN8 = np.ones((3, 3), dtype=bool) # MATLAB bwconncomp's default 2-D connectivity;
105
+ # scipy's label() default is 4-connectivity and
106
+ # will silently disagree with MATLAB unless this
107
+ # structure is passed explicitly every time.
108
+
109
+ # ---------------------------------------------------------------------------
110
+ # Structuring elements -- loaded from MATLAB, not approximated.
111
+ # See module docstring "PACKAGING REQUIREMENT" above.
112
+ # ---------------------------------------------------------------------------
113
+
114
+ _DISK_STREL_DIR = str(Path(__file__).parent / "data" / "disk_strels")
115
+ _DISK_DECOMP_DIR = str(Path(__file__).parent / "data" / "disk_decomp")
116
+ # Anchored to __file__, not the caller's working directory: a relative
117
+ # path would resolve only when the process happened to be started beside
118
+ # a disk_strels/ folder.
119
+ #
120
+ # This assumes the data files live at <package_dir>/core/data/disk_strels/
121
+ # and <package_dir>/core/data/disk_decomp/ (i.e. a `data/` folder next to
122
+ # this classification.py file). Adjust the two lines above if the actual
123
+ # package layout puts the data files elsewhere -- e.g. if data files are
124
+ # meant to live at the top-level package root rather than inside core/,
125
+ # use Path(__file__).parent.parent / "data" / ... instead. Whoever wires
126
+ # this into the actual package's setup.py/pyproject.toml packaging
127
+ # (package_data / include_package_data) needs to make sure these two
128
+ # folders actually ship with an installed copy of eccopy, not just exist
129
+ # in a development checkout.
130
+
131
+ _disk_cache = {}
132
+ _decomp_cache = {}
133
+
134
+
135
+ def _disk(radius: int) -> np.ndarray:
136
+ """Exact MATLAB strel('disk', radius).Neighborhood (the n=4 octagon),
137
+ for any radius. This is MATLAB's octagon, not a Euclidean circle -
138
+ see the module docstring.
139
+
140
+ Generated in pure Python by eccopy.core.disk, bit-exact to MATLAB -
141
+ see tests/test_disk_generator.py. A bundled .mat for this radius, if
142
+ present, is used as-is; it is byte-identical to the generator, so the
143
+ validated
144
+ radii changes."""
145
+ from .disk import disk_neighborhood
146
+ r = int(radius)
147
+ if r not in _disk_cache:
148
+ mat = Path(f"{_DISK_STREL_DIR}/disk_strel_r{r}.mat")
149
+ if mat.exists():
150
+ _disk_cache[r] = loadmat(str(mat))["nhood"].astype(bool)
151
+ else:
152
+ _disk_cache[r] = disk_neighborhood(r, n=4)
153
+ return _disk_cache[r]
154
+
155
+
156
+ def _load_decomp(radius: int):
157
+ """MATLAB's getsequence(strel('disk', radius)) primitives, for any
158
+ radius. Generated in pure Python by eccopy.core.disk, bit-exact to
159
+ MATLAB - see tests/test_disk_generator.py. A bundled .mat for this
160
+ radius, if present, is used as-is."""
161
+ from .disk import disk_decomposition
162
+ r = int(radius)
163
+ if r not in _decomp_cache:
164
+ info_mat = Path(f"{_DISK_DECOMP_DIR}/disk_decomp_r{r}_info.mat")
165
+ if info_mat.exists():
166
+ n_steps = int(loadmat(str(info_mat))["n_steps"][0][0])
167
+ _decomp_cache[r] = [
168
+ loadmat(f"{_DISK_DECOMP_DIR}/disk_decomp_r{r}_step{k}.mat")["nhood_k"].astype(bool)
169
+ for k in range(1, n_steps + 1)
170
+ ]
171
+ else:
172
+ _decomp_cache[r] = disk_decomposition(r, n=4)
173
+ return _decomp_cache[r]
174
+
175
+
176
+ def _line_h(length: int) -> np.ndarray:
177
+ return np.ones((1, int(length)), dtype=bool)
178
+
179
+
180
+ # ---------------------------------------------------------------------------
181
+ # Physical-radius -> pixel-radius convenience for enlarge_mixed/enlarge_conv
182
+ # (see module docstring "PIXEL COUNTS, NOT PHYSICAL UNITS" section).
183
+ # ---------------------------------------------------------------------------
184
+
185
+ def available_enlarge_radii_px() -> list:
186
+ """
187
+ List the pixel radii that have a bundled MATLAB-exported disk-mask
188
+ fixture. NOTE: this is NO LONGER a limit on which radii _disk() can
189
+ produce -- eccopy.core.disk generates any radius on demand (see module
190
+ docstring "DISK STRUCTURING ELEMENTS"). This function now just reports
191
+ which radii have exact-ground-truth .mat fixtures bundled (useful for
192
+ tests / provenance), queried live from the data directory so it can't
193
+ drift out of sync with whatever .mat files ship with a given install.
194
+
195
+ Returns
196
+ -------
197
+ list of int, sorted ascending. Empty if the data directory is
198
+ missing or contains no recognisable disk_strel_r{R}.mat files.
199
+ """
200
+ import re
201
+ d = Path(_DISK_STREL_DIR)
202
+ if not d.exists():
203
+ return []
204
+ radii = []
205
+ for f in d.glob("disk_strel_r*.mat"):
206
+ m = re.match(r"disk_strel_r(\d+)\.mat$", f.name)
207
+ if m:
208
+ radii.append(int(m.group(1)))
209
+ return sorted(radii)
210
+
211
+
212
+ def resolve_enlarge_radius_px(target_km: float,
213
+ representative_spacing_km: float) -> int:
214
+ """
215
+ Convert a target PHYSICAL enlarge radius (km) into a pixel radius --
216
+ a one-shot, UNIFORM-GRID-ONLY convenience. See module docstring
217
+ "PIXEL COUNTS, NOT PHYSICAL UNITS" for why this does NOT have a
218
+ genuinely spacing-aware ("varying", in refl_texture_1d's kernel_mode
219
+ sense) counterpart: that would be a modelling decision, not a shape
220
+ lookup.
221
+
222
+ Since eccopy.core.disk generates the structuring element at any
223
+ radius, this now resolves to the EXACT rounded pixel radius --
224
+ round(target_km / representative_spacing_km) -- rather than snapping
225
+ to a small set of pre-exported masks. No approximation, no warning.
226
+
227
+ Parameters
228
+ ----------
229
+ target_km : float
230
+ Desired physical enlarge radius, km.
231
+ representative_spacing_km : float
232
+ ONE spacing value for the whole array (e.g.
233
+ `float(np.nanmedian(spacing_km_array))`), matching the "uniform"
234
+ convention already used elsewhere in EccoPy (see
235
+ refl_texture_1d's kernel_mode). On a genuinely non-uniform grid,
236
+ the returned pixel radius represents a DIFFERENT physical size at
237
+ points whose true local spacing differs from this representative
238
+ value -- the same caveat class_basic()'s pixel-based radii always
239
+ carried, just made explicit here instead of silent.
240
+ Returns
241
+ -------
242
+ int
243
+ round(target_km / representative_spacing_km), clamped to a minimum
244
+ of 1.
245
+
246
+ Raises
247
+ ------
248
+ ValueError
249
+ If representative_spacing_km is not a positive, finite number.
250
+ """
251
+ if not np.isfinite(representative_spacing_km) or representative_spacing_km <= 0:
252
+ raise ValueError(
253
+ f"representative_spacing_km must be a positive, finite number; "
254
+ f"got {representative_spacing_km!r}."
255
+ )
256
+ return max(1, int(round(target_km / representative_spacing_km)))
257
+
258
+
259
+ def _edge_pad_close(arr: np.ndarray, se: np.ndarray) -> np.ndarray:
260
+ """Single closing step matching MATLAB's real imclose mechanism,
261
+ found by direct comparison against MATLAB ground truth on real SPOL
262
+ data: edge-replicate the INPUT (not the already-dilated array)
263
+ before dilating, then standard dilate+erode with border_value=0,
264
+ then crop back to the original shape.
265
+
266
+ Do not substitute scipy.ndimage.binary_closing(): it applies one
267
+ global border_value across a single dilate-erode pair, which diverges
268
+ from MATLAB by thousands of pixels on real cases.
269
+ """
270
+ h0 = se.shape[0] // 2 + 1
271
+ h1 = se.shape[1] // 2 + 1
272
+ padded = np.pad(arr, ((h0, h0), (h1, h1)), mode='edge')
273
+ d = binary_dilation(padded, structure=se, border_value=0)
274
+ e = binary_erosion(d, structure=se, border_value=0)
275
+ return e[h0:-h0, h1:-h1]
276
+
277
+
278
+ def _sequential_close(arr: np.ndarray, radius: int) -> np.ndarray:
279
+ """Closing by a large disk, applied as MATLAB really does it: through
280
+ the disk's real decomposition primitives, one at a time, each via
281
+ _edge_pad_close(). This is NOT mathematically equivalent to a single
282
+ dilate-then-erode with the full disk mask near array boundaries --
283
+ that equivalence only holds in the interior, far from any edge. See
284
+ module docstring for validated accuracy."""
285
+ steps = _load_decomp(radius)
286
+ current = arr
287
+ for s in steps:
288
+ current = _edge_pad_close(current, s)
289
+ return current
290
+
291
+
292
+ # ---------------------------------------------------------------------------
293
+ # Basic classification (EccoPy-1D / EccoPy-2D)
294
+ # ---------------------------------------------------------------------------
295
+
296
+ def class_basic_isotropic(conv: np.ndarray,
297
+ strat_mixed: float,
298
+ mixed_conv: float,
299
+ enlarge_mixed: int = 0,
300
+ enlarge_conv: int = 0) -> np.ndarray:
301
+ """
302
+ Basic convective / mixed / stratiform classification for plan-view
303
+ (horizontal) data. Retained for backward compatibility and as a
304
+ simpler alternative to the clumping-based path now used by default
305
+ in eccopy2d_h.run() (see eccopy2d_h/clumping.py) -- this function is
306
+ a straight morphological threshold-and-clean approach with no
307
+ connectivity/area accounting, analogous to class_basic() but with
308
+ isotropic (disk-only) structuring since both axes are spatial here.
309
+
310
+ Carries the same two morphological conventions as class_basic():
311
+ border_value=1 on erosion, and MATLAB's exact disk shape. Both are
312
+ properties of the operation rather than of any one dataset.
313
+ Uses the same disk decomposition as class_basic()
314
+ (radius = enlarge*3 / enlarge*5), generated by eccopy.core.disk.
315
+
316
+ Parameters
317
+ ----------
318
+ conv : np.ndarray, shape (Y, X)
319
+ Convectivity field.
320
+ strat_mixed, mixed_conv : float
321
+ Convectivity thresholds.
322
+ enlarge_mixed, enlarge_conv : int
323
+ Disk radii for morphological cleanup. 0 disables cleanup beyond
324
+ basic thresholding (still removes single-pixel speckle via a
325
+ minimal disk-3 close+erode pass).
326
+
327
+ Returns
328
+ -------
329
+ result : 1=stratiform, 2=mixed, 3=convective, NaN=no data
330
+ """
331
+ conv = np.asarray(conv, dtype=float).copy()
332
+ result = np.full(conv.shape, np.nan)
333
+
334
+ mask_mixed = conv >= strat_mixed
335
+ if not mask_mixed.any():
336
+ result[~np.isnan(conv)] = 1
337
+ return result
338
+
339
+ mixed_large = binary_dilation(mask_mixed, structure=_disk(max(enlarge_mixed, 1)))
340
+ mixed_large = _sequential_close(mixed_large, max(enlarge_mixed, 1) * 3)
341
+ mixed_large[np.isnan(conv)] = 0
342
+ mixed_large = binary_fill_holes(mixed_large)
343
+ # border_value=1 (not scipy's default 0) -- see docstring above.
344
+ mixed_large_e = binary_erosion(mixed_large, structure=_disk(3), border_value=1)
345
+ if not mixed_large_e.any() and mixed_large.any():
346
+ mixed_large_e = mixed_large
347
+ mixed_large = binary_dilation(mixed_large_e, structure=_disk(3))
348
+
349
+ mask_conv = conv >= mixed_conv
350
+ conv_large = binary_dilation(mask_conv, structure=_disk(max(enlarge_conv, 1)))
351
+ conv_large = _sequential_close(conv_large, max(enlarge_conv, 1) * 5)
352
+ conv_large[np.isnan(conv)] = 0
353
+ conv_large = binary_fill_holes(conv_large)
354
+ conv_large_e = binary_erosion(conv_large, structure=_disk(3), border_value=1)
355
+ if not conv_large_e.any() and conv_large.any():
356
+ conv_large_e = conv_large
357
+ conv_large = binary_dilation(conv_large_e, structure=_disk(3))
358
+
359
+ result[conv_large] = 3
360
+ result[np.isnan(result) & mixed_large] = 2
361
+ result[np.isnan(result)] = 1
362
+ result[np.isnan(conv)] = np.nan
363
+ return result
364
+
365
+
366
+ def class_basic(conv: np.ndarray,
367
+ strat_mixed: float,
368
+ mixed_conv: float,
369
+ melt: Optional[np.ndarray] = None,
370
+ enlarge_mixed: int = 0,
371
+ enlarge_conv: int = 0) -> np.ndarray:
372
+ """
373
+ Basic convective / mixed / stratiform classification.
374
+ Port of MATLAB f_classBasic.m -- see module docstring for the
375
+ validation history of this specific function's morphological steps.
376
+
377
+ Parameters
378
+ ----------
379
+ conv : np.ndarray
380
+ Convectivity field, any shape with at least 2 dimensions.
381
+ strat_mixed, mixed_conv : float
382
+ Convectivity thresholds.
383
+ melt : np.ndarray, optional
384
+ Melting-layer height/flag field, same shape as conv. If provided,
385
+ enables the "rain below melting layer" override check.
386
+ Thresholded at `meltArea < 20` with a sentinel of 10,
387
+ matching f_classBasic.m.
388
+ Returns
389
+ -------
390
+ result : 1=stratiform, 2=mixed, 3=convective, NaN=no data
391
+ """
392
+ conv = conv.astype(float).copy()
393
+ result = np.full(conv.shape, np.nan)
394
+
395
+ mask_mixed_orig = conv >= strat_mixed
396
+ if not mask_mixed_orig.any():
397
+ result[~np.isnan(conv)] = 1
398
+ return result
399
+
400
+ mask_mixed = mask_mixed_orig.copy()
401
+ conv[(mask_mixed == 0) & mask_mixed_orig] = 0
402
+
403
+ # Rain-below-melt check.
404
+ # MATLAB's `checkCol(1:firstInd)=1` is inclusive of firstInd, so
405
+ # the Python slice must be `check_col[:first_ind + 1]`. Excluding
406
+ # it drops the whole column's contribution whenever the
407
+ # convectivity value at the melt-crossing pixel is NaN.
408
+ if melt is not None:
409
+ melt = melt.astype(float).copy()
410
+ labeled_mixed, n_mixed = label(mask_mixed, structure=_CONN8)
411
+ for ii in range(1, n_mixed + 1):
412
+ pix_flat = np.where((labeled_mixed == ii).ravel())[0]
413
+ melt_area = melt.ravel()[pix_flat]
414
+ below_frac = np.sum(melt_area < 20) / max(len(pix_flat), 1)
415
+ if below_frac <= 0.8:
416
+ continue
417
+
418
+ rows, cols = np.unravel_index(pix_flat, conv.shape)
419
+ ucols = np.unique(cols)
420
+ conv_cols = conv[:, ucols]
421
+ melt_cols = melt[:, ucols]
422
+ this_mat = np.zeros(conv.shape)
423
+ this_mat.ravel()[pix_flat] = 1
424
+ this_cols = this_mat[:, ucols]
425
+
426
+ conv_cols = conv_cols[::-1, :]
427
+ melt_cols = melt_cols[::-1, :]
428
+ this_cols = this_cols[::-1, :]
429
+
430
+ check_cols = np.full(melt_cols.shape, np.nan)
431
+ for jj in range(len(ucols)):
432
+ melt_col = melt_cols[:, jj].copy()
433
+ check_col = conv_cols[:, jj].copy()
434
+ this_col = this_cols[:, jj]
435
+ first_valid = np.where(~np.isnan(melt_col))[0]
436
+ if len(first_valid) == 0:
437
+ continue
438
+ melt_col[: first_valid[0] + 1] = 10
439
+ above_melt = np.where(melt_col >= 20)[0]
440
+ if len(above_melt) == 0:
441
+ continue
442
+ first_ind = above_melt[0]
443
+ check_col[:first_ind + 1] = 1
444
+ nan_inds = np.where(np.isnan(check_col))[0]
445
+ last_ind = nan_inds[0] - 1 if len(nan_inds) > 0 else len(melt_col) - 1
446
+ last_mixed = np.where(this_col == 1)[0]
447
+ if len(last_mixed) == 0:
448
+ continue
449
+ last_mixed_idx = last_mixed[-1]
450
+ test_conv = conv_cols[:, jj].copy()
451
+ test_conv[:last_mixed_idx + 1] = 1
452
+ first_nan2 = np.where(np.isnan(test_conv))[0]
453
+ if len(first_nan2) > 0 and last_ind > first_nan2[0]:
454
+ last_ind = max(first_ind, first_nan2[0])
455
+ check_cols[first_ind: last_ind + 1, jj] = (
456
+ conv_cols[first_ind: last_ind + 1, jj]
457
+ )
458
+
459
+ n_valid_check = np.sum(~np.isnan(check_cols))
460
+ strat_perc = np.sum(check_cols < strat_mixed) / max(n_valid_check, 1)
461
+ med_thick = np.median(np.sum(~np.isnan(check_cols), axis=0))
462
+ if strat_perc > 0.8 and med_thick > 5:
463
+ mask_mixed.ravel()[pix_flat] = 0
464
+ conv.ravel()[pix_flat] = 0
465
+
466
+ hor_large = binary_dilation(mask_mixed, structure=_line_h(100))
467
+
468
+ # --- Mixed region: enlarge, close, fill, erode ---
469
+ mixed_large1 = binary_dilation(mask_mixed, structure=_disk(enlarge_mixed))
470
+ mixed_large = _sequential_close(mixed_large1, enlarge_mixed * 3)
471
+ if not mixed_large.any() and mixed_large1.any():
472
+ mixed_large = mixed_large1
473
+ mixed_large[np.isnan(conv)] = 0
474
+ mixed_large = binary_fill_holes(mixed_large)
475
+ # border_value=1 here (not scipy's default 0) is required for this
476
+ # erosion to be mathematically extensive relative to its input --
477
+ # see module docstring / border_value fix history.
478
+ mixed_large_e = binary_erosion(mixed_large, structure=_disk(3), border_value=1)
479
+ if not mixed_large_e.any() and mixed_large.any():
480
+ mixed_large_e = mixed_large
481
+ mixed_large = mixed_large_e
482
+
483
+ for col_idx in np.where(mixed_large.any(axis=0))[0]:
484
+ col = mixed_large[:, col_idx].copy()
485
+ hor_col = hor_large[:, col_idx]
486
+ lbl_col, n_pieces = label(col)
487
+ if n_pieces > 1:
488
+ for jj in range(1, n_pieces + 1):
489
+ piece = lbl_col == jj
490
+ if not hor_col[piece].any():
491
+ col[piece] = 0
492
+ mixed_large[:, col_idx] = col
493
+
494
+ mixed_large = binary_dilation(mixed_large, structure=_disk(3))
495
+
496
+ # --- Convective region: enlarge, close, fill, erode ---
497
+ mask_conv = conv >= mixed_conv
498
+ hor_large2 = binary_dilation(mask_conv, structure=_line_h(100))
499
+
500
+ conv_large1 = binary_dilation(mask_conv, structure=_disk(enlarge_conv))
501
+ conv_large = _sequential_close(conv_large1, enlarge_conv * 5)
502
+ if not conv_large.any() and conv_large1.any():
503
+ conv_large = conv_large1
504
+ conv_large[np.isnan(conv)] = 0
505
+ conv_large = binary_fill_holes(conv_large)
506
+ conv_large_e = binary_erosion(conv_large, structure=_disk(3), border_value=1)
507
+ if not conv_large_e.any() and conv_large.any():
508
+ conv_large_e = conv_large
509
+ conv_large = conv_large_e
510
+
511
+ for col_idx in np.where(conv_large.any(axis=0))[0]:
512
+ col = conv_large[:, col_idx].copy()
513
+ hor_col = hor_large2[:, col_idx]
514
+ lbl_col, n_pieces = label(col)
515
+ if n_pieces > 1:
516
+ for jj in range(1, n_pieces + 1):
517
+ piece = lbl_col == jj
518
+ if not hor_col[piece].any():
519
+ col[piece] = 0
520
+ conv_large[:, col_idx] = col
521
+
522
+ conv_large = binary_dilation(conv_large, structure=_disk(3))
523
+
524
+ result[conv_large] = 3
525
+ result[np.isnan(result) & mixed_large] = 2
526
+ result[np.isnan(result)] = 1
527
+ result[np.isnan(conv)] = np.nan
528
+ return result
529
+
530
+
531
+ # ---------------------------------------------------------------------------
532
+ # 1-D minimum-length clump filter (EccoPy-1D)
533
+ # ---------------------------------------------------------------------------
534
+ #
535
+ # There is no MATLAB or C++ "ECCO-1D" reference to port this from -- 1-D
536
+ # time-series classification has no upstream ground truth. This is a new
537
+ # EccoPy-1D-only addition, designed (not ported) to address one specific,
538
+ # named risk: class_basic()'s morphological pipeline already suppresses
539
+ # sub-structuring-element speckle via its erode/dilate sequence, but a
540
+ # convective run that survives that pipeline can still be physically very
541
+ # brief -- e.g. a single erroneous high-convectivity sample sitting right
542
+ # at the edge of what enlarge_conv's disk width lets through. The 3-D path
543
+ # (eccopy3d/clumping.py) guards against the volumetric equivalent of this
544
+ # by rejecting any clump with volume_km3 < min_valid_volume_for_convective
545
+ # BEFORE it can be labeled Convective -- see _clump_category()'s first
546
+ # check, which demotes undersized clumps to MIXED rather than dropping
547
+ # them to Stratiform (an undersized-but-real convective signature is
548
+ # "uncertain", not "definitely not convective"). filter_short_convective_
549
+ # runs_1d() is the 1-D analogue of that same check: physical LENGTH
550
+ # (time or distance, matching whatever unit the caller's coords are in)
551
+ # stands in for volume, since a 1-D run has no other size to measure.
552
+ #
553
+ # Deliberately NOT included here: the 3-D path's two-stage dual-threshold
554
+ # SPLITTING logic (ClumpingDualThresh -- see eccopy3d/clumping.py module
555
+ # docstring), which exists to re-separate two genuine, distinct storm
556
+ # cores that got morphologically bridged into one clump. A 1-D analogue
557
+ # (secondary-threshold local-maxima detection + regrow) is possible but
558
+ # is a separate, nontrivial design decision -- deferred pending input on
559
+ # whether EccoPy-1D actually needs to distinguish "one brief burst" from
560
+ # "two adjacent bursts that got closed together" for the intended
561
+ # time-series use case, versus just filtering brief/erroneous ones out.
562
+
563
+
564
+ def filter_short_convective_runs_1d(echo_type: np.ndarray,
565
+ spacing_base: np.ndarray,
566
+ min_length_base: float,
567
+ demote_to: int = CATEGORY_MIXED,
568
+ target_code: int = 3) -> np.ndarray:
569
+ """
570
+ Demote contiguous convective runs shorter than `min_length_base` to
571
+ `demote_to` (Mixed by default -- matching _clump_category()'s
572
+ treatment of undersized 3-D clumps, not Stratiform).
573
+
574
+ Parameters
575
+ ----------
576
+ echo_type : np.ndarray, shape (N,)
577
+ Output of class_basic() (already squeezed back to 1-D by the
578
+ eccopy1d caller): 1=stratiform, 2=mixed, 3=convective, NaN=missing.
579
+ spacing_base : np.ndarray, shape (N,)
580
+ Local point-to-point spacing, in the SAME base unit as
581
+ `min_length_base` (both metres/both seconds/both raw pixel
582
+ counts -- caller's responsibility to match them; see
583
+ eccopy1d.run()'s handling of WindowSpec base units for the
584
+ pattern used to guarantee this).
585
+ min_length_base : float
586
+ Minimum physical (or pixel-count) length a convective run must
587
+ span to remain Convective. A run's length is the sum of
588
+ spacing_base over every point in the run -- see Notes.
589
+ demote_to : int
590
+ Echo code to assign to undersized runs. Default CATEGORY_MIXED.
591
+ target_code : int
592
+ Echo code identifying which runs to check. Default 3
593
+ (Convective) -- the only code this is meaningful for currently,
594
+ but left as a parameter rather than hardcoded.
595
+
596
+ Returns
597
+ -------
598
+ result : np.ndarray, shape (N,)
599
+ Copy of echo_type with undersized target_code runs demoted.
600
+
601
+ Notes
602
+ -----
603
+ A run's length is computed as the sum of spacing_base over the run's
604
+ own points, which slightly OVER-counts the run's true footprint (the
605
+ last point's spacing value describes the gap to the point AFTER the
606
+ run, not a gap the run itself occupies) -- this is a deliberate,
607
+ conservative choice: it means a run is very slightly more likely to
608
+ survive the filter than a stricter definition would allow, rather
609
+ than less likely, which matters more given False Elimination of a
610
+ real convective signature is a worse failure than the reverse.
611
+ """
612
+ result = np.array(echo_type, dtype=float, copy=True)
613
+ if min_length_base is None or min_length_base <= 0:
614
+ return result
615
+
616
+ mask = (result == target_code)
617
+ if not mask.any():
618
+ return result
619
+
620
+ labeled, n_runs = label(mask) # default structure: 1-D adjacency
621
+ spacing_base = np.asarray(spacing_base, dtype=float)
622
+
623
+ for ii in range(1, n_runs + 1):
624
+ run = labeled == ii
625
+ run_length = float(np.nansum(spacing_base[run]))
626
+ if run_length < min_length_base:
627
+ result[run] = demote_to
628
+
629
+ return result
630
+
631
+
632
+ # ---------------------------------------------------------------------------
633
+ # 2-D sub-classification (EccoPy-1D / EccoPy-2D)
634
+ # ---------------------------------------------------------------------------
635
+
636
+ def class_sub_2d(class_in: np.ndarray,
637
+ height: np.ndarray,
638
+ topo,
639
+ melt: np.ndarray,
640
+ temp: np.ndarray,
641
+ elev: Optional[np.ndarray] = None,
642
+ first_row: Optional[int] = None,
643
+ surf_alt_lim: float = 0.0) -> np.ndarray:
644
+ """
645
+ Sub-classification into echo type codes. Port of f_classSub.m.
646
+
647
+ Non-uniform grids: unlike class_basic()
648
+ /class_basic_isotropic(), this function has NO pixel-radius structuring
649
+ elements and never touches a spacing array at all -- every threshold
650
+ here (melt=15, temp=-25 C, surf_alt_lim in metres) is compared
651
+ directly against physical field VALUES at each point independently.
652
+ So class_sub_2d() is already fully non-uniform-grid-safe; the "pixel
653
+ counts, not physical units" caveat documented at the top of this
654
+ module applies only to the basic-classification morphology, not to
655
+ sub-classification.
656
+
657
+ *** API CHANGE from the previous class_sub_2d ***: `height` and
658
+ `temp` are NOT alternatives with a fallback between them. The real
659
+ algorithm requires `height` (for AGL / near-surface tests, and to
660
+ force-correct `melt`/`temp` near the surface) together with BOTH
661
+ `melt` and `temp`. `melt` is the primary signal for shallow/low
662
+ classification; `temp` only distinguishes mid from deep/high. All
663
+ three are required together; f_classSub.m has no path that takes a
664
+ subset.
665
+
666
+ Parameters
667
+ ----------
668
+ class_in : np.ndarray, shape (Z, X)
669
+ Output of class_basic(): 1=stratiform, 2=mixed, 3=convective.
670
+ height : np.ndarray, shape (Z, X)
671
+ Height field, METRES (MATLAB's `asl`). Note: this differs from
672
+ this package's usual km convention at the public API boundary --
673
+ follow the existing eccopy2d_v.run() pattern of converting
674
+ km->m once at the boundary before calling this function.
675
+ topo : np.ndarray or scalar, broadcastable to (Z, X)
676
+ Terrain height / beam-height correction, METRES.
677
+ melt : np.ndarray, shape (Z, X)
678
+ Melting-layer field (same convention as class_basic's `melt`
679
+ parameter -- NOT optional here, unlike in the previous version
680
+ of this function).
681
+ temp : np.ndarray, shape (Z, X)
682
+ Temperature field, deg C.
683
+ elev, first_row : optional
684
+ Near-aircraft override logic (rarely needed) -- see f_classSub.m.
685
+ surf_alt_lim : float, metres
686
+
687
+ Returns
688
+ -------
689
+ result : np.ndarray, shape (Z, X)
690
+ Echo type codes: 14/16/18 (stratiform low/mid/high), 25 (mixed),
691
+ 30 (near-aircraft override), 32/34/36/38 (convective
692
+ elevated/shallow/mid/deep).
693
+ """
694
+ class_in = np.asarray(class_in, dtype=float)
695
+ height = np.asarray(height, dtype=float)
696
+ melt_orig = np.asarray(melt, dtype=float)
697
+ temp = np.asarray(temp, dtype=float).copy() # mutated below; don't touch caller's array
698
+
699
+ topo_arr = np.asarray(topo, dtype=float)
700
+ if topo_arr.shape != height.shape:
701
+ topo_arr = np.broadcast_to(topo_arr, height.shape)
702
+
703
+ result = np.full(class_in.shape, np.nan)
704
+
705
+ conv_mask = (class_in == 3)
706
+ labeled_conv, n_conv = label(conv_mask, structure=_CONN8)
707
+
708
+ dist_asl_topo = height - topo_arr
709
+
710
+ melt = melt_orig.copy()
711
+ melt[dist_asl_topo < 2000] = 9
712
+ melt[np.isnan(melt_orig)] = np.nan
713
+ temp[(dist_asl_topo < 4000) & (temp < -25)] = -25
714
+
715
+ for ii in range(1, n_conv + 1):
716
+ pix_flat = np.where((labeled_conv == ii).ravel())[0]
717
+ rows, cols = np.unravel_index(pix_flat, class_in.shape)
718
+
719
+ if elev is not None and first_row is not None:
720
+ plane_mask = rows == first_row
721
+ plane_pix = int(np.sum(plane_mask))
722
+ alt_diff = dist_asl_topo.ravel()[pix_flat]
723
+ alt_plane_pix = alt_diff[plane_mask]
724
+ cols_first = cols[plane_mask]
725
+ elev_plane_pix = elev[cols_first]
726
+ alt_low = int(np.sum((alt_plane_pix < 500) & (elev_plane_pix > 0)))
727
+ plane_pix = plane_pix - alt_low
728
+ else:
729
+ plane_pix = 0
730
+
731
+ asl_area = dist_asl_topo.ravel()[pix_flat]
732
+ near_surf_pix = int(np.sum(asl_area < 500 + surf_alt_lim))
733
+
734
+ if near_surf_pix == 0:
735
+ if elev is not None and plane_pix > 10 and np.nanmedian(elev[cols]) > 0:
736
+ code = CATEGORY_CONVECTIVE
737
+ else:
738
+ code = CATEGORY_CONVECTIVE_ELEVATED
739
+ else:
740
+ melt_max = np.nanmax(melt.ravel()[pix_flat])
741
+ if melt_max < 15:
742
+ code = CATEGORY_CONVECTIVE if plane_pix > 10 else CATEGORY_CONVECTIVE_SHALLOW
743
+ else:
744
+ min_temp = np.nanmin(temp.ravel()[pix_flat])
745
+ if min_temp >= -25:
746
+ code = CATEGORY_CONVECTIVE if plane_pix > 10 else CATEGORY_CONVECTIVE_MID
747
+ else:
748
+ if elev is not None and plane_pix > 10 and np.nanmedian(elev[cols]) > 0:
749
+ code = CATEGORY_CONVECTIVE
750
+ else:
751
+ code = CATEGORY_CONVECTIVE_DEEP
752
+ result.ravel()[pix_flat] = code
753
+
754
+ result[(class_in == 1) & (melt < 15)] = CATEGORY_STRATIFORM_LOW
755
+ result[(class_in == 1) & (melt > 15) & (temp >= -25)] = CATEGORY_STRATIFORM_MID
756
+ result[(class_in == 1) & (melt > 15) & (temp < -25)] = CATEGORY_STRATIFORM_HIGH
757
+
758
+ result[class_in == 2] = CATEGORY_MIXED
759
+
760
+ return result
761
+
762
+
763
+ def assign_echo_type_2d(convectivity: np.ndarray,
764
+ clumps: list,
765
+ max_conv_for_strat: float) -> np.ndarray:
766
+ """
767
+ Assign basic (1/2/3) echo type codes for EccoPy-2D-H from a list of
768
+ 2-D clumps (see eccopy2d_h/clumping.py:find_clumps_2d()).
769
+
770
+ 2-D analogue of set_echo_type_3d()'s two-pass structure, simplified:
771
+ there is no height/temp axis for a single horizontal level, so there
772
+ is no Pass-1 shallow/mid/deep/elevated sub-typing -- every clump
773
+ pixel is simply CATEGORY code 3 (Convective), and remaining pixels
774
+ follow the same convectivity-threshold Pass-2 logic as class_basic /
775
+ class_basic_isotropic (which is why this returns plain 1/2/3 codes,
776
+ not the extended 14/16/18/25/32/34/36/38 set that set_echo_type_3d
777
+ can produce -- matching EccoPy-2D-H's documented "no sub-classification
778
+ without depth" contract).
779
+
780
+ Parameters
781
+ ----------
782
+ convectivity : np.ndarray, shape (Y, X)
783
+ clumps : list of dicts, each with an 'index' key -- a (iy_arr, ix_arr)
784
+ tuple of integer index arrays (see find_clumps_2d()).
785
+ max_conv_for_strat : float
786
+ Convectivity threshold above which a non-clump point is Mixed
787
+ rather than Stratiform (same role as class_basic's strat_mixed).
788
+
789
+ Returns
790
+ -------
791
+ echo_type : np.ndarray, shape (Y, X)
792
+ 1=Stratiform, 2=Mixed, 3=Convective, NaN=missing/no data.
793
+ """
794
+ result = np.full(convectivity.shape, np.nan)
795
+
796
+ # Pass 1 - clump pixels are Convective, unconditionally (any clump
797
+ # that reached this function already passed find_clumps_2d()'s own
798
+ # area filtering -- see that module for the filtering logic).
799
+ for clump in clumps:
800
+ result[clump['index']] = 3
801
+
802
+ # Pass 2 - stratiform/mixed for everything else with valid convectivity
803
+ unassigned = np.isnan(result)
804
+ has_conv = unassigned & ~np.isnan(convectivity)
805
+ mixed_mask = has_conv & (convectivity > max_conv_for_strat)
806
+ result[mixed_mask] = 2
807
+ result[has_conv & ~mixed_mask] = 1
808
+
809
+ return result
810
+
811
+
812
+ # ---------------------------------------------------------------------------
813
+ # 3-D echo type assignment (EccoPy-3D)
814
+ # Port of ConvStratFinder::_setEchoType3D() + StormClump::setEchoType()
815
+ # ---------------------------------------------------------------------------
816
+
817
+ def set_echo_type_3d(convectivity: np.ndarray,
818
+ clumps: list,
819
+ height_km: Optional[np.ndarray] = None,
820
+ temp: Optional[np.ndarray] = None,
821
+ shallow_threshold_ht: float = 4.5,
822
+ deep_threshold_ht: float = 9.0,
823
+ shallow_threshold_temp: float = 0.0,
824
+ deep_threshold_temp: float = -12.0,
825
+ terrain_ht_km: Optional[np.ndarray] = None,
826
+ min_ht_agl_for_mid: float = 2.0,
827
+ min_ht_agl_for_deep: float = 4.0,
828
+ max_conv_for_strat: float = 0.4,
829
+ min_conv_for_conv: float = 0.5,
830
+ min_vol_km3: float = 20.0,
831
+ min_vert_extent_km: float = 1.0,
832
+ min_conv_frac_deep: float = 0.05,
833
+ min_conv_frac_shallow: float = 0.95,
834
+ max_shallow_frac_elevated: float = 0.05,
835
+ max_deep_frac_elevated: float = 0.25,
836
+ min_strat_frac_strat_below: float = 0.9) -> np.ndarray:
837
+ """
838
+ Assign 3-D echo type codes.
839
+
840
+ *** WARNING: this function has NOT been re-validated against this
841
+ session's findings (border_value fix, exact disk masks, sequential
842
+ closing mechanism). It still uses height-threshold logic for
843
+ shallow/mid/deep, which does not apply to the 2-D case
844
+ (class_sub_2d) -- the real algorithm there uses melt/temp instead.
845
+ Whether the 3-D C++ reference (ConvStratFinder) genuinely differs
846
+ from the 2-D MATLAB reference (f_classSub.m) in this respect, or
847
+ whether this function has the same undiscovered bug, has not been
848
+ checked. Do not treat this function as validated. ***
849
+
850
+ Exact port of ConvStratFinder::_setEchoType3D() two-pass structure:
851
+
852
+ Pass 1: For each clump, call _clump_category() - sets convective pixels.
853
+ Pass 2: Loop all remaining pixels:
854
+ - conv missing or 0 → skip (stays MISSING)
855
+ - conv > max_conv_for_strat → MIXED
856
+ - conv <= max_conv_for_strat → low/mid/high stratiform code,
857
+ based on EITHER height_km OR temp (whichever is supplied)
858
+
859
+ If both height_km and temp are None, every non-clump, non-mixed point
860
+ with valid convectivity is simply MIXED-or-missing - pass a basic
861
+ classification mode (CATEGORY_MIXED only, no low/mid/high distinction)
862
+ by leaving both arguments unset; clump pixels are still differentiated
863
+ into shallow/mid/deep/elevated.
864
+
865
+ Parameters
866
+ ----------
867
+ convectivity : np.ndarray, shape (nz, ny, nx)
868
+ clumps : list of dicts (see find_clumps_3d / _clump_category)
869
+ height_km : np.ndarray, shape (nz, ny, nx), optional
870
+ Height field, km MSL.
871
+ temp : np.ndarray, shape (nz, ny, nx), optional
872
+ Temperature field, °C.
873
+ shallow_threshold_ht, deep_threshold_ht : float, km
874
+ shallow_threshold_temp, deep_threshold_temp : float, °C
875
+ terrain_ht_km : np.ndarray, shape (ny, nx), optional
876
+ min_ht_agl_for_mid, min_ht_agl_for_deep : float, km
877
+ max_conv_for_strat, min_conv_for_conv, min_vol_km3,
878
+ min_vert_extent_km, min_conv_frac_deep, min_conv_frac_shallow,
879
+ max_shallow_frac_elevated, max_deep_frac_elevated,
880
+ min_strat_frac_strat_below : float
881
+
882
+ Returns
883
+ -------
884
+ echo_type : np.ndarray, shape (nz, ny, nx), int16
885
+ """
886
+ nz, ny, nx = convectivity.shape
887
+ echo_type = np.zeros((nz, ny, nx), dtype=np.int16)
888
+
889
+ use_height = height_km is not None
890
+ use_temp = (not use_height) and (temp is not None)
891
+
892
+ if use_height:
893
+ height_km = np.asarray(height_km, dtype=float)
894
+ shallow_bnd = np.full((ny, nx), shallow_threshold_ht)
895
+ deep_bnd = np.full((ny, nx), deep_threshold_ht)
896
+ if terrain_ht_km is not None:
897
+ terrain_ht_km = np.asarray(terrain_ht_km, dtype=float)
898
+ shallow_bnd = np.maximum(shallow_bnd, terrain_ht_km + min_ht_agl_for_mid)
899
+ deep_bnd = np.maximum(deep_bnd, terrain_ht_km + min_ht_agl_for_deep)
900
+ elif use_temp:
901
+ temp = np.asarray(temp, dtype=float)
902
+
903
+ # Pass 1 - assign convective pixels via clumps
904
+ for clump in clumps:
905
+ category = _clump_category(
906
+ clump, min_vol_km3, min_vert_extent_km,
907
+ min_conv_frac_deep, min_conv_frac_shallow,
908
+ max_shallow_frac_elevated, max_deep_frac_elevated,
909
+ min_strat_frac_strat_below,
910
+ convectivity, min_conv_for_conv,
911
+ )
912
+ echo_type[clump['index']] = category
913
+
914
+ # Pass 2 - stratiform/mixed for remaining points
915
+ unassigned = (echo_type == CATEGORY_MISSING)
916
+ has_conv = unassigned & ~np.isnan(convectivity) & (convectivity != 0)
917
+
918
+ mixed_mask = has_conv & (convectivity > max_conv_for_strat)
919
+ echo_type[mixed_mask] = CATEGORY_MIXED
920
+
921
+ strat_mask = has_conv & ~mixed_mask
922
+ if use_height:
923
+ ht_broadcast = height_km
924
+ sh_b = shallow_bnd[np.newaxis, :, :]
925
+ dp_b = deep_bnd[np.newaxis, :, :]
926
+ echo_type[strat_mask & (ht_broadcast <= sh_b)] = CATEGORY_STRATIFORM_LOW
927
+ echo_type[strat_mask & (ht_broadcast >= dp_b)] = CATEGORY_STRATIFORM_HIGH
928
+ echo_type[strat_mask & (ht_broadcast > sh_b) & (ht_broadcast < dp_b)] = CATEGORY_STRATIFORM_MID
929
+ elif use_temp:
930
+ echo_type[strat_mask & (temp >= shallow_threshold_temp)] = CATEGORY_STRATIFORM_LOW
931
+ echo_type[strat_mask & (temp < shallow_threshold_temp)
932
+ & (temp >= deep_threshold_temp)] = CATEGORY_STRATIFORM_MID
933
+ echo_type[strat_mask & (temp < deep_threshold_temp)] = CATEGORY_STRATIFORM_HIGH
934
+ else:
935
+ echo_type[strat_mask] = CATEGORY_MIXED
936
+
937
+ return echo_type
938
+
939
+
940
+ def _clump_category(clump: dict,
941
+ min_vol_km3: float,
942
+ min_vert_extent_km: float,
943
+ min_conv_frac_deep: float,
944
+ min_conv_frac_shallow: float,
945
+ max_shallow_frac_elevated: float,
946
+ max_deep_frac_elevated: float,
947
+ min_strat_frac_strat_below: float,
948
+ convectivity: np.ndarray,
949
+ min_conv_for_conv: float) -> int:
950
+ """
951
+ Determine echo type category for one clump.
952
+ Port of ConvStratFinder::StormClump::setEchoType().
953
+
954
+ Decision tree (matching C++ exactly):
955
+ 1. vol < min_vol_km3 OR vert_extent < min_vert_extent → MIXED
956
+ 2. fracShallow < max_shallow_frac_elevated
957
+ AND stratiformBelow()
958
+ → if fracDeep < max_deep_frac_elevated → ELEVATED
959
+ → else → MIXED
960
+ 3. fracShallow > min_conv_frac_shallow → SHALLOW
961
+ 4. fracDeep > min_conv_frac_deep → DEEP
962
+ 5. else → MID
963
+ """
964
+ if (clump['volume_km3'] < min_vol_km3 or
965
+ clump['vert_extent_km'] < min_vert_extent_km):
966
+ return CATEGORY_MIXED
967
+
968
+ n_total = max(clump['n_pts_total'], 1)
969
+ frac_shallow = clump['n_pts_shallow'] / n_total
970
+ frac_deep = clump['n_pts_deep'] / n_total
971
+
972
+ if frac_shallow < max_shallow_frac_elevated:
973
+ if _strat_below(clump['index'], convectivity, min_conv_for_conv,
974
+ min_strat_frac_strat_below):
975
+ if frac_deep < max_deep_frac_elevated:
976
+ return CATEGORY_CONVECTIVE_ELEVATED
977
+ else:
978
+ return CATEGORY_MIXED
979
+
980
+ if frac_shallow > min_conv_frac_shallow:
981
+ return CATEGORY_CONVECTIVE_SHALLOW
982
+ if frac_deep > min_conv_frac_deep:
983
+ return CATEGORY_CONVECTIVE_DEEP
984
+ return CATEGORY_CONVECTIVE_MID
985
+
986
+
987
+ def _strat_below(index: Tuple[np.ndarray, np.ndarray, np.ndarray],
988
+ convectivity: np.ndarray,
989
+ min_conv_for_conv: float,
990
+ min_strat_frac: float) -> bool:
991
+ """
992
+ Check for stratiform echo in the plane IMMEDIATELY below each clump pixel.
993
+
994
+ Port of ConvStratFinder::StormClump::stratiformBelow():
995
+ - If any clump pixel is at iz==0, return False immediately.
996
+ - For each (iz, iy, ix) in clump, look at convectivity[iz-1, iy, ix].
997
+ - missing → nMiss++
998
+ - < min_conv_for_conv → nStrat++
999
+ - fractionStrat = nStrat / (nMiss + nStrat) > min_strat_frac → True
1000
+
1001
+ Parameters
1002
+ ----------
1003
+ index : tuple of (iz_arr, iy_arr, ix_arr) - matches clump['index']
1004
+ from find_clumps_3d(), shape (Z, Y, X) convention.
1005
+ convectivity : np.ndarray, shape (Z, Y, X)
1006
+
1007
+ `index` is a (Z, Y, X)-ordered tuple from np.where(); the vertical
1008
+ step decrements iz_arr, the first axis.
1009
+ """
1010
+ iz_arr, iy_arr, ix_arr = index
1011
+ if len(iz_arr) == 0:
1012
+ return False
1013
+ if iz_arr.min() == 0:
1014
+ return False
1015
+
1016
+ below = convectivity[iz_arr - 1, iy_arr, ix_arr]
1017
+ n_miss = int(np.sum(np.isnan(below)))
1018
+ n_strat = int(np.sum(below < min_conv_for_conv)) # NaN-safe: NaN < x is False
1019
+
1020
+ n_total = n_miss + n_strat
1021
+ if n_total == 0:
1022
+ return False
1023
+ return (n_strat / n_total) > min_strat_frac