Attenuation Correction#

AttenuationOverflowError

Attenuation Overflow Error

correct_attenuation_hb

Gate-by-Gate attenuation correction according to [Hitschfeld et al., 1954]

constraint_dbz

Constraint callback function for correct_attenuation_constrained.

constraint_pia

Constraint callback function for correct_attenuation_constrained.

correct_attenuation_constrained

Gate-by-Gate attenuation correction based on the iterative approach of [Kraemer et al., 2008] and [Jacobi et al., 2016] with a generalized and scalable number of constraints.

correct_radome_attenuation_empirical

Estimate two-way wet radome losses.

pia_from_kdp

Retrieving path integrated attenuation from specific differential phase (Kdp).

AttenMethods

wradlib xarray SubAccessor methods for Atten Methods.
exception wradlib.atten.AttenuationOverflowError[source]#

Bases: Exception

Attenuation Overflow Error

Exception, if attenuation exceeds thrs and no handling mode is set.

wradlib.atten.correct_attenuation_hb(gateset, *, coefficients={'a': 0.000167, 'b': 0.7, 'gate_length': 1.0}, mode='except', thrs=59.0)[source]#

Gate-by-Gate attenuation correction according to [Hitschfeld et al., 1954]

Parameters

  • gateset (numpy.ndarray) – multidimensional array. The range gates (over which iteration has to be performed) are supposed to vary along the last dimension so, e.g., for a set of l radar images stored in polar form with m azimuths and n range-bins the input array’s shape can be either (l,m,n) or (m,l,n) data has to be provided in decibel representation of reflectivity [dBZ]

  • a (float) – proportionality factor of the k-Z relation (\(k=a \cdot Z^{b}\)). Per default set to 1.67e-4.

  • b (float) – exponent of the k-Z relation ( \(k=a \cdot Z^{b}\) ). Per default set to 0.7.

  • gate_length (float) – length of a range gate [km]. Per default set to 1.0.

  • mode (str) – controls how the function reacts, if the sum of signal and attenuation exceeds the threshold thrs Possible values:

    • ‘warn’ : emit a warning through the module’s logger but continue execution

    • ‘zero’ : set offending gates to 0.0

    • ‘nan’ : set offending gates to nan

    • ‘except’: raise an AttenuationOverflowError exception

    Any other mode will also raise the Exception.

  • thrs (float) – threshold, for the sum of attenuation and signal, which is considered implausible.

Returns

pia (numpy.ndarray) – Array with the same shape as gateset containing the calculated attenuation [dB] for each range gate.

Raises

wradlib.atten.AttenuationOverflowError –

Examples

See Hitschfeld and Bordan.

wradlib.atten.constraint_dbz(gateset, pia, thrs_dbz)[source]#

Constraint callback function for correct_attenuation_constrained.

Selects beams, in which at least one pixel exceeds thrs_dbz [dBZ].

wradlib.atten.constraint_pia(gateset, pia, thrs_pia)[source]#

Constraint callback function for correct_attenuation_constrained.

Selects beams, in which the path integrated attenuation exceeds thrs_pia.

wradlib.atten.correct_attenuation_constrained(gateset, *, a_max=0.000167, a_min=2.33e-05, n_a=4, b_max=0.7, b_min=0.65, n_b=6, gate_length=1.0, constraints=None, constraint_args=None, sector_thr=10)[source]#
wradlib.atten.correct_attenuation_constrained(obj: DataArray, **kwargs)

Gate-by-Gate attenuation correction based on the iterative approach of [Kraemer et al., 2008] and [Jacobi et al., 2016] with a generalized and scalable number of constraints.

Differing from the original approach, the method for addressing small sectors which conflict with the constraints is based on a bisection forward calculating method, and not on backwards attenuation calculation.

Parameters

  • gateset (numpy.ndarray) – Multidimensional array, where the range gates (over which iteration has to be performed) are supposed to vary along the last array-dimension and the azimuths are supposed to vary along the next to last array-dimension.

    Data has to be provided in decibel representation of reflectivity [dBZ].

  • a_max (float) – Initial value for linear coefficient of the k-Z relation ( \(k=a \cdot Z^{b}\) ).

    Per default set to 1.67e-4.

  • a_min (float) – Minimal allowed linear coefficient of the k-Z relation ( \(k=a \cdot Z^{b}\) ) in the downwards iteration of ‘a’ in case of breaching one of thresholds constr_args of the optional conditions constraints.

    Per default set to 2.33e-5.

  • n_a (int) – Number of iterations from a_max to a_min.

    Per default set to 4.

  • b_max (float) – Initial value for exponential coefficient of the k-Z relation ( \(k=a \cdot Z^{b}\) ).

    Per default set to 0.7.

  • b_min (float) – Minimal allowed exponential coefficient of the k-Z relation ( \(k=a \cdot Z^{b}\) ) in the downwards iteration of ‘b’ in case of breaching one of thresholds constr_args of the optional conditions constraints and the linear coefficient ‘a’ has already reached the lower limit a_min.

    Per default set to 0.65.

  • n_b (int) – Number of iterations from b_max to b_min.

    Per default set to 6.

  • gate_length (float) – Radial length of a range gate [km].

    Per default set to 1.0.

  • constraints (list) – List of constraint functions. The signature of these functions has to be constraint_function(gateset, k, *constr_args). Their return value must be a boolean array of shape gateset.shape[:-1] set to True for beams, which do not fulfill the constraint.

  • constraint_args (list) – List of lists, which are to be passed to the individual constraint functions using the *args mechanism (len(constr_args) == len(constraints)).

  • sector_thr (int) – Number of adjacent beams, for which in case of breaching the constraints the attenuation with downward iterated a and b - parameters is recalculated. For more narrow sectors the integrated attenuation of the last gate is interpolated and used as reference for the recalculation.

Returns

pia (numpy.ndarray) – Array with the same shape as gateset containing the calculated path integrated attenuation [dB] for each range gate.

Examples

Implementing the original Hitschfeld & Bordan (1954) algorithm with otherwise default parameters:

from wradlib.atten import *
pia = correct_attenuation_constrained(gateset, a_max=8.e-5,
                                      b_max=0.731, n_a=1, n_b=1,
                                      gate_length=1.0)

Implementing the basic Kraemer algorithm:

pia = atten.correct_attenuation_constrained(gateset, a_max=1.67e-4,
                                            a_min=2.33e-5, n_a=100,
                                            b_max=0.7, b_min=0.65,
                                            n_b=6, gate_length=1.,
                                            constraints=
                                            [wrl.atten.constraint_dbz],
                                            constraint_args=[[59.0]])

Implementing the PIA algorithm by Jacobi et al.:

pia = atten.correct_attenuation_constrained(gateset, a_max=1.67e-4,
                                            a_min=2.33e-5, n_a=100,
                                            b_max=0.7, b_min=0.65,
                                            n_b=6, gate_length=1.,
                                            constraints=
                                            [wrl.atten.constraint_dbz,
                                            wrl.atten.constraint_pia],
                                            constraint_args=
                                            [[59.0],[20.0]])
wradlib.atten.correct_radome_attenuation_empirical(gateset, *, frequency=5.64, hydrophobicity=0.165, n_r=2, stat=<function mean>)[source]#

Estimate two-way wet radome losses.

Empirical function of frequency and rainfall rate for both standard and hydrophobic radomes based on the approach of [Merceret et al., 2000].

Parameters

  • gateset (numpy.ndarray) – Multidimensional array, where the range gates (over which iteration has to be performed) are supposed to vary along the last array-dimension and the azimuths are supposed to vary along the next to last array-dimension. Data has to be provided in decibel representation of reflectivity [dBZ].

  • frequency (float) –

    Radar-frequency [GHz]:

    Standard frequencies in X-band range between 8.0 and 12.0 GHz,

    Standard frequencies in C-band range between 4.0 and 8.0 GHz,

    Standard frequencies in S-band range between 2.0 and 4.0 GHz.

    Be aware that the empirical fit of the formula was just done for C- and S-band. The use for X-band is probably an undue extrapolation.

    Per default set to 5.64 as used by the German Weather Service radars.

  • hydrophobicity (float) – Empirical parameter based on the hydrophobicity of the radome material.

    • 0.165 for standard radomes,

    • 0.0575 for hydrophobic radomes.

    Per default set to 0.165.

  • n_r (int) – The radius of rangebins within the rain-intensity is statistically evaluated as the representative rain-intensity over radome.

  • stat (callable) – A numpy function for statistical aggregation of the central rangebins defined by n_r.

    Potential options: np.mean, np.median, np.max, np.min.

Returns

k (numpy.ndarray) – Array with the same shape as gateset containing the calculated two-way transmission loss [dB] for each range gate. In case the input array (gateset) contains NaNs the corresponding beams of the output array (k) will be set as NaN, too.

wradlib.atten.pia_from_kdp(kdp, dr, *, gamma=0.08)[source]#

Retrieving path integrated attenuation from specific differential phase (Kdp).

The default value of gamma is based on [Carey et al., 2000].

Parameters

  • kdp (numpy.ndarray) – array specific differential phase Range dimension must be the last dimension.

  • dr (float) – gate length (km)

  • gamma (float) – linear coefficient (default value: 0.08) in the relation between Kdp phase and specific attenuation (alpha)

Returns

output (numpy.ndarray) – array of same shape as kdp containing the path integrated attenuation

class wradlib.atten.AttenMethods(obj)[source]#

Bases: XarrayMethods

wradlib xarray SubAccessor methods for Atten Methods.

correct_attenuation_constrained(*, a_max=0.000167, a_min=2.33e-05, n_a=4, b_max=0.7, b_min=0.65, n_b=6, gate_length=1.0, constraints=None, constraint_args=None, sector_thr=10)[source]#

Gate-by-Gate attenuation correction based on the iterative approach of [Kraemer et al., 2008] and [Jacobi et al., 2016] with a generalized and scalable number of constraints.

Differing from the original approach, the method for addressing small sectors which conflict with the constraints is based on a bisection forward calculating method, and not on backwards attenuation calculation.

Parameters

  • gateset (numpy.ndarray) – Multidimensional array, where the range gates (over which iteration has to be performed) are supposed to vary along the last array-dimension and the azimuths are supposed to vary along the next to last array-dimension.

    Data has to be provided in decibel representation of reflectivity [dBZ].

  • a_max (float) – Initial value for linear coefficient of the k-Z relation ( \(k=a \cdot Z^{b}\) ).

    Per default set to 1.67e-4.

  • a_min (float) – Minimal allowed linear coefficient of the k-Z relation ( \(k=a \cdot Z^{b}\) ) in the downwards iteration of ‘a’ in case of breaching one of thresholds constr_args of the optional conditions constraints.

    Per default set to 2.33e-5.

  • n_a (int) – Number of iterations from a_max to a_min.

    Per default set to 4.

  • b_max (float) – Initial value for exponential coefficient of the k-Z relation ( \(k=a \cdot Z^{b}\) ).

    Per default set to 0.7.

  • b_min (float) – Minimal allowed exponential coefficient of the k-Z relation ( \(k=a \cdot Z^{b}\) ) in the downwards iteration of ‘b’ in case of breaching one of thresholds constr_args of the optional conditions constraints and the linear coefficient ‘a’ has already reached the lower limit a_min.

    Per default set to 0.65.

  • n_b (int) – Number of iterations from b_max to b_min.

    Per default set to 6.

  • gate_length (float) – Radial length of a range gate [km].

    Per default set to 1.0.

  • constraints (list) – List of constraint functions. The signature of these functions has to be constraint_function(gateset, k, *constr_args). Their return value must be a boolean array of shape gateset.shape[:-1] set to True for beams, which do not fulfill the constraint.

  • constraint_args (list) – List of lists, which are to be passed to the individual constraint functions using the *args mechanism (len(constr_args) == len(constraints)).

  • sector_thr (int) – Number of adjacent beams, for which in case of breaching the constraints the attenuation with downward iterated a and b - parameters is recalculated. For more narrow sectors the integrated attenuation of the last gate is interpolated and used as reference for the recalculation.

Returns

pia (numpy.ndarray) – Array with the same shape as gateset containing the calculated path integrated attenuation [dB] for each range gate.

Examples

Implementing the original Hitschfeld & Bordan (1954) algorithm with otherwise default parameters:

from wradlib.atten import *
pia = correct_attenuation_constrained(gateset, a_max=8.e-5,
                                      b_max=0.731, n_a=1, n_b=1,
                                      gate_length=1.0)

Implementing the basic Kraemer algorithm:

pia = atten.correct_attenuation_constrained(gateset, a_max=1.67e-4,
                                            a_min=2.33e-5, n_a=100,
                                            b_max=0.7, b_min=0.65,
                                            n_b=6, gate_length=1.,
                                            constraints=
                                            [wrl.atten.constraint_dbz],
                                            constraint_args=[[59.0]])

Implementing the PIA algorithm by Jacobi et al.:

pia = atten.correct_attenuation_constrained(gateset, a_max=1.67e-4,
                                            a_min=2.33e-5, n_a=100,
                                            b_max=0.7, b_min=0.65,
                                            n_b=6, gate_length=1.,
                                            constraints=
                                            [wrl.atten.constraint_dbz,
                                            wrl.atten.constraint_pia],
                                            constraint_args=
                                            [[59.0],[20.0]])