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