Echo Products

EchoProductsParameters

Configuration for the post-gridding echo products — fuzzy hydrometeor identification (HID/FHC) and polarimetric rain rate — applied to the gridded radar variables (the beam-power-weighted averages), loaded from the optional [echo] block. Both algorithms are CSURadarTools ports ([`csufhcsummer](@ref), [calcblendedraintropical`](@ref)).

Fields

• enabled::Bool: master switch; when false the gridding drivers skip echo products entirely.
• band::String: radar frequency band ("S", "C", "X") selecting both the FHC membership functions and the rain-rate coefficients.
• compute_fhc::Bool: write the hydrometeor classification field.
• compute_blended_rain::Bool: write the blended rain-rate field.
• rain_components::Vector{String}: which individual rain components to also write, any subset of RATE_Z, RATE_Z_CONV, RATE_Z_STRAT, RATE_KDP, RATE_Z_ZDR, RATE_KDP_ZDR. These are computed directly from the gridded variables and are available even when compute_blended_rain is false — useful for visualization and as fallbacks when blended inputs (e.g. Kdp) are missing/noisy.
• dbz_field/zdr_field/kdp_field/rhohv_field/ldr_field::String: input field names to read from the grid; ldr_field="" disables LDR.
• fhc_method::Symbol: :hybrid (default) or :linear.
• use_temp::Bool: include temperature in the FHC.
• temp_source::Symbol: where temperature comes from — :profile (the temperature T(z) profile, default), :field (a gridded temperature field, temp_field), or :reference_state (future Springsteel reference state; currently errors at runtime).
• temp_field::String: gridded temperature field name used when temp_source = :field (default "TEMP_FOR_PID").
• temp_field_units::String: units of temp_field, "C" (default) or "K" (converted to °C internally; the FHC works in °C).
• height_field::String: name of a gridded beam-height field (e.g. a field tagged beam_height). When set and present, the :profile temperature source samples the T(z) profile at this per-cell height — enabling temperature on 2-D PPI/RHI grids that have no Z axis. Empty (default) falls back to the grid's z-axis heights.
• temp_factor::Float64: broadens the temperature membership functions when > 1.
• correct_ice_method::Bool: label rain method code 2 only on hail cells (default true); false replicates the Python ice-method bug exactly.
• fhc_output/rain_output/rain_method_output::String: output variable names. rain_method_output="" suppresses the method field.
• weights::Dict{Symbol,Float64}: per-variable FHC weights (keys :DZ, :DR, :KD, :RH, :LD, :T).
• temperature::Union{TemperatureProfile,Nothing}: vertical T(z) profile (°C), required when use_temp is true and temp_source = :profile. A temporary stand-in for a future shared hydrostatic reference state (see temperature_profile.jl).

apply_echo_products(fields, dp::EchoProductsParameters;
                       io::IOParameters, heights=nothing) -> Dict{String,Array{Float32}}

Compute the configured echo products from a dict of gridded fields (keyed by name, e.g. the fields of read_gridded_radar). Returns a dict of new fields keyed by their output names. heights is an array the same shape as the input fields giving each cell's height in meters; when supplied with a temperature profile it enables the temperature term of the FHC.

The hydrometeor classification, when computed, is fed into the blended rain rate for ice/hail masking.

add_echo_products!(file, p::DaishoParameters) -> Vector{String}

Compute the echo products (per p.echo) for an already-written Daisho gridded NetCDF file and append them as new variables in place. Supports 3-D volume (X,Y,Z), 2-D PPI/composite (X,Y) and 2-D RHI (R,Z) layouts, and loops over the time dimension for concatenated multi-time files. Returns the names of the variables written.

The standalone counterpart to the in-grid hook: useful for reprocessing archived grids or applying updated coefficients without regridding.

echo_output_names(dp::EchoProductsParameters) -> Vector{String}

The names of the netCDF variables this echo configuration writes: the HID field, the blended rain field, the optional rain-method field, and any individual rain components. Echo products are appended after gridding and are therefore not part of [fields]; this list lets the gridded readers surface them anyway.

csu_fhc_summer(; dz, zdr=nothing, kdp=nothing, rho=nothing, ldr=nothing,
               T=nothing, weights=DEFAULT_FHC_WEIGHTS, method=:hybrid,
               band="S", use_temp=true, temp_factor=1.0,
               return_scores=false, fill_value=-32768.0, undetect=-9999.0,
               masked=0)

Fuzzy-logic hydrometeor identification for warm-season precipitation. Julia port of CSURadarTools `csufhc_summer`.

dz (reflectivity, dBZ) is required; zdr (dB), kdp (deg/km), rho (unitless), ldr (dB) and T (temperature, °C) are optional and, when supplied, must broadcast to the same shape as dz. Inputs may be scalars or arrays of any dimensionality.

Returns an integer classification array (or scalar) with values 1:FHC_N_TYPES (see FHC_SUMMER_CLASSES); gates whose dz is non-finite or equal to a sentinel are set to masked. With return_scores=true, returns the full score array of shape (FHC_N_TYPES, size(dz)...) instead (matching the Python return_scores ordering).

Methods: :hybrid (default) weights the polarimetric variables into a normalized score, then multiplies by the temperature and reflectivity memberships; :linear treats all present variables as a single weighted sum.

get_mbf_sets_summer(band="S"; use_temp=true, temp_factor=1.0)

Load the warm-season membership beta function coefficient sets for a frequency band ("S", "C", or "X"). Returns a Dict{Symbol,NamedTuple} keyed by the classifier variable labels (:DZ, :DR, :KD, :LD, :RH, :T), each a (m, a, b) NamedTuple of length FHC_N_TYPES. The :T entry is nothing when use_temp=false. Port of CSURadarTools `getmbfsetssummer`.

beta_mbf(x, m, a, b)

Membership beta function 1 / (1 + (((x - m) / a)^2)^b). Returns a value in (0, 1]. This is the elementwise kernel of the fuzzy classification.

FHC_SUMMER_CLASSES

Summer (warm-season) hydrometeor classes recognized by the fuzzy-logic classifier, in argmax order so that the integer class label returned by csu_fhc_summer indexes directly into this tuple (class i == FHC_SUMMER_CLASSES[i]). The ten classes are drizzle, rain, ice crystals, aggregates, wet snow, vertical ice, low-density graupel, high-density graupel, hail, and big drops. A class label of 0 denotes an unclassified (masked) gate.

FHC_N_TYPES

Number of hydrometeor classes in FHC_SUMMER_CLASSES (10). This is the leading dimension of the per-class score array produced during classification.

DEFAULT_FHC_WEIGHTS

Default relative weights for the fuzzy hydrometeor classification variables (matches CSURadarTools `DEFAULTWEIGHTS): reflectivityDZ, differential reflectivityDR, specific differential phaseKD, copolar correlationRH, linear depolarization ratioLD, and temperatureT. In the:hybridmethod only the polarimetric weights (DR,KD,RH,LD) enter the weighted sum;DZandTact as pure multipliers, so their weights are unused there. Pass aNamedTuplewith the same keys to [csufhcsummer`](@ref) to override.

calc_blended_rain_tropical(; dz, zdr, kdp, fhc=nothing, cs=nothing, band="S",
    thresh_dz=38.0, thresh_zdr=0.25, thresh_kdp=0.3,
    correct_ice_method=true, fill_value=-32768.0, undetect=-9999.0)

Blended tropical/oceanic rain rate (Thompson et al. 2016). Julia port of CSURadarTools `calcblendedraintropical`.

Per grid cell, selects the best rain-rate estimate via the Thompson flowchart from reflectivity dz (dBZ), differential reflectivity zdr (dB) and specific differential phase kdp (deg/km). Returns (rain, method) arrays (mm h⁻¹ and method codes; see RAIN_METHOD_*).

Selection priority:

1. kdp ≥ thresh_kdp ∧ dz ≥ thresh_dz ∧ zdr ≥ thresh_zdr → R(Kdp,Zdr)
2. kdp ≥ thresh_kdp ∧ dz ≥ thresh_dz ∧ zdr < thresh_zdr → R(Kdp)
3. zdr ≥ thresh_zdr ∧ ¬(kdp ≥ thresh_kdp ∧ dz ≥ thresh_dz) → R(Z,Zdr)
4. otherwise → R(Zall), or R(Zconv)/R(Z_strat) when a convective/stratiform map cs is supplied (cs: 1=stratiform, 2=convective, 3=mixed, 0=unknown).

Optional fhc (hydrometeor class array, e.g. from csu_fhc_summer) masks ice: classes 2 < fhc < 10 get rain 0, and hail (fhc == 9) with the Kdp/Z condition met falls back to R(Kdp).

correct_ice_method (default true) labels the method code 2 only on hail cells. The Python original sets it on all ice cells (an apparent bug at csublendedrain_tropical.py:221); set false to replicate that exactly. Rain values are identical either way.

calc_rain_zr(dz; a=216.0, b=1.39)

R(Z) rain rate (mm h⁻¹) from reflectivity dz (dBZ): R = (10^(dBZ/10)/a)^(1/b). Use the convective (RAIN_RZ_CONV) or stratiform (RAIN_RZ_STRAT) coefficients for those regimes. Accepts a scalar or array.

calc_rain_kdp(kdp; a, b)

R(Kdp) rain rate (mm h⁻¹): R = a·Kdp^b. Pass band coefficients from RAIN_BAND_COEFFS or use calc_rain_kdp(kdp, band). Accepts a scalar or array.

calc_rain_kdp_zdr(kdp, zdr; a, b, c)

R(Kdp,Zdr) rain rate (mm h⁻¹): R = a·Kdp^b·10^(c·Zdr). Accepts scalars or arrays.

calc_rain_z_zdr(dz, zdr; a, b, c)

R(Z,Zdr) rain rate (mm h⁻¹): R = a·(10^(dBZ/10))^b·10^(c·Zdr). Accepts scalars or arrays.

RAIN_RZ_ALL

(a, b) coefficients for the band-independent R(Z) relation R = (10^(dBZ/10) / a)^(1/b) for all/unspecified precipitation. Pass the a/b fields to calc_rain_zr. See also RAIN_RZ_CONV and RAIN_RZ_STRAT.

RAIN_RZ_CONV

(a, b) coefficients for the R(Z) relation tuned for convective precipitation. See RAIN_RZ_ALL.

RAIN_RZ_STRAT

(a, b) coefficients for the R(Z) relation tuned for stratiform precipitation. See RAIN_RZ_ALL.

RAIN_BAND_COEFFS

Per-band (a, b, c) coefficients for the polarimetric rain relations R(Kdp), R(Kdp, Zdr), and R(Z, Zdr), keyed by radar band ("S", "C", "X"). The c exponents are the Thompson values divided by 10 (the algorithm form is 10^(c·Zdr)). Used by calc_blended_rain_tropical and the band-aware methods of calc_rain_kdp, calc_rain_kdp_zdr, and calc_rain_z_zdr.

TemperatureProfile(heights, temperatures)

A piecewise-linear vertical temperature profile. heights are in meters (MSL or AGL, matching the grid's z-axis convention) and temperatures are in °C. Entries are sorted by height on construction; values outside the range are held constant at the nearest endpoint (no extrapolation).

This is a temporary stand-in for a full hydrostatic reference state (see the swap note in temperature_profile.jl). Sample it with temperature_celsius.

read_temperature_profile(path) -> TemperatureProfile

Read a two-column text file of height_m temperature_C (whitespace- or comma-delimited; blank lines and # comments ignored).

temperature_celsius(profile, z) -> Float64

Temperature (°C) at height z (meters) by linear interpolation, clamped to the profile endpoints outside its range. This is the single accessor the HID code depends on; a future shared reference state should implement the same method.

temperature_celsius(profile, z_axis::AbstractVector) -> Vector{Float64}

Sample the profile at every height in z_axis (meters).