disdrodb.l2 package

Contents

disdrodb.l2 package#

Submodules#

disdrodb.l2.empirical_dsd module#

Functions for computation of DSD parameters.

The functions of this module expects xarray.DataArray objects as input. Zeros and NaN values input arrays are correctly processed. Infinite values should be removed beforehand or otherwise are propagated throughout the computations.

disdrodb.l2.empirical_dsd.add_bins_metrics(ds)[source][source]#

Add bin metrics if missing.

disdrodb.l2.empirical_dsd.bringi_nw_dm_classification(Dm, Nw)[source][source]#

Bringi stratiform / convective classification using Nw-Dm space.

Returns:

0 = invalid / no rain 1 = stratiform 2 = convective

Return type:

xr.DataArray

disdrodb.l2.empirical_dsd.compute_integral_parameters(drop_number_concentration, velocity, diameter, diameter_bin_width, sample_interval, water_density)[source][source]#

Compute integral parameters of a drop size distribution (DSD).

Parameters:

  • drop_number_concentration (xarray.DataArray) – Drop number concentration in each diameter bin [#/m3/mm].

  • velocity (xarray.DataArray) – Fall velocity of drops in each diameter bin [m/s]. The presence of a velocity_method dimension enable to compute the parameters with different velocity estimates.

  • diameter (array-like) – Diameter of drops in each bin in m.

  • diameter_bin_width (array-like) – Width of each diameter bin in mm.

  • sample_interval (float) – Time interval over which the samples are collected in seconds.

  • water_density (float or array-like) – Density of water [kg/m3].

Returns:

ds – Dataset containing the computed integral parameters:

  • Nt : Total number concentration [#/m3]

  • M1 to M6 : Moments of the drop size distribution

  • Z : Reflectivity factor [dBZ]

  • W : Liquid water content [g/m3]

  • D10 : Diameter at the 10th quantile of the cumulative LWC distribution [mm]

  • D50 : Median volume drop diameter [mm]

  • D90 : Diameter at the 90th quantile of the cumulative LWC distribution [mm]

  • Dmode : Diameter at which the distribution peaks [mm]

  • Dm : Mean volume drop diameter [mm]

  • sigma_m : Standard deviation of the volume drop diameter [mm]

  • Nw : Normalized intercept parameter [m-3·mm⁻¹]

  • R : Rain rate [mm/h]

  • P : Rain accumulation [mm]

  • TKE: Total Kinetic Energy [J/m2]

  • KED: Kinetic Energy per unit rainfall Depth [J·m⁻²·mm⁻¹].

  • KEF: Kinetic Energy Flux [J·m⁻²·h⁻¹].

Return type:

xarray.Dataset

disdrodb.l2.empirical_dsd.compute_qc_bins_metrics(ds)[source][source]#

Compute quality-control metrics for drop-count bins along the diameter dimension.

This function selects the first available drop-related variable from the dataset, optionally collapses over velocity methods and the velocity dimension, then computes four metrics per time step:

  1. Nbins: total number of diameter bins with non-zero count

  2. Nbins_missing: number of bins with zero or NaN counts between the first and last non-zero count

  3. Nbins_missing_fraction: fraction of missing bins (zeros) between the first and last non-zero count

  4. Nbins_missing_consecutive: maximum length of consecutive missing bins

Parameters:

ds (xarray.Dataset) – Input dataset containing one of the following variables: ‘drop_counts’, ‘drop_number_concentration’, or ‘drop_number’. If a ‘velocity_method’ dimension exists, only the first method is used. If a velocity dimension (specified by VELOCITY_DIMENSION) exists, it is summed over.

Returns:

Dataset with a new ‘metric’ dimension of size 4 and coordinates: [‘Nbins’, ‘Nbins_missing’, ‘Nbins_missing_fraction’, ‘Nbins_missing_consecutive’], indexed by ‘time’.

Return type:

xarray.Dataset

disdrodb.l2.empirical_dsd.compute_spectrum_parameters(drop_number_concentration, velocity, diameter, sample_interval, water_density=1000)[source][source]#

Compute drop size spectrum of rain rate, kinetic energy, mass and reflectivity.

Parameters:

  • drop_number_concentration (xarray.DataArray) – Drop number concentration in each diameter bin [#/m3/mm].

  • velocity (xarray.DataArray) – Fall velocity of drops in each diameter bin [m/s]. The presence of a velocity_method dimension enable to compute the parameters with different velocity estimates.

  • diameter (array-like) – Diameter of drops in each bin in m.

  • sample_interval (float) – Time interval over which the samples are collected in seconds.

  • water_density (float or array-like) – Density of water [kg/m3].

Returns:

ds – Dataset containing the following spectrum:

  • KE_spectrum : Kinetic Energy spectrum [J/m2/mm]

  • R_spectrum : Rain Rate spectrum [mm/h/mm]

  • LWC_spectrum : Mass spectrum [g/m3/mm]

  • Z_spectrum : Reflectivity spectrum [dBZ of mm6/m3/mm]

Return type:

xarray.Dataset

disdrodb.l2.empirical_dsd.count_bins_with_drops(ds)[source][source]#

Count the number of diameter bins with data.

disdrodb.l2.empirical_dsd.get_bin_dimensions(xr_obj)[source][source]#

Return the dimensions of the drop spectrum.

disdrodb.l2.empirical_dsd.get_drop_average_velocity(drop_number)[source][source]#

Calculate the drop average velocity \( v_m(D))) \) per diameter class.

The average velocity is obtained by weighting by the number of drops in each velocity bin. If in a given diameter bin no drops are recorded, the resulting average drop size velocity for such bin will be set to NaN.

Parameters:

drop_number (xarray.DataArray) – Array of drop counts \( n(D,v) \) per diameter (and velocity, if available) bins over the measurement interval. The DataArray must have the velocity_bin_center coordinate.

Returns:

average_velocity – Array of drop average velocity \( v_m(D))) \) in m·s⁻¹ . At timesteps with zero drop counts, it returns NaN.

Return type:

xarray.DataArray

disdrodb.l2.empirical_dsd.get_drop_counts_from_number_concentration(drop_number_concentration, velocity, diameter_bin_width, sample_interval, sampling_area)[source][source]#

Calculate drop counts from drop number concentration.

Parameters:

  • drop_number_concentration (xarray.DataArray) – Drop number concentration \(N(D)\) in m-3 mm-1.

  • velocity (xarray.DataArray) – Drop fall velocity \(v(D)\) in m s-1. The array can already be broadcast on the target dimensions.

  • diameter_bin_width (xarray.DataArray) – Diameter bin width \(\Delta D\) in millimeters.

  • sample_interval (float or xarray.DataArray) – Measurement interval \(\Delta t\) in seconds.

  • sampling_area (float or xarray.DataArray) – Effective sensor sampling area \(A\) in square meters.

Returns:

Drop counts \(n(D)\) or \(n(D, v)\) over the measurement interval.

Return type:

xarray.DataArray

Notes

This is a drop-specific wrapper around get_particle_counts_from_number_concentration().

disdrodb.l2.empirical_dsd.get_drop_number_concentration(drop_number, velocity, diameter_bin_width, sampling_area, sample_interval)[source][source]#

Calculate the volumetric drop number concentration \( N(D) \) per diameter class.

Computes the drop number concentration \( N(D) \) [m⁻³·mm⁻¹] for each diameter class based on the measured drop counts and sensor parameters. This represents the number of drops per unit volume per unit diameter interval. It is also referred to as the drop size distribution N(D) per cubic metre per millimetre [m-3 mm-1]

Parameters:

  • velocity (xarray.DataArray) – Array of drop fall velocities \( v(D) \) corresponding to each diameter bin in meters per second (m/s). Typically the estimated fall velocity is used. But one can also pass the velocity bin center of the optical disdrometer, which get broadcasted along the diameter bin dimension.

  • diameter_bin_width (xarray.DataArray) – Width of each diameter bin \( \Delta D \) in millimeters (mm).

  • drop_number (xarray.DataArray) – Array of drop counts \( n(D) or n(D,v) \) per diameter (and velocity if available) bins over the measurement interval.

  • sample_interval (float or xarray.DataArray) – Time over which the drops are counted \( \Delta t \) in seconds (s).

  • sampling_area (float or xarray.DataArray) – The effective sampling area \( A \) of the sensor in square meters (m²).

Returns:

drop_number_concentration – Array of drop number concentrations \( N(D) \) in m⁻³·mm⁻¹, representing the number of drops per unit volume per unit diameter interval.

Return type:

xarray.DataArray or numpy.ndarray

Notes

The drop number concentration \( N(D) \) is calculated using:

\[\begin{split}N(D) = \frac{n(D)}{A_{\text{eff}}(D) \\cdot \\Delta D \\cdot \\Delta t \\cdot v(D)}\end{split}\]

where:

  • \( n(D,v) \): Number of drops counted in diameter (and velocity) bins.

  • \( A_{text{eff}}(D) \): Effective sampling area of the sensor for diameter \( D \) in square meters (m²).

  • \( \Delta D \): Diameter bin width in millimeters (mm).

  • \( \Delta t \): Measurement interval in seconds (s).

  • \( v(D) \): Fall velocity of drops in diameter bin \( D \) in meters per second (m/s).

The effective sampling area \( A_{text{eff}}(D) \) depends on the sensor and may vary with drop diameter.

disdrodb.l2.empirical_dsd.get_drop_volume(diameter)[source][source]#

Compute the volume of a droplet assuming it is spherical.

Parameters:

diameter (float or array-like) – The diameter of the droplet(s). Can be a scalar or an array of diameters.

Returns:

The volume of the droplet(s) calculated in cubic units based on the input diameter(s).

Return type:

array-like

Notes

The volume is calculated using the formula for the volume of a sphere: V = (π/6) * d^3, where d is the diameter of the droplet.

disdrodb.l2.empirical_dsd.get_effective_sampling_area(sensor_name, diameter)[source][source]#

Compute the effective sampling area in m2 of the disdrometer.

The diameter must be provided in meters !

disdrodb.l2.empirical_dsd.get_effective_sampling_interval(ds, sensor_name)[source][source]#

Return the effective sample interval in seconds of the disdrometer.

disdrodb.l2.empirical_dsd.get_equivalent_reflectivity_factor(drop_number_concentration, diameter, diameter_bin_width)[source][source]#

Compute the equivalent reflectivity factor in decibels relative to 1 mm⁶·m⁻³ (dBZ).

The equivalent reflectivity (in mm⁶·m⁻³) is obtained from the sixth moment of the drop size distribution (DSD). The reflectivity factor is expressed in decibels relative to 1 mm⁶·m⁻³ using the formula:

\[Z = 10 \cdot \log_{10}(z)\]

where \( z \) is the reflectivity in linear units of the DSD.

To convert back the reflectivity factor to linear units (mm⁶·m⁻³), use the formula:

\[z = 10^{(Z/10)}\]
Parameters:

  • drop_number_concentration (xarray.DataArray) – Array representing the concentration of droplets per diameter class in number per unit volume.

  • diameter (xarray.DataArray) – Array of droplet diameters in meters (m).

  • diameter_bin_width (xarray.DataArray) – Array representing the width of each diameter bin in millimeters (mm).

Returns:

The equivalent reflectivity factor in decibels (dBZ).

Return type:

xarray.DataArray

Notes

The function computes the sixth moment of the DSD using the formula:

\[\begin{split}z = \\sum n(D) \cdot D^6 \cdot \\Delta D\end{split}\]

where \( n(D) \) is the drop number concentration, \( D \) is the drop diameter, and \( \Delta D \) is the diameter bin width.

disdrodb.l2.empirical_dsd.get_equivalent_reflectivity_spectrum(drop_number_concentration, diameter)[source][source]#

Compute the equivalent reflectivity per diameter class.

The equivalent reflectivity per unit diameter Z(D) [in mm⁶·m⁻³ / mm] is expressed in decibels using the formula:

\[Z(D) = 10 \cdot \log_{10}(z(D))\]

where \( z(D) \) is the equivalent reflectivity spectrum in linear units of the DSD.

To convert back the reflectivity factor to linear units (mm⁶·m⁻³ / mm), use the formula:

\[z(D) = 10^{(Z(D)/10)}\]

To obtain the total equivalent reflectivity factor (z) one has to multiply z(D) with the diameter bins intervals and summing over the diameter bins.

Parameters:

  • drop_number_concentration (xarray.DataArray) – Array representing the concentration of droplets per diameter class in number per unit volume.

  • diameter (xarray.DataArray) – Array of droplet diameters in meters (m).

Returns:

The equivalent reflectivity spectrum in decibels (dBZ).

Return type:

xarray.DataArray

disdrodb.l2.empirical_dsd.get_kinetic_energy_spectrum(drop_number_concentration, velocity, diameter, sample_interval, water_density=1000)[source][source]#

Compute the rainfall kinetic energy per diameter class.

To obtain the Total Kinetic Energy (TKE) one has to multiply KE(D) with the diameter

bins intervals and summing over the diameter bins.

Parameters:

  • drop_number_concentration (xarray.DataArray) – Array of drop number concentrations \( N(D) \) in m⁻³·mm⁻¹.

  • velocity (xarray.DataArray or float) – The fall velocities \( v \) of the drops, in meters per second (m/s).

  • diameter (xarray.DataArray) – The equivalent volume diameters \( D \) of the drops in each bin, in meters (m).

  • sample_interval (float) – The time over which the drops are counted \( \Delta t \) in seconds (s).

  • water_density (float, optional) – The density of water \( rho_w \) in kilograms per cubic meter (kg/m³). Default is 1000 kg/m³.

Returns:

Kinetic Energy Spectrum [J/m2/mm]

Return type:

xarray.DataArray

disdrodb.l2.empirical_dsd.get_kinetic_energy_variables(drop_number_concentration, velocity, diameter, diameter_bin_width, sample_interval, water_density=1000)[source][source]#

Compute rainfall kinetic energy descriptors from the drop number concentration.

Parameters:

  • drop_number_concentration (xarray.DataArray) – Array of drop number concentrations \( N(D) \) in m⁻³·mm⁻¹.

  • velocity (xarray.DataArray or float) – The fall velocities \( v \) of the drops, in meters per second (m/s).

  • diameter (xarray.DataArray) – The equivalent volume diameters \( D \) of the drops in each bin, in meters (m).

  • diameter_bin_width (xarray.DataArray) – Width of each diameter bin \( \Delta D \) in millimeters (mm).

  • sample_interval (float) – The time over which the drops are counted \( \Delta t \) in seconds (s).

  • water_density (float, optional) – The density of water \( rho_w \) in kilograms per cubic meter (kg/m³). Default is 1000 kg/m³.

Returns:

Xarray Dataset with relevant rainfall kinetic energy variables:

  • TKE: Total Kinetic Energy [J/m2]

  • KED: Kinetic Energy per unit rainfall Depth [J·m⁻²·mm⁻¹]. Typical values range between 0 and 40 J·m⁻²·mm⁻¹.

  • KEF: Kinetic Energy Flux [J·m⁻²·h⁻¹]. Typical values range between 0 and 5000 J·m⁻²·h⁻¹.

KEF is related to the KED by the rain rate: KED = KEF/R .

Return type:

xarray.Dataset

disdrodb.l2.empirical_dsd.get_kinetic_energy_variables_from_drop_number(drop_number, velocity, sampling_area, diameter, sample_interval, water_density=1000)[source][source]#

Compute rainfall kinetic energy descriptors from the measured drop number spectrum.

Parameters:

  • drop_number (xarray.DataArray) – The number of drops in each diameter (and velocity, if available) bin(s).

  • velocity (xarray.DataArray or float) – The fall velocities \( v \) of the drops in each bin, in meters per second (m/s). Values are broadcasted to match the dimensions of drop_number.

  • diameter (xarray.DataArray) – The equivalent volume diameters \( D \) of the drops in each bin, in meters (m).

  • sampling_area (float) – The effective sampling area \( A \) of the sensor in square meters (m²).

  • sample_interval (float) – The time over which the drops are counted \( \Delta t \) in seconds (s).

  • water_density (float, optional) – The density of water \( rho_w \) in kilograms per cubic meter (kg/m³). Default is 1000 kg/m³.

Returns:

Xarray Dataset with relevant rainfall kinetic energy variables:

  • TKE: Total Kinetic Energy [J/m2]

  • KED: Kinetic Energy per unit rainfall Depth [J·m⁻²·mm⁻¹]. Typical values range between 0 and 40 J·m⁻²·mm⁻¹.

  • KEF: Kinetic Energy Flux [J·m⁻²·h⁻¹]. Typical values range between 0 and 5000 J·m⁻²·h⁻¹.

KEF is related to the KED by the rain rate: KED = KEF/R .

Return type:

xarray.Dataset

Notes

KED provides a measure of the energy associated with each unit of rainfall depth. KED is useful for analyze the potential impact of raindrop erosion as a function of the intensity of rainfall events.

The kinetic energy of a rain drop is defined as:

\[\begin{split}KE(D) = \frac{1}{2} · m_{drop} · v_{drop}^2 = \frac{\\pi \rho_{w}}{12} · D^3 · v^2\end{split}\]

The Total Kinetic Energy (TKE) is calculated using:

\[\begin{split}TKE = \\sum_{i,j} \\left({n_{ij} · KE(D_{i}) \right) = \frac{\\pi \rho_{w}}{12 · A} \\sum_{i,j} \\left( {n_{ij} · D_{i}^3 · v_{j}^2}} \right)\end{split}\]

The Kinetic Energy Flux (KEF) is calculated using:

\[\begin{split}KEF = \frac{TKE}{\\Delta t } · 3600\end{split}\]

KED is calculated using:

\[\begin{split}KED = \frac{KEF}{R} \\cdot \frac{\\pi}{6} \\cdot \frac{\rho_w}{R} \\cdot \\sum_{i,j} \\left( \frac{n_{ij} \\cdot D_i^3 \\cdot v_j^2}{A} \right)\end{split}\]

where:

  • \( n_{ij} \) is the number of drops in diameter bin \( i \) and velocity bin \( j \).

  • \( D_i \) is the diameter of bin \( i \).

  • \( v_j \) is the velocity of bin \( j \).

  • \( A \) is the sampling area.

  • \( \Delta t \) is the measurement interval in seconds.

  • \( R \) is the rainfall rate in mm/hr.

disdrodb.l2.empirical_dsd.get_liquid_water_content(drop_number_concentration, diameter, diameter_bin_width, water_density=1000)[source][source]#

Calculate the liquid water content based on drop number concentration and drop diameter.

Parameters:

  • drop_number_concentration (array-like) – The concentration of droplets (number of droplets per unit volume) in each diameter bin.

  • diameter (array-like) – The diameters of the droplets for each bin, in meters (m).

  • diameter_bin_width (array-like) – The width of each diameter bin, in millimeters (mm).

  • water_density (float, optional) – The density of water in kg/m^3. The default is 1000 kg/m3.

Returns:

The calculated liquid water content in grams per cubic meter (g/m3).

Return type:

array-like

disdrodb.l2.empirical_dsd.get_liquid_water_content_from_moments(moment_3, water_density=1000)[source][source]#

Calculate the liquid water content (LWC) from the third moment of the DSD.

LWC represents the mass of liquid water per unit volume of air.

Parameters:

  • moment_3 (float or array-like) – The third moment of the drop size distribution, \( M_3 \), in units of [m⁻³·mm³] (number per cubic meter times diameter cubed).

  • water_density (float, optional) – The density of water in kilograms per cubic meter (kg/m³). Default is 1000 kg/m³ (approximate density of water at 20°C).

Returns:

lwc – The liquid water content in grams per cubic meter (g/m³).

Return type:

float or array-like

Notes

The liquid water content is calculated using the formula:

\[\begin{split}\text{LWC} = \frac{\\pi \rho_w}{6} \\cdot M_3\end{split}\]

where:

  • \( text{LWC} \) is the liquid water content [g/m³].

  • \( rho_w \) is the density of water [g/mm³].

  • \( M_3 \) is the third moment of the DSD [m⁻³·mm³].

Examples

Compute the liquid water content from the third moment:

>>> moment_3 = 1e6  # Example value in [m⁻³·mm³]
>>> lwc = get_liquid_water_content_from_moments(moment_3)
>>> print(f"LWC: {lwc:.4f} g/m³")
LWC: 0.0005 g/m³
disdrodb.l2.empirical_dsd.get_liquid_water_spectrum(drop_number_concentration, diameter, water_density=1000)[source][source]#

Calculate the mass spectrum W(D) per diameter class.

It represents the mass of liquid water as a function of raindrop diameter. The integrated liquid water content can be obtained by multiplying the spectrum with the diameter bins intervals and summing over the diameter bins.

Parameters:

  • drop_number_concentration (array-like) – The concentration of droplets (number of droplets per unit volume) in each diameter bin.

  • diameter (array-like) – The diameters of the droplets for each bin, in meters (m).

Returns:

The calculated rain drop mass spectrum in grams per cubic meter per unit diameter (g/m3/mm).

Return type:

array-like

disdrodb.l2.empirical_dsd.get_mean_volume_drop_diameter(moment_3, moment_4)[source][source]#

Calculate the volume-weighted mean volume diameter \( D_m \) from DSD moments.

The mean volume diameter of a drop size distribution (DSD) is computed using the third and fourth moments.

The volume-weighted mean volume diameter is also referred as the mass mean diameter. It represents the first moment of the mass spectrum.

If no drops are recorded, the output values is NaN.

Parameters:

  • moment_3 (float or array-like) – The third moment of the drop size distribution, \( M_3 \), in units of [m⁻³·mm³].

  • moment_4 (float or array-like) – The fourth moment of the drop size distribution, \( M_4 \), in units of [m⁻³·mm⁴].

Returns:

D_m – The mean volume diameter in millimeters (mm).

Return type:

float or array-like

Notes

The mean volume diameter is calculated using the formula:

\[D_m = \frac{M_4}{M_3}\]

where:

  • \( D_m \) is the mean volume diameter [mm].

  • \( M_3 \) is the third moment of the DSD [m⁻³·mm³].

  • \( M_4 \) is the fourth moment of the DSD [m⁻³·mm⁴].

Examples

Compute the mean volume diameter from the third and fourth moments:

>>> moment_3 = 1e6  # Example value in [m⁻³·mm³]
>>> moment_4 = 5e6  # Example value in [m⁻³·mm⁴]
>>> D_m = get_mean_volume_drop_diameter(moment_3, moment_4)
>>> print(f"Mean Volume Diameter D_m: {D_m:.4f} mm")
Mean Volume Diameter D_m: 5.0000 mm
disdrodb.l2.empirical_dsd.get_median_volume_drop_diameter(drop_number_concentration, diameter, diameter_bin_width, water_density=1000)[source][source]#

Compute the median volume drop diameter (D50).

The median volume drop diameter (D50) is defined as the diameter at which half of the total liquid water content is contributed by drops smaller than D50, and half by drops larger than D50.

Drops smaller (respectively larger) than D50 contribute to half of the total rainwater content in the sampled volume. D50 is sensitive to the concentration of large drops.

Often referred also as D50 (50 for 50 percentile of the distribution).

Parameters:

  • drop_number_concentration (xarray.DataArray) – The drop number concentration ( N(D) ) for each diameter bin, typically in units of number per cubic meter per millimeter (m⁻³·mm⁻¹).

  • diameter (xarray.DataArray) – The equivalent volume diameters ( D ) of the drops in each bin, in meters (m).

  • diameter_bin_width (xarray.DataArray) – The width ( Delta D ) of each diameter bin, in millimeters (mm).

  • water_density (float, optional) – The density of water in kg/m^3. The default is 1000 kg/m3.

Returns:

Median volume drop diameter (D50) [mm]. The drop diameter that divides the volume of water contained in the sample into two equal parts.

Return type:

xarray.DataArray

disdrodb.l2.empirical_dsd.get_min_max_diameter(drop_counts)[source][source]#

Get the minimum and maximum diameters where drop_counts is non-zero.

Parameters:

drop_counts (xarray.DataArray) – Drop counts with dimensions (“time”, “diameter_bin_center”) and coordinate “diameter_bin_center”. It assumes the diameter coordinate to be monotonically increasing !

Returns:

  • min_drop_diameter (xarray.DataArray) – Minimum diameter where drop_counts is non-zero, for each time step.

  • max_drop_diameter (xarray.DataArray) – Maximum diameter where drop_counts is non-zero, for each time step.

disdrodb.l2.empirical_dsd.get_mode_diameter(drop_number_concentration, diameter)[source][source]#

Get raindrop diameter with highest occurrence.

Parameters:

  • drop_number_concentration (xarray.DataArray) – The drop number concentration N(D) for each diameter bin, typically in units of number per cubic meter per millimeter (m⁻³·mm⁻¹).

  • diameter (xarray.DataArray) – The equivalent volume diameters D of the drops in each bin, in meters (m).

Returns:

The diameter with the highest drop number concentration.

Return type:

xarray.DataArray

disdrodb.l2.empirical_dsd.get_moment(drop_number_concentration, diameter, diameter_bin_width, moment)[source][source]#

Calculate the m-th moment of the drop size distribution.

Computes the m-th moment of the drop size distribution (DSD), denoted as E[D**m], where D is the drop diameter and m is the order of the moment. This is useful in meteorology and hydrology for characterizing precipitation. For example, weather radar measurements correspond to the sixth moment of the DSD (m = 6).

Parameters:

  • drop_number_concentration (xarray.DataArray) – The drop number concentration N(D) for each diameter bin, typically in units of number per cubic meter per millimeter (m⁻³ mm⁻¹).

  • diameter (xarray.DataArray) – The equivalent volume diameters D of the drops in each bin, in meters (m).

  • diameter_bin_width (xarray.DataArray) – The width dD of each diameter bin, in millimeters (mm).

  • moment (int or float) – The order m of the moment to compute.

Returns:

moment_value – The computed m-th moment of the drop size distribution, typically in units dependent on the input units, such as mmᵐ m⁻³.

Return type:

xarray.DataArray

Notes

The m-th moment is calculated using the formula:

\[\begin{split}M_m = \\sum_{\text{bins}} N(D) \\cdot D^m \\cdot dD\end{split}\]

where:

  • \( M_m \) is the m-th moment of the DSD.

  • \( N(D) \) is the drop number concentration for diameter \( D \).

  • \( D^m \) is the diameter raised to the power of \( m \).

  • \( dD \) is the diameter bin width.

This computation integrates over the drop size distribution to provide a scalar value representing the statistical momen

disdrodb.l2.empirical_dsd.get_nd_from_partial_number_concentrations(ds)[source][source]#

Reconstruct N(D) from partial number concentration variables.

Partial number concentration variable are selected by matching the naming convention N_<lower>_<upper>, where decimal points are encoded as p. For example, N_0p5_1p0 and N_3p0_4p0.

Parameters:

ds (xarray.Dataset) – Dataset containing partial number concentration variables.

Returns:

DataArray containing the reconstructed drop number concentration.

Return type:

xarray.DataArray

disdrodb.l2.empirical_dsd.get_normalized_intercept_parameter(liquid_water_content, mean_volume_diameter, water_density=1000)[source][source]#

Calculate the normalized intercept parameter \( N_w \) of the drop size distribution.

A higher \( N_w \) indicates a higher concentration of smaller drops. The \( N_w \) is used in models to represent the DSD when assuming a normalized gamma distribution.

Parameters:

  • liquid_water_content (float or array-like) – Liquid water content \( LWC \) in grams per cubic meter (g/m³).

  • mean_volume_diameter (float or array-like) – Mean volume diameter \( D_m \) in millimeters (mm).

  • water_density (float, optional) – Density of water \( rho_w \) in kilograms per cubic meter (kg/m³). The default is 1000 kg/m³.

Returns:

Nw – Normalized intercept parameter \( N_w \) in units of m⁻3·mm⁻¹.

Return type:

xarray.DataArray or float

Notes

The normalized intercept parameter \( N_w \) is calculated using the formula:

\[\begin{split}N_w = \frac{256}{\\pi \rho_w} \\cdot \frac{W}{D_m^4}\end{split}\]

where:

  • \( N_w \) is the normalized intercept parameter.

  • \( W \) is the liquid water content in g/m³.

  • \( D_m \) is the mean volume diameter in mm.

  • \( rho_w \) is the density of water in kg/m³.

disdrodb.l2.empirical_dsd.get_normalized_intercept_parameter_from_moments(moment_3, moment_4)[source][source]#

Calculate the normalized intercept parameter \( N_w \) of the drop size distribution.

moment_3float or array-like

The third moment of the drop size distribution, \( M_3 \), in units of [m⁻³·mm³] (number per cubic meter times diameter cubed).

moment_4float or array-like

The fourth moment of the drop size distribution, \( M_3 \), in units of [m⁻³·mm4].

Returns:

Nw – Normalized intercept parameter \( N_w \) in units of m⁻3·mm⁻¹.

Return type:

xarray.DataArray or float

References

Testud, J., S. Oury, R. A. Black, P. Amayenc, and X. Dou, 2001: The Concept of “Normalized” Distribution to Describe Raindrop spectrum: A Tool for Cloud Physics and Cloud Remote Sensing. J. Appl. Meteor. Climatol., 40, 1118-1140, https://doi.org/10.1175/1520-0450(2001)040<1118:TCONDT>2.0.CO;2

disdrodb.l2.empirical_dsd.get_partial_number_concentration(drop_number_concentration, minimum_diameter=0.0, maximum_diameter=None)[source][source]#

Compute number concentration over a specified diameter interval.

Parameters:

  • drop_number_concentration (xarray.DataArray) – Drop number concentration N(D) [m⁻³ mm⁻¹].

  • minimum_diameter (float) – Lower diameter bound (mm), exclusive.

  • maximum_diameter (float or None) – Upper diameter bound (mm), inclusive. If None, integrates over D > D_min.

Returns:

Number concentration [m⁻³] over the specified interval.

Return type:

xarray.DataArray

disdrodb.l2.empirical_dsd.get_partial_number_concentrations(drop_number_concentration, diameter_bin_edges)[source][source]#

Compute partial number concentrations over specified diameter intervals.

The input drop number concentration density, N(D), is first resampled onto the target diameter bins defined by diameter_bin_edges. The number concentration in each diameter interval is then obtained by multiplying the resampled density by the corresponding bin width.

Output variables are named using the convention N_<lower>_<upper>, where decimal points are replaced by p. For example, the variable N_0p5_1p0 represents the number concentration integrated over the diameter interval [0.5, 1.0).

Parameters:

  • drop_number_concentration (xarray.DataArray) – Drop number concentration density as a function of diameter, i.e. N(D). The diameter coordinate is expected to be expressed in millimeters.

  • diameter_bin_edges (array-like of float) – Monotonically increasing diameter bin edges in millimeters defining the target diameter intervals. For example, [0.5, 1.0, 1.5, 2.0] defines the intervals [0.5, 1.0), [1.0, 1.5), and [1.5, 2.0).

Returns:

Dataset containing one variable per diameter interval. Each variable is the partial number concentration integrated over the corresponding diameter range. Variable names follow the pattern N_<lower>_<upper>.

Return type:

xarray.Dataset

Notes

The partial number concentration in each interval [a, b) is computed as

\[\begin{split}N_{a-b} = \\int_a^b N(D) \\, dD\end{split}\]

where N(D) is the drop number concentration density.

Examples

>>> diameter_bin_edges = [0.5, 1.0, 1.5, 2.0]
>>> ds_partial = get_partial_number_concentrations(
...     drop_number_concentration=drop_number_concentration,
...     diameter_bin_edges=diameter_bin_edges,
... )
>>> list(ds_partial.data_vars)
['N_0p5_1p0', 'N_1p0_1p5', 'N_1p5_2p0']
disdrodb.l2.empirical_dsd.get_particle_counts_from_number_concentration(particle_number_concentration, velocity, diameter_bin_width, sample_interval, sampling_area)[source][source]#

Calculate particle counts from particle number concentration.

Parameters:

  • particle_number_concentration (xarray.DataArray) – Particle number concentration \(N(D)\) in m-3 mm-1.

  • velocity (xarray.DataArray) – Particle fall velocity \(v(D)\) in m s-1. The array can already be broadcast on the target dimensions.

  • diameter_bin_width (xarray.DataArray) – Diameter bin width \(\Delta D\) in millimeters.

  • sample_interval (float or xarray.DataArray) – Measurement interval \(\Delta t\) in seconds.

  • sampling_area (float or xarray.DataArray) – Effective sensor sampling area \(A\) in square meters.

Returns:

Particle counts \(n(D)\) or \(n(D, v)\) over the measurement interval.

Return type:

xarray.DataArray

Notes

The counts are reconstructed as

\[n(D) = N(D) \cdot v(D) \cdot A \cdot \Delta D \cdot \Delta t\]
disdrodb.l2.empirical_dsd.get_particle_number_concentration(particle_number, velocity, diameter_bin_width, sampling_area, sample_interval)[source][source]#

Calculate the volumetric particle number concentration \( N(D) \) per diameter class.

Computes the particle number concentration \( N(D) \) [m⁻³·mm⁻¹] for each diameter class based on the measured particle counts and sensor parameters. This represents the number of particles per unit volume per unit diameter interval. It is also referred to as the particle size distribution N(D) per cubic metre per millimetre [m-3 mm-1]

Parameters:

  • particle_number (xarray.DataArray) – Array of particle counts \( n(D) or n(D,v) \) per diameter (and velocity if available) bins over the measurement interval.

  • velocity (xarray.DataArray) – Array of particle fall velocities \( v(D) \) corresponding to each diameter bin in meters per second (m/s). Typically the estimated fall velocity is used. But one can also pass the velocity bin center of the optical disdrometer, which get broadcasted along the diameter bin dimension.

  • diameter_bin_width (xarray.DataArray) – Width of each diameter bin \( \Delta D \) in millimeters (mm).

  • sample_interval (float or xarray.DataArray) – Time over which the particles are counted \( \Delta t \) in seconds (s).

  • sampling_area (float or xarray.DataArray) – The effective sampling area \( A \) of the sensor in square meters (m²).

Returns:

particle_number_concentration – Array of particle number concentrations \( N(D) \) in m⁻³·mm⁻¹, representing the number of particles per unit volume per unit diameter interval.

Return type:

xarray.DataArray or numpy.ndarray

Notes

The particle number concentration \( N(D) \) is calculated using:

\[\begin{split}N(D) = \frac{n(D)}{A_{\text{eff}}(D) \\cdot \\Delta D \\cdot \\Delta t \\cdot v(D)}\end{split}\]

where:

  • \( n(D,v) \): Number of particles counted in diameter (and velocity) bins.

  • \( A_{text{eff}}(D) \): Effective sampling area of the sensor for diameter \( D \) in square meters (m²).

  • \( \Delta D \): Diameter bin width in millimeters (mm).

  • \( \Delta t \): Measurement interval in seconds (s).

  • \( v(D) \): Fall velocity of particles in diameter bin \( D \) in meters per second (m/s).

The effective sampling area \( A_{text{eff}}(D) \) depends on the sensor and may vary with particle diameter.

disdrodb.l2.empirical_dsd.get_quantile_volume_drop_diameter(drop_number_concentration, diameter, diameter_bin_width, fraction, water_density=1000)[source][source]#

Compute the diameter corresponding to a specified fraction of the cumulative liquid water content (LWC).

This function calculates the diameter ( D_f ) at which the cumulative LWC reaches a specified fraction ( f ) of the total LWC for each drop size distribution (DSD). When ( f = 0.5 ), it computes the median volume drop diameter.

Parameters:

  • drop_number_concentration (xarray.DataArray) – The drop number concentration ( N(D) ) for each diameter bin, typically in units of number per cubic meter per millimeter (m⁻³·mm⁻¹).

  • diameter (xarray.DataArray) – The equivalent volume diameters ( D ) of the drops in each bin, in meters (m).

  • diameter_bin_width (xarray.DataArray) – The width ( Delta D ) of each diameter bin, in millimeters (mm).

  • fraction (float or numpy.ndarray) – The fraction ( f ) of the total liquid water content to compute the diameter for. Default is 0.5, which computes the median volume diameter (D50). For other percentiles, use 0.1 for D10, 0.9 for D90, etc. Values must be between 0 and 1 (exclusive).

  • water_density (float, optional) – The density of water in kg/m^3. The default is 1000 kg/m3.

Returns:

D_f – The diameter ( D_f ) corresponding to the specified fraction ( f ) of cumulative LWC, in millimeters (mm). For fraction=0.5, this is the median volume drop diameter D50.

Return type:

xarray.DataArray

Notes

The calculation involves computing the cumulative sum of the liquid water content contributed by each diameter bin and finding the diameter at which the cumulative sum reaches the specified fraction ( f ) of the total liquid water content.

Linear interpolation is used between the two diameter bins where the cumulative LWC crosses the target LWC fraction.

disdrodb.l2.empirical_dsd.get_rain_accumulation(rain_rate, sample_interval)[source][source]#

Calculate the total rain accumulation over a specified time period.

Parameters:

  • rain_rate (float or array-like) – The rain rate in millimeters per hour (mm/h).

  • sample_interval (int) – The time over which to accumulate rain, specified in seconds.

Returns:

The total rain accumulation in millimeters (mm) over the specified time period.

Return type:

float or numpy.ndarray

disdrodb.l2.empirical_dsd.get_rain_rate(drop_number_concentration, velocity, diameter, diameter_bin_width)[source][source]#

Compute the rain rate \( R \) [mm/h] based on the drop size distribution and raindrop velocities.

Calculates the rain rate by integrating over the drop size distribution (DSD), considering the volume of water falling per unit time and area.

Parameters:

  • drop_number_concentration (xarray.DataArray) – Array of drop number concentrations \( N(D) \) in m⁻³·mm⁻¹.

  • velocity (xarray.DataArray) – Array of drop fall velocities \( v(D) \) corresponding to each diameter bin in meters per second (m/s).

  • diameter (xarray.DataArray) – Array of drop diameters \( D \) in meters (m).

  • diameter_bin_width (xarray.DataArray) – Width of each diameter bin \( \Delta D \) in millimeters (mm).

Returns:

rain_rate – The rain rate \( R \) in millimeters per hour (mm/h), representing the volume of water falling per unit area per unit time.

Return type:

xarray.DataArray

Notes

The rain rate \( R \) is calculated using:

\[\begin{split}R = \frac{\\pi}{6} \times 10^{-3} \times 3600 \times \\sum_{\text{bins}} N(D) \\cdot v(D) \\cdot D^3 \\cdot \\Delta D\end{split}\]

where:

  • \( N(D) \): Drop number concentration [m⁻³·mm⁻¹].

  • \( v(D) \): Fall velocity of drops in diameter bin \( D \) [m/s].

  • \( D \): Drop diameter [mm].

  • \( \Delta D \): Diameter bin width [mm].

  • The factor \( frac{\pi}{6} \) converts the diameter cubed to volume of a sphere.

  • The factor \( 10^{-3} \) converts from mm³ to m³.

  • The factor \( 3600 \) converts from seconds to hours.

disdrodb.l2.empirical_dsd.get_rain_rate_contribution(drop_number_concentration, velocity, diameter, diameter_bin_width)[source][source]#

Compute the rain rate contribution per diameter class.

Parameters:

  • drop_number_concentration (xarray.DataArray) – Array of drop number concentrations \( N(D) \) in m⁻³·mm⁻¹.

  • velocity (xarray.DataArray) – Array of drop fall velocities \( v(D) \) corresponding to each diameter bin in meters per second (m/s).

  • diameter (xarray.DataArray) – Array of drop diameters \( D \) in meters (m).

  • diameter_bin_width (xarray.DataArray) – Width of each diameter bin \( \Delta D \) in millimeters (mm).

Returns:

The rain rate contribution percentage per diameter class.

Return type:

xarray.DataArray

disdrodb.l2.empirical_dsd.get_rain_rate_from_drop_counts(drop_counts, sampling_area, diameter, sample_interval)[source][source]#

Compute the rain rate \( R \) [mm/h] based on the drop size distribution.

Drop velocities are not required to estimate rain rate from drop counts!

This function calculates the rain rate by integrating over the drop size distribution (DSD), considering the volume of water falling per unit time and area. It uses the number of drops counted in each diameter class, the effective sampling area of the sensor, the diameters of the drops, and the time interval over which the drops are counted.

Parameters:

  • drop_counts (xarray.DataArray) – Array representing the number of drops per diameter class. Passing the drop number array n(D, v) is allowed, but velocity information is not exploited. The derived rain rate will be the same as if n(D) was passed.

  • sample_interval (float or xarray.DataArray) – The time duration over which drops are counted \( \Delta t \) in seconds (s).

  • sampling_area (float or xarray.DataArray) – The effective sampling area \( A \) of the sensor in square meters (m²).

  • diameter (xarray.DataArray) – Array of drop diameters \( D \) in meters (m).

Returns:

rain_rate – The computed rain rate \( R \) in millimeters per hour (mm/h), which represents the volume of water falling per unit area per unit time.

Return type:

xarray.DataArray

Notes

The rain rate \( R \) is calculated using the following formula:

\[ \begin{align}\begin{aligned}\begin{split}R = \frac{\\pi}{6} \times 10^{3} \times 3600 \times \\sum_{\text{bins}} n(D) \cdot A(D) \cdot D^3 \cdot \\Delta t\end{split}\\\begin{split} = \\pi \times 0.6 \times 10^{6} \times \\sum_{\text{bins}} n(D) \cdot A(D) \cdot D^3 \cdot \\Delta t\end{split}\\\begin{split} = \\pi \times 6 \times 10^{5} \times \\sum_{\text{bins}} n(D) \cdot A(D) \cdot D^3 \cdot \\Delta t\end{split}\end{aligned}\end{align} \]

Where: - \( n(D) \) is the number of drops in each diameter class. - \( A(D) \) is the effective sampling area. - \( D \) is the drop diameter. - \( \Delta t \) is the time interval for drop counts.

This formula incorporates a conversion factor to express the rain rate in millimeters per hour.

In the literature, when the diameter is expected in millimeters, the formula is given as: .. math:

R = \\pi  \times {6} \times 10^{-4}  \times
\\sum_{\text{bins}} n(D) \cdot A(D) \cdot D^3 \cdot \\Delta t
disdrodb.l2.empirical_dsd.get_rain_rate_spectrum(drop_number_concentration, velocity, diameter)[source][source]#

Compute the rain rate per diameter class.

It represents the rain rate as a function of raindrop diameter. The total rain rate can be obtained by multiplying the spectrum with the diameter bin width and summing over the diameter bins.

Parameters:

  • drop_number_concentration (xarray.DataArray) – Array of drop number concentrations \( N(D) \) in m⁻³·mm⁻¹.

  • velocity (xarray.DataArray) – Array of drop fall velocities \( v(D) \) corresponding to each diameter bin in meters per second (m/s).

  • diameter (xarray.DataArray) – Array of drop diameters \( D \) in meters (m).

Returns:

The rain rate spectrum in millimeters per hour per mm, representing the volume of water falling per unit area per unit time per unit diameter.

Return type:

xarray.DataArray

disdrodb.l2.empirical_dsd.get_sampling_area(sensor_name)[source][source]#

Return the sampling area in m2 of the disdrometer.

disdrodb.l2.empirical_dsd.get_std_volume_drop_diameter(moment_3, moment_4, moment_5)[source][source]#

Calculate the standard deviation of the mass-weighted drop diameter (σₘ).

This parameter is often also referred as the mass spectrum standard deviation. It quantifies the spread or variability of DSD.

If drops are recorded in just one bin, the standard deviation of the mass-weighted drop diameter is set to 0. If no drops are recorded, the output values is NaN.

Parameters:

  • drop_number_concentration (xarray.DataArray) – The drop number concentration \( N(D) \) for each diameter bin, typically in units of number per cubic meter per millimeter (m⁻³·mm⁻¹).

  • diameter (xarray.DataArray) – The equivalent volume diameters \( D \) of the drops in each bin, in meters (m).

  • diameter_bin_width (xarray.DataArray) – The width \( \Delta D \) of each diameter bin, in millimeters (mm).

  • mean_volume_diameter (xarray.DataArray) – The mean volume diameter \( D_m \), in millimeters (mm). This is typically computed using the third and fourth moments or directly from the DSD.

Returns:

sigma_m – The standard deviation of the mass-weighted drop diameter, \( \sigma_m \), in millimeters (mm).

Return type:

xarray.DataArray or float

Notes

The standard deviation of the mass-weighted drop diameter is calculated using the formula:

\[\begin{split}\\sigma_m = \\sqrt{\frac{\\sum [N(D) \\cdot (D - D_m)^2 \\cdot D^3 \\cdot \\Delta D]}{\\sum [N(D) \\cdot D^3 \\cdot \\Delta D]}}\end{split}\]

where:

  • \( N(D) \) is the drop number concentration for diameter \( D \) [m⁻³·mm⁻¹].

  • \( D \) is the drop diameter [mm].

  • \( D_m \) is the mean volume diameter [mm].

  • \( \Delta D \) is the diameter bin width [mm].

  • The numerator computes the weighted variance of diameters.

  • The weighting factor \( D^3 \) accounts for mass (since mass ∝ \( D^3 \)).

Physical Interpretation:

  • A smaller \( \sigma_m \) indicates that the mass is concentrated around the mean mass-weighted diameter, implying less variability in drop sizes.

  • A larger \( \sigma_m \) suggests a wider spread of drop sizes contributing to the mass, indicating greater variability.

References

  • Smith, P. L., Johnson, R. W., & Kliche, D. V. (2019). On Use of the Standard Deviation of the Mass Distribution as a Parameter in Raindrop Size Distribution Functions. Journal of Applied Meteorology and Climatology, 58(4), 787-796. https://doi.org/10.1175/JAMC-D-18-0086.1

  • Williams, C. R., and Coauthors, 2014: Describing the Shape of Raindrop Size Distributions Using Uncorrelated Raindrop Mass Spectrum Parameters. J. Appl. Meteor. Climatol., 53, 1282-1296, https://doi.org/10.1175/JAMC-D-13-076.1.

disdrodb.l2.empirical_dsd.get_total_number_concentration(drop_number_concentration, diameter_bin_width)[source][source]#

Compute the total number concentration \( N_t \) from the drop size distribution.

Calculates the total number concentration \( N_t \) [m⁻³] by integrating the drop number concentration over all diameter bins.

Parameters:

  • drop_number_concentration (xarray.DataArray) – Array of drop number concentrations \( N(D) \) in m⁻³·mm⁻¹.

  • diameter_bin_width (xarray.DataArray) – Width of each diameter bin \( \Delta D \) in millimeters (mm).

Returns:

total_number_concentration – Total number concentration \( N_t \) in m⁻³, representing the total number of drops per unit volume.

Return type:

xarray.DataArray or numpy.ndarray

Notes

The total number concentration \( N_t \) is calculated by integrating over the diameter bins:

\[\begin{split}N_t = \\sum_{\text{bins}} N(D) \\cdot \\Delta D\end{split}\]

where:

  • \( N(D) \): Drop number concentration in each diameter bin [m⁻³·mm⁻¹].

  • \( \Delta D \): Diameter bin width in millimeters (mm).

disdrodb.l2.empirical_dsd.identify_partial_number_concentrations_variables(obj)[source][source]#

Identify partial number concentrations variable names.

disdrodb.l2.processing module#

Implement DISDRODB L2 processing.

disdrodb.l2.processing.check_l2e_input_dataset(ds)[source][source]#

Check dataset validity for L2E production.

disdrodb.l2.processing.check_l2m_input_dataset(ds)[source][source]#

Check dataset validity for L2M production.

disdrodb.l2.processing.define_rain_spectrum_mask(drop_number, fall_velocity_lower, fall_velocity_upper, above_velocity_fraction=None, above_velocity_tolerance=None, below_velocity_fraction=None, below_velocity_tolerance=None, maintain_drops_smaller_than=1, maintain_drops_slower_than=2.5, maintain_smallest_drops=False)[source][source]#

Define a mask for the drop spectrum based on fall velocity thresholds.

Parameters:

  • drop_number (xarray.DataArray) – Array of drop counts per diameter and velocity bins.

  • fall_velocity_lower (array-like) – The expected terminal fall velocities lower bound for rain drops of given size interval.

  • fall_velocity_upper (array-like) – The expected terminal fall velocities upper bound for rain drops of given size interval.

  • above_velocity_fraction (float, optional) – Fraction of terminal fall velocity above which rain drops are considered too fast. Either specify above_velocity_fraction or above_velocity_tolerance.

  • above_velocity_tolerance (float, optional) – Absolute tolerance above which rain drops terminal fall velocities are considered too fast. Either specify above_velocity_fraction or above_velocity_tolerance.

  • below_velocity_fraction (float, optional) – Fraction of terminal fall velocity below which rain drops are considered too slow. Either specify below_velocity_fraction or below_velocity_tolerance.

  • below_velocity_tolerance (float, optional) –

    Absolute tolerance below which rain drops terminal fall velocities are considered too slow.

    Either specify below_velocity_fraction or below_velocity_tolerance.

  • maintain_smallest (bool, optional) – If True, ensures that the small rain drops in the spectrum are retained in the mask. The smallest rain drops are characterized by maintain_drops_smaller_than and maintain_drops_slower_than arguments. Defaults to False.

  • maintain_drops_smaller_than (float, optional) – The diameter threshold to use for keeping the smallest rain drop. Defaults to 1 mm.

  • maintain_drops_slower_than (float, optional) – The fall velocity threshold to use for keeping the smallest rain drops. Defaults to 2.5 m/s.

Returns:

A boolean mask array indicating valid bins according to the specified criteria.

Return type:

xarray.DataArray

disdrodb.l2.processing.define_velocity_array(ds, spectrum='drop_number')[source][source]#

Create the fall velocity DataArray using various methods.

If ‘velocity_bin_center’ is a dimension in the dataset, returns a Dataset with ‘measured_velocity’, ‘average_velocity’, and ‘fall_velocity’ as variables. Otherwise, returns the ‘fall_velocity’ DataArray from the input dataset.

Parameters:

ds (xarray.Dataset) – The input dataset containing velocity variables.

Returns:

velocity

Return type:

xarray.DataArray

disdrodb.l2.processing.generate_l2_radar(ds, frequency=None, num_points=1024, diameter_min=0, diameter_max=10, canting_angle_std=7, axis_ratio_model='Thurai2007', permittivity_model='Turner2016', water_temperature=10, elevation_angle=0, parallel=True)[source][source]#

Simulate polarimetric radar variables from empirical drop number concentration or the estimated PSD.

Parameters:

  • ds (xarray.Dataset) – Dataset containing the drop number concentration variable or the PSD parameters.

  • frequency (str, float, or list of str or float, optional) – Frequencies in GHz for which to compute the radar parameters. Alternatively, also strings can be used to specify common radar frequencies. If None, the common radar frequencies will be used. See disdrodb.scattering.available_radar_bands().

  • num_points (int or list of int, optional) – Number of bins into which discretize the PSD.

  • diameter_min (float or list of float, optional) – Minimum diameter. The default value is 0 mm.

  • diameter_max (float or list of float, optional) – Maximum diameter. The default value is 10 mm.

  • canting_angle_std (float or list of float, optional) – Standard deviation of the canting angle. The default value is 7.

  • axis_ratio_model (str or list of str, optional) – Models to compute the axis ratio. The default model is Thurai2007. See available models with disdrodb.scattering.available_axis_ratio_models().

  • permittivity_model (str or list of str, optional) – Permittivity model to use to compute the refractive index and the rayleigh_dielectric_factor. The default is Turner2016. See available models with disdrodb.scattering.available_permittivity_models().

  • water_temperature (float or list of float, optional) – Water temperature in degree Celsius to be used in the permittivity model. The default is 10 degC.

  • elevation_angle (float or list of float, optional) – Radar elevation angles in degrees. Specify 90 degrees for vertically pointing radars. The default is 0 degrees.

  • parallel (bool, optional) – Whether to compute radar variables in parallel. The default value is True.

Returns:

Dataset containing the computed radar parameters.

Return type:

xarray.Dataset

disdrodb.l2.processing.generate_l2e(ds, ds_env=None, compute_spectra=False, compute_percentage_contribution=False, compute_partial_number_concentrations=False, partial_number_concentration_bins=(0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8), minimum_ndrops=1, minimum_nbins=1, minimum_rain_rate=0.01, minimum_diameter=0, maximum_diameter=10, minimum_velocity=0, maximum_velocity=12, keep_mixed_precipitation=False, fall_velocity_model='Beard1976', above_velocity_fraction=0.5, above_velocity_tolerance=None, below_velocity_fraction=0.5, below_velocity_tolerance=None, maintain_drops_smaller_than=1, maintain_drops_slower_than=2.5, maintain_smallest_drops=True, remove_splashing_drops=True)[source][source]#

Generate the DISDRODB L2E dataset from the DISDRODB L1 dataset.

Parameters:

  • ds (xarray.Dataset) –

    DISDRODB L1 dataset. Alternatively, a xarray dataset with at least:

    • variables: raw_drop_number

    • dimension: DIAMETER_DIMENSION

    • coordinates: diameter_bin_center, diameter_bin_width, sample_interval

    • attributes: sensor_name

  • ds_env (xarray.Dataset, optional) – Environmental dataset used for fall velocity and water density estimates. If None, a default environment dataset will be loaded.

  • fall_velocity_model (str, optional) – Model name to estimate drop fall velocity. The default method is "Beard1976".

  • minimum_diameter (float, optional) – Minimum diameter for filtering. The default value is 0 mm.

  • maximum_diameter (float, optional) – Maximum diameter for filtering. The default value is 10 mm.

  • minimum_velocity (float, optional) – Minimum velocity for filtering. The default value is 0 m/s.

  • maximum_velocity (float, optional) – Maximum velocity for filtering. The default value is 12 m/s.

  • above_velocity_fraction (float, optional) – Fraction of drops above velocity threshold. The default value is 0.5.

  • above_velocity_tolerance (float or None, optional) – Tolerance for above velocity filtering. The default value is None.

  • below_velocity_fraction (float, optional) – Fraction of drops below velocity threshold. The default value is 0.5.

  • below_velocity_tolerance (float or None, optional) – Tolerance for below velocity filtering. The default value is None.

  • maintain_drops_smaller_than (float, optional) – Threshold for small diameter drops. The default value is 1.

  • maintain_drops_slower_than (float, optional) – Threshold for small velocity drops. The default value is 2.5.

  • maintain_smallest_drops (bool, optional) – Whether to maintain the smallest drops. The default value is True.

  • remove_splashing_drops (bool, optional) – Whether to mask splashing drops. The default value is True.

Returns:

DISDRODB L2E dataset.

Return type:

xarray.Dataset

disdrodb.l2.processing.generate_l2m(ds, psd_model, optimization=None, optimization_settings=None, diameter_min=0, diameter_max=10, diameter_spacing=0.05, ds_env=None, fall_velocity_model='Beard1976', minimum_ndrops=1, minimum_nbins=3, minimum_rain_rate=0.01, gof_metrics=True)[source][source]#

Generate the DISDRODB L2M dataset from a DISDRODB L2E dataset.

This function estimates PSD model parameters and successively computes DSD integral parameters. Optionally, radar variables at various bands are simulated using T-matrix simulations. Goodness-of-fit metrics of the PSD can also be optionally included into the output dataset.

Parameters:

  • ds (xarray.Dataset) – DISDRODB L2E dataset.

  • psd_model (str) – The PSD model to fit. See disdrodb.psd.available_psd_models().

  • ds_env (xarray.Dataset, optional) – Environmental dataset used for fall velocity and water density estimates. If None, a default environment dataset will be loaded.

  • diameter_min (float, optional) – Minimum PSD diameter. The default value is 0 mm.

  • diameter_max (float, optional) – Maximum PSD diameter. The default value is 8 mm.

  • diameter_spacing (float, optional) – PSD diameter spacing. The default value is 0.05 mm.

  • optimization (str, optional) – The fitting optimization procedure. Either “GS” (Grid Search), “ML (Maximum Likelihood) or “MOM” (Method of Moments).

  • optimization_settings (dict, optional) – Dictionary with arguments to customize the fitting procedure.

  • minimum_nbins (int) – Minimum number of bins with drops required to fit the PSD model. The default value is 5.

  • gof_metrics (bool, optional) – Whether to add goodness-of-fit metrics to the output dataset. The default is True.

Returns:

DISDRODB L2M dataset.

Return type:

xarray.Dataset

disdrodb.l2.processing.get_mask_contour(mask, x_dim='diameter_bin_center', y_dim='velocity_bin_center')[source][source]#

Extract exact stair-step boundary of True region from boolean DataArray.

disdrodb.l2.processing.get_spectrum_mask_boundary(ds, above_velocity_fraction=None, above_velocity_tolerance=None, below_velocity_fraction=None, below_velocity_tolerance=None, maintain_drops_smaller_than=1, maintain_drops_slower_than=2.5, maintain_smallest_drops=False, fall_velocity_model='Beard1976')[source][source]#

Return the boundary of the spectrum mask.

disdrodb.l2.processing.retrieve_drop_spectrum(ds, ds_env, above_velocity_fraction=None, above_velocity_tolerance=None, below_velocity_fraction=None, below_velocity_tolerance=None, maintain_drops_smaller_than=1, maintain_drops_slower_than=2.5, maintain_smallest_drops=False, remove_splashing_drops=True, fall_velocity_model='Beard1976')[source][source]#

Retrieve the drop spectrum from the DISDRODB L1 product.

disdrodb.l2.processing.select_timesteps_with_drops(ds, minimum_ndrops=0)[source][source]#

Select timesteps with at least the specified number of drops.

disdrodb.l2.processing.select_timesteps_with_minimum_nbins(ds, minimum_nbins)[source][source]#

Select timesteps with at least the specified number of diameter bins with drops.

disdrodb.l2.processing.select_timesteps_with_minimum_rain_rate(ds, minimum_rain_rate)[source][source]#

Select timesteps with at least the specified rain rate.

Module contents#

Module for DISDRODB L2 production.

disdrodb.l2.generate_l2_radar(ds, frequency=None, num_points=1024, diameter_min=0, diameter_max=10, canting_angle_std=7, axis_ratio_model='Thurai2007', permittivity_model='Turner2016', water_temperature=10, elevation_angle=0, parallel=True)[source][source]#

Simulate polarimetric radar variables from empirical drop number concentration or the estimated PSD.

Parameters:

  • ds (xarray.Dataset) – Dataset containing the drop number concentration variable or the PSD parameters.

  • frequency (str, float, or list of str or float, optional) – Frequencies in GHz for which to compute the radar parameters. Alternatively, also strings can be used to specify common radar frequencies. If None, the common radar frequencies will be used. See disdrodb.scattering.available_radar_bands().

  • num_points (int or list of int, optional) – Number of bins into which discretize the PSD.

  • diameter_min (float or list of float, optional) – Minimum diameter. The default value is 0 mm.

  • diameter_max (float or list of float, optional) – Maximum diameter. The default value is 10 mm.

  • canting_angle_std (float or list of float, optional) – Standard deviation of the canting angle. The default value is 7.

  • axis_ratio_model (str or list of str, optional) – Models to compute the axis ratio. The default model is Thurai2007. See available models with disdrodb.scattering.available_axis_ratio_models().

  • permittivity_model (str or list of str, optional) – Permittivity model to use to compute the refractive index and the rayleigh_dielectric_factor. The default is Turner2016. See available models with disdrodb.scattering.available_permittivity_models().

  • water_temperature (float or list of float, optional) – Water temperature in degree Celsius to be used in the permittivity model. The default is 10 degC.

  • elevation_angle (float or list of float, optional) – Radar elevation angles in degrees. Specify 90 degrees for vertically pointing radars. The default is 0 degrees.

  • parallel (bool, optional) – Whether to compute radar variables in parallel. The default value is True.

Returns:

Dataset containing the computed radar parameters.

Return type:

xarray.Dataset

disdrodb.l2.generate_l2e(ds, ds_env=None, compute_spectra=False, compute_percentage_contribution=False, compute_partial_number_concentrations=False, partial_number_concentration_bins=(0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8), minimum_ndrops=1, minimum_nbins=1, minimum_rain_rate=0.01, minimum_diameter=0, maximum_diameter=10, minimum_velocity=0, maximum_velocity=12, keep_mixed_precipitation=False, fall_velocity_model='Beard1976', above_velocity_fraction=0.5, above_velocity_tolerance=None, below_velocity_fraction=0.5, below_velocity_tolerance=None, maintain_drops_smaller_than=1, maintain_drops_slower_than=2.5, maintain_smallest_drops=True, remove_splashing_drops=True)[source][source]#

Generate the DISDRODB L2E dataset from the DISDRODB L1 dataset.

Parameters:

  • ds (xarray.Dataset) –

    DISDRODB L1 dataset. Alternatively, a xarray dataset with at least:

    • variables: raw_drop_number

    • dimension: DIAMETER_DIMENSION

    • coordinates: diameter_bin_center, diameter_bin_width, sample_interval

    • attributes: sensor_name

  • ds_env (xarray.Dataset, optional) – Environmental dataset used for fall velocity and water density estimates. If None, a default environment dataset will be loaded.

  • fall_velocity_model (str, optional) – Model name to estimate drop fall velocity. The default method is "Beard1976".

  • minimum_diameter (float, optional) – Minimum diameter for filtering. The default value is 0 mm.

  • maximum_diameter (float, optional) – Maximum diameter for filtering. The default value is 10 mm.

  • minimum_velocity (float, optional) – Minimum velocity for filtering. The default value is 0 m/s.

  • maximum_velocity (float, optional) – Maximum velocity for filtering. The default value is 12 m/s.

  • above_velocity_fraction (float, optional) – Fraction of drops above velocity threshold. The default value is 0.5.

  • above_velocity_tolerance (float or None, optional) – Tolerance for above velocity filtering. The default value is None.

  • below_velocity_fraction (float, optional) – Fraction of drops below velocity threshold. The default value is 0.5.

  • below_velocity_tolerance (float or None, optional) – Tolerance for below velocity filtering. The default value is None.

  • maintain_drops_smaller_than (float, optional) – Threshold for small diameter drops. The default value is 1.

  • maintain_drops_slower_than (float, optional) – Threshold for small velocity drops. The default value is 2.5.

  • maintain_smallest_drops (bool, optional) – Whether to maintain the smallest drops. The default value is True.

  • remove_splashing_drops (bool, optional) – Whether to mask splashing drops. The default value is True.

Returns:

DISDRODB L2E dataset.

Return type:

xarray.Dataset

disdrodb.l2.generate_l2m(ds, psd_model, optimization=None, optimization_settings=None, diameter_min=0, diameter_max=10, diameter_spacing=0.05, ds_env=None, fall_velocity_model='Beard1976', minimum_ndrops=1, minimum_nbins=3, minimum_rain_rate=0.01, gof_metrics=True)[source][source]#

Generate the DISDRODB L2M dataset from a DISDRODB L2E dataset.

This function estimates PSD model parameters and successively computes DSD integral parameters. Optionally, radar variables at various bands are simulated using T-matrix simulations. Goodness-of-fit metrics of the PSD can also be optionally included into the output dataset.

Parameters:

  • ds (xarray.Dataset) – DISDRODB L2E dataset.

  • psd_model (str) – The PSD model to fit. See disdrodb.psd.available_psd_models().

  • ds_env (xarray.Dataset, optional) – Environmental dataset used for fall velocity and water density estimates. If None, a default environment dataset will be loaded.

  • diameter_min (float, optional) – Minimum PSD diameter. The default value is 0 mm.

  • diameter_max (float, optional) – Maximum PSD diameter. The default value is 8 mm.

  • diameter_spacing (float, optional) – PSD diameter spacing. The default value is 0.05 mm.

  • optimization (str, optional) – The fitting optimization procedure. Either “GS” (Grid Search), “ML (Maximum Likelihood) or “MOM” (Method of Moments).

  • optimization_settings (dict, optional) – Dictionary with arguments to customize the fitting procedure.

  • minimum_nbins (int) – Minimum number of bins with drops required to fit the PSD model. The default value is 5.

  • gof_metrics (bool, optional) – Whether to add goodness-of-fit metrics to the output dataset. The default is True.

Returns:

DISDRODB L2M dataset.

Return type:

xarray.Dataset

Contents