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.
- eccopy/__init__.py +46 -0
- eccopy/core/__init__.py +55 -0
- eccopy/core/classification.py +1023 -0
- eccopy/core/colormaps.py +267 -0
- eccopy/core/convectivity.py +43 -0
- eccopy/core/coords.py +245 -0
- eccopy/core/data/disk_decomp/disk_decomp_r15_info.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r15_step1.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r15_step2.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r15_step3.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r15_step4.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r15_step5.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r15_step6.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r25_info.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r25_step1.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r25_step2.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r25_step3.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r25_step4.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r25_step5.mat +0 -0
- eccopy/core/data/disk_decomp/disk_decomp_r25_step6.mat +0 -0
- eccopy/core/data/disk_strels/disk_strel_r15.mat +0 -0
- eccopy/core/data/disk_strels/disk_strel_r25.mat +0 -0
- eccopy/core/data/disk_strels/disk_strel_r3.mat +0 -0
- eccopy/core/data/disk_strels/disk_strel_r5.mat +0 -0
- eccopy/core/debug.py +493 -0
- eccopy/core/disk.py +178 -0
- eccopy/core/temperature.py +250 -0
- eccopy/core/texture.py +1398 -0
- eccopy/eccopy1d/__init__.py +2 -0
- eccopy/eccopy1d/classify.py +273 -0
- eccopy/eccopy2d_h/__init__.py +2 -0
- eccopy/eccopy2d_h/classify.py +281 -0
- eccopy/eccopy2d_h/clumping.py +265 -0
- eccopy/eccopy2d_v/__init__.py +2 -0
- eccopy/eccopy2d_v/classify.py +288 -0
- eccopy/eccopy3d/__init__.py +2 -0
- eccopy/eccopy3d/classify.py +421 -0
- eccopy/eccopy3d/clumping.py +477 -0
- eccopy/params/__init__.py +6 -0
- eccopy/params/classification_params.py +151 -0
- eccopy/params/texture_params.py +66 -0
- eccopy/params/vertical_params.py +54 -0
- eccopy/params/window.py +141 -0
- eccopy/stats/__init__.py +56 -0
- eccopy/stats/basic_stats.py +370 -0
- eccopy/tests/__init__.py +0 -0
- eccopy/tests/_reference_impls/__init__.py +0 -0
- eccopy/tests/_reference_impls/isotherm_height_reference.py +54 -0
- eccopy/tests/_reference_impls/sliding_texture_reference.py +77 -0
- eccopy/tests/_reference_impls/texture_2d_reference.py +309 -0
- eccopy/tests/test_classification_1d_filter.py +151 -0
- eccopy/tests/test_classification_rain_below_melt.py +130 -0
- eccopy/tests/test_colormaps.py +213 -0
- eccopy/tests/test_coords.py +127 -0
- eccopy/tests/test_debug.py +226 -0
- eccopy/tests/test_disk_generator.py +82 -0
- eccopy/tests/test_eccopy1d.py +209 -0
- eccopy/tests/test_eccopy2d_h.py +185 -0
- eccopy/tests/test_eccopy2d_h_clumping.py +105 -0
- eccopy/tests/test_eccopy2d_v.py +359 -0
- eccopy/tests/test_eccopy3d.py +282 -0
- eccopy/tests/test_examples.py +84 -0
- eccopy/tests/test_min_valid_dbz.py +144 -0
- eccopy/tests/test_notebooks.py +111 -0
- eccopy/tests/test_numba_cross_validation.py +331 -0
- eccopy/tests/test_packaging.py +144 -0
- eccopy/tests/test_refl_texture_1d.py +167 -0
- eccopy/tests/test_stats.py +117 -0
- eccopy/tests/test_stats_sentinel.py +74 -0
- eccopy/tests/test_temperature.py +207 -0
- eccopy/tests/test_texture_kernel_modes.py +82 -0
- eccopy/tests/test_texture_params_implemented.py +148 -0
- eccopy/tests/test_vert_levels_type.py +180 -0
- eccopy/tests/test_window.py +80 -0
- eccopy-1.0.0.dist-info/METADATA +420 -0
- eccopy-1.0.0.dist-info/RECORD +79 -0
- eccopy-1.0.0.dist-info/WHEEL +5 -0
- eccopy-1.0.0.dist-info/licenses/LICENSE +39 -0
- 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
|