disdrodb.l1 package#
Submodules#
disdrodb.l1.beard_model module#
Utilities to estimate the drop fall velocity using the Beard model.
- disdrodb.l1.beard_model.get_air_density(temperature, air_pressure, vapor_pressure, gas_constant_dry_air=287.04)[source][source]#
Computes the air density according to the equation of state for moist air.
Reference: Brutsaert 1982
- Parameters:
- Returns:
Air density in kg/m^3.
- Return type:
- disdrodb.l1.beard_model.get_air_dynamic_viscosity(temperature)[source][source]#
Computes the dynamic viscosity of dry air.
Reference: Beard 1977; Pruppacher & Klett 1978
- disdrodb.l1.beard_model.get_air_pressure_at_height(altitude, latitude, temperature, sea_level_air_pressure=101325, lapse_rate=0.0065, gas_constant_dry_air=287.04)[source][source]#
Computes the air pressure at a given height in a standard atmosphere.
According to the hypsometric formula of Brutsaert 1982; Ulaby et al. 1981
- Parameters:
altitude (float) – Altitude in meters.
latitude (float) – Latitude in degrees.
temperature (float) – Temperature at altitude in Kelvin.
sea_level_air_pressure (float, optional) – Standard atmospheric pressure at sea level in Pascals. The default is 101_325 Pascals.
lapse_rate (float, optional) – Standard atmospheric lapse rate in K/m. The default is 0.0065 K/m.
gas_constant_dry_air (float, optional) – Gas constant for dry air in J/(kg*K). The default is 287.04 J/(kg*K).
- Returns:
Air pressure in Pascals.
- Return type:
- disdrodb.l1.beard_model.get_air_temperature_at_height(altitude, sea_level_temperature, lapse_rate=0.0065)[source][source]#
Computes the air temperature at a given height in a standard atmosphere.
Reference: Brutsaert 1982; Ulaby et al. 1981
- disdrodb.l1.beard_model.get_drag_coefficient(diameter, air_density, water_density, fall_velocity, g=9.81)[source][source]#
Computes the drag coefficient for a raindrop.
- Parameters:
- Returns:
Drag coefficient of the raindrop.
- Return type:
- disdrodb.l1.beard_model.get_fall_velocity_beard_1976(diameter, temperature, air_density, water_density, g)[source][source]#
Computes the terminal fall velocity of a raindrop in still air.
Reference: Beard 1976; Pruppacher & Klett 1978
- Parameters:
- Returns:
Terminal fall velocity of the raindrop in m/s.
- Return type:
- disdrodb.l1.beard_model.get_gravitational_acceleration(latitude, altitude=0)[source][source]#
Computes gravitational acceleration at a given altitude and latitude.
- disdrodb.l1.beard_model.get_pure_water_compressibility(temperature)[source][source]#
Computes the isothermal compressibility of pure ordinary water.
Reference: Kell, Weast & Astle 1980
- disdrodb.l1.beard_model.get_pure_water_density(temperature)[source][source]#
Computes the density of pure water at standard pressure.
For temperatures above freezing uses Kell formulation. For temperatures below freezing use Dorsch & Boyd formulation.
References: Pruppacher & Klett 1978; Weast & Astle 1980
- disdrodb.l1.beard_model.get_pure_water_surface_tension(temperature)[source][source]#
Computes the surface tension of pure ordinary water against air.
Reference: Pruppacher & Klett 1978
- disdrodb.l1.beard_model.get_raindrop_reynolds_number(diameter, temperature, air_density, water_density, g)[source][source]#
Compute raindrop Reynolds number.
It quantifies the relative strength of the convective inertia and linear viscous forces acting on the drop at terminal velocity.
Estimates Reynolds number for drops with diameter between 19 um and 7 mm. Coefficients are taken from Table 1 of Beard 1976.
Reference: Beard 1976; Pruppacher & Klett 1978 See also Table A1 in Rahman et al., 2020.
- Parameters:
- Returns:
Reynolds number for the raindrop.
- Return type:
- disdrodb.l1.beard_model.get_vapor_actual_pressure(relative_humidity, temperature)[source][source]#
Computes the actual vapor pressure over water.
- disdrodb.l1.beard_model.get_vapor_actual_pressure_at_height(altitude, sea_level_temperature, sea_level_relative_humidity, sea_level_air_pressure=101325, lapse_rate=0.0065)[source][source]#
Computes the vapor pressure using Yamamoto’s exponential relationship.
Reference: Brutsaert 1982
- Parameters:
altitude (float) – Altitude in meters.
sea_level_temperature (float) – Standard temperature at sea level in Kelvin.
sea_level_relative_humidity (float) – Relative humidity at sea level. A value between 0 and 1.
sea_level_air_pressure (float, optional) – Standard atmospheric pressure at sea level in Pascals. The default is 101_325 Pascals.
lapse_rate (float, optional) – Standard atmospheric lapse rate in K/m. The default is 0.0065 K/m.
- Returns:
Vapor pressure in Pascals.
- Return type:
- disdrodb.l1.beard_model.get_vapor_saturation_pressure(temperature)[source][source]#
Computes the saturation vapor pressure over water as a function of temperature.
Use formulation and coefficients of Wexler (1976, 1977). References: Brutsaert 1982; Pruppacher & Klett 1978; Flatau & al. 1992
- disdrodb.l1.beard_model.get_water_density(temperature, air_pressure, sea_level_air_pressure=101325)[source][source]#
Computes the density of water according to Weast & Astle 1980.
- Parameters:
temperature (float) – Temperature in Kelvin.
air_pressure (float) – Air pressure in Pascals.
sea_level_air_pressure (float) – Standard atmospheric pressure at sea level in Pascals. The default is 101_325 Pascal.
freezing_temperature (float, optional) – Freezing temperature of water in Kelvin. The default is 273.15 K.
- Returns:
Water density in kg/m^3.
- Return type:
- disdrodb.l1.beard_model.retrieve_air_dynamic_viscosity(ds_env)[source][source]#
Retrieve air dynamic viscosity.
- disdrodb.l1.beard_model.retrieve_fall_velocity(diameter, altitude, latitude, temperature, relative_humidity, air_pressure=None, sea_level_air_pressure=101325, gas_constant_dry_air=287.04, lapse_rate=0.0065)[source][source]#
Computes the terminal fall velocity and drag coefficients for liquid raindrops.
- Parameters:
diameter (float) – Diameter of the raindrop in meters.
altitude (float) – Altitude in meters.
temperature (float) – Temperature in Kelvin.
relative_humidity (float) – Relative humidity. A value between 0 and 1.
latitude (float) – Latitude in degrees.
air_pressure (float) – Air pressure in Pascals. If None, air_pressure at altitude is inferred assuming a standard atmospheric pressure at sea level.
sea_level_air_pressure (float) – Standard atmospheric pressure at sea level in Pascals. The default is 101_325 Pascal.
gas_constant_dry_air (float, optional) – Gas constant for dry air in J/(kg*K). The default is 287.04 is J/(kg*K).
lapse_rate (float, optional) – Standard atmospheric lapse rate in K/m. The default is 0.0065 K/m.
- Returns:
Terminal fall velocity and drag coefficients for liquid raindrops.
- Return type:
disdrodb.l1.fall_velocity module#
Theoretical models to estimate the raindrop fall velocity based on drop diameter in mm.
- disdrodb.l1.fall_velocity.available_raindrop_fall_velocity_models()[source][source]#
Return a list of the available raindrop fall velocity models.
- disdrodb.l1.fall_velocity.check_raindrop_fall_velocity_model(model)[source][source]#
Check validity of the specified raindrop fall velocity model.
- disdrodb.l1.fall_velocity.get_fall_velocity_atlas_1973(diameter)[source][source]#
Compute the fall velocity of raindrops using the Atlas et al. (1973) relationship.
- Parameters:
diameter (array-like) – Diameter of the raindrops in millimeters.
- Returns:
fall_velocity – Fall velocities corresponding to the input diameters, in meters per second.
- Return type:
array-like
References
Atlas, D., Srivastava, R. C., & Sekhon, R. S. (1973). Doppler radar characteristics of precipitation at vertical incidence. Reviews of Geophysics, 11(1), 1-35. https://doi.org/10.1029/RG011i001p00001
Gunn, R., & Kinzer, G. D. (1949). The terminal velocity of fall for water droplets in stagnant air. Journal of Meteorology, 6(4), 243-248. https://doi.org/10.1175/1520-0469(1949)006<0243:TTVOFF>2.0.CO;2
- disdrodb.l1.fall_velocity.get_fall_velocity_beard_1976(diameter, ds_env)[source][source]#
Calculate the fall velocity of a particle using the Beard (1976) model.
- Parameters:
diameter (array-like) – Diameter of the raindrops in millimeters.
ds_env (xr.Dataset) – A dataset containing the following environmental variables: - ‘altitude’ : Altitude in meters (m). - ‘latitude’ : Latitude in degrees. - ‘temperature’ : Temperature in degrees Kelvin (K). - ‘relative_humidity’ : Relative humidity in percentage (%). - ‘sea_level_air_pressure’ : Sea level air pressure in Pascals (Pa). - ‘air_pressure’: Air pressure in Pascals (Pa). - ‘lapse_rate’ : Lapse rate in degrees Celsius per meter (°C/m).
- Returns:
fall_velocity – The calculated fall velocities of the raindrops.
- Return type:
array-like
- disdrodb.l1.fall_velocity.get_fall_velocity_brandes_2002(diameter)[source][source]#
Compute the fall velocity of raindrops using the Brandes et al. (2002) relationship.
- Parameters:
diameter (array-like) – Diameter of the raindrops in millimeters.
- Returns:
fall_velocity – Fall velocities in meters per second.
- Return type:
array-like
References
Brandes, E. A., Zhang, G., & Vivekanandan, J. (2002). Experiments in rainfall estimation with a polarimetric radar in a subtropical environment. Journal of Applied Meteorology, 41(6), 674-685. https://doi.org/10.1175/1520-0450(2002)041<0674:EIREWA>2.0.CO;2
- disdrodb.l1.fall_velocity.get_fall_velocity_uplinger_1981(diameter)[source][source]#
Compute the fall velocity of raindrops using Uplinger (1981) relationship.
- Parameters:
diameter (array-like) – Diameter of the raindrops in millimeters. Valid for diameters between 0.1 mm and 7 mm.
- Returns:
fall_velocity – Fall velocities in meters per second.
- Return type:
array-like
References
Uplinger, C. W. (1981). A new formula for raindrop terminal velocity. In Proceedings of the 20th Conference on Radar Meteorology (pp. 389-391). AMS.
- disdrodb.l1.fall_velocity.get_fall_velocity_van_dijk_2002(diameter)[source][source]#
Compute the fall velocity of raindrops using van Dijk et al. (2002) relationship.
- Parameters:
diameter (array-like) – Diameter of the raindrops in millimeters.
- Returns:
fall_velocity – Fall velocities in meters per second.
- Return type:
array-like
References
van Dijk, A. I. J. M., Bruijnzeel, L. A., & Rosewell, C. J. (2002). Rainfall intensity-kinetic energy relationships: a critical literature appraisal. Journal of Hydrology, 261(1-4), 1-23. https://doi.org/10.1016/S0022-1694(02)00020-3
- disdrodb.l1.fall_velocity.get_raindrop_fall_velocity(diameter, model, ds_env=None)[source][source]#
Calculate the fall velocity of raindrops based on their diameter.
- Parameters:
diameter (array-like) – The diameter of the raindrops in millimeters.
model (str) – The model to use for calculating the raindrop fall velocity. Must be one of the following: ‘Atlas1973’, ‘Beard1976’, ‘Brandes2002’, ‘Uplinger1981’, ‘VanDijk2002’.
ds_env (xr.Dataset, optional) – Only required if model is ‘Beard1976’. A dataset containing the following environmental variables: - ‘altitude’ (m) - ‘latitude’ (°) - ‘temperature’ : Temperature in degrees Kelvin (K). - ‘relative_humidity’ : Relative humidity. A value between 0 and 1. - ‘sea_level_air_pressure’ : Sea level air pressure in Pascals (Pa). - ‘lapse_rate’ : Lapse rate in degrees Celsius per meter (°C/m). If not specified, sensible default values are used.
- Returns:
fall_velocity – The calculated raindrop fall velocities per diameter.
- Return type:
xr.DataArray
Notes
The ‘Beard1976’ model requires additional environmental parameters. These parameters can be provided through the ds_env argument. If not provided, default values are be used.
For D < 0.12, Atlas1973 relationship results output V = 0 m/s ! For D < 0.05, VanDijk2002 relationship results output V = 0 m/s ! For D < 0.02, Brandes relationship results output V = 0 m/s !
- disdrodb.l1.fall_velocity.get_raindrop_fall_velocity_from_ds(ds, ds_env=None, model='Beard1976')[source][source]#
Compute the raindrop fall velocity.
- Parameters:
ds (xarray.Dataset) – DISDRODB dataset with the
'diameter_bin_center'coordinate. The'altitude'and'latitude'coordinates are used ifmodel='Beard1976'.model (str, optional) – Model to compute rain drop fall velocity. The default model is
"Beard1976".ds_env (xr.Dataset, optional) – Only required if model is ‘Beard1976’. A dataset containing the following environmental variables: - ‘temperature’ : Temperature in degrees Kelvin (K). - ‘relative_humidity’ : Relative humidity. A value between 0 and 1. - ‘sea_level_air_pressure’ : Sea level air pressure in Pascals (Pa). - ‘lapse_rate’ : Lapse rate in degrees Celsius per meter (°C/m). If not specified, sensible default values are used.
- Returns:
Rain drop fall velocity DataArray.
- Return type:
Notes
The ‘Beard1976’ model requires additional environmental parameters. These parameters can be provided through the ds_env argument. If not provided, default values are be used.
For D < 0.12, Atlas1973 relationship results output V = 0 m/s For D < 0.05, VanDijk2002 relationship results output V = 0 m/s For D < 0.02, Brandes relationship results output V = 0 m/s
- disdrodb.l1.fall_velocity.get_raindrop_fall_velocity_model(model)[source][source]#
Return the specified raindrop fall velocity model.
- Parameters:
model (str) – The model to use for calculating the rain drop fall velocity. Available models are: ‘Atlas1973’, ‘Beard1976’, ‘Brandes2002’, ‘Uplinger1981’, ‘VanDijk2002’.
- Returns:
A function which compute the raindrop fall velocity model given the rain drop diameter in mm.
- Return type:
callable
Notes
This function serves as a wrapper to various raindrop fall velocity models. It returns the appropriate model based on the model parameter.
disdrodb.l1.filters module#
Utilities for filtering the disdrometer raw drop spectra.
- disdrodb.l1.filters.define_raindrop_spectrum_mask(drop_number, fall_velocity, above_velocity_fraction=None, above_velocity_tolerance=None, below_velocity_fraction=None, below_velocity_tolerance=None, small_diameter_threshold=1, small_velocity_threshold=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 (array-like) – The expected terminal fall velocities for rain drops of given sizes.
above_velocity_fraction (float, optional) – Fraction of terminal fall velocity above which rain drops are considered too fast. Either specify
above_velocity_fractionorabove_velocity_tolerance.above_velocity_tolerance (float, optional) – Absolute tolerance above which rain drops terminal fall velocities are considered too fast. Either specify
above_velocity_fractionorabove_velocity_tolerance.below_velocity_fraction (float, optional) – Fraction of terminal fall velocity below which rain drops are considered too slow. Either specify
below_velocity_fractionorbelow_velocity_tolerance.below_velocity_tolerance (float, optional) –
- Absolute tolerance below which rain drops terminal fall velocities are considered too slow.
Either specify
below_velocity_fractionorbelow_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
small_diameter_thresholdandsmall_velocity_thresholdarguments. Defaults to False.small_diameter_threshold (float, optional) – The diameter threshold to use for keeping the smallest rain drop. Defaults to 1 mm.
small_velocity_threshold (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:
- disdrodb.l1.filters.filter_diameter_bins(ds, minimum_diameter=None, maximum_diameter=None)[source][source]#
Filter the dataset to include only diameter bins within specified bounds.
- Parameters:
ds (xarray.Dataset) – The dataset containing diameter bin data.
minimum_diameter (float, optional) – The minimum diameter to be included, in millimeters. Defaults to the minimum value in ds[“diameter_bin_lower”].
maximum_diameter (float, optional) – The maximum diameter to be included, in millimeters. Defaults to the maximum value in ds[“diameter_bin_upper”].
- Returns:
The filtered dataset containing only the specified diameter bins.
- Return type:
- disdrodb.l1.filters.filter_velocity_bins(ds, minimum_velocity=None, maximum_velocity=None)[source][source]#
Filter the dataset to include only velocity bins within specified bounds.
- Parameters:
ds (xarray.Dataset) – The dataset containing velocity bin data.
minimum_velocity (float, optional) – The minimum velocity to include in the filter, in meters per second. Defaults to the minimum value in ds[“velocity_bin_lower”].
maximum_velocity (float, optional) – The maximum velocity to include in the filter, in meters per second. Defaults to the maximum value in ds[“velocity_bin_upper”].
- Returns:
The filtered dataset containing only the specified velocity bins.
- Return type:
disdrodb.l1.processing module#
Core functions for DISDRODB L1 production.
- disdrodb.l1.processing.generate_l1(ds, fall_velocity_model='Beard1976', minimum_diameter=0, maximum_diameter=10, minimum_velocity=0, maximum_velocity=12, above_velocity_fraction=0.5, above_velocity_tolerance=None, below_velocity_fraction=0.5, below_velocity_tolerance=None, small_diameter_threshold=1, small_velocity_threshold=2.5, maintain_smallest_drops=True)[source][source]#
Generate DISDRODB L1 Dataset from DISDRODB L0C Dataset.
- Parameters:
ds (xarray.Dataset) – DISDRODB L0C dataset.
fall_velocity_model (str, optional) – Method to compute 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.small_diameter_threshold (float, optional) – Threshold for small diameter drops. The default value is 1.
small_velocity_threshold (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.
- Returns:
DISDRODB L1 dataset.
- Return type:
disdrodb.l1.resampling module#
Utilities for temporal resampling.
- disdrodb.l1.resampling.add_sample_interval(ds, sample_interval)[source][source]#
Add a sample_interval coordinate to the dataset.
- Parameters:
ds (xarray.Dataset) – The input dataset to which the sample_interval coordinate will be added.
sample_interval (int or float) – The dataset sample interval in seconds.
- Returns:
The dataset with the added sample interval coordinate.
- Return type:
Notes
The function adds a new coordinate named ‘sample_interval’ to the dataset and updates the ‘measurement_interval’ attribute.
- disdrodb.l1.resampling.define_window_size(sample_interval, accumulation_interval)[source][source]#
Calculate the rolling window size based on sampling and accumulation intervals.
- Parameters:
- Returns:
The calculated window size as the number of sampling intervals required to cover the accumulation interval.
- Return type:
- Raises:
ValueError – If the accumulation interval is not a multiple of the sampling interval.
Examples
>>> define_window_size(60, 300) 5
>>> define_window_size(120, 600) 5
- disdrodb.l1.resampling.resample_dataset(ds, sample_interval, temporal_resolution)[source][source]#
Resample the dataset to a specified accumulation interval.
The output timesteps correspond to the starts of the periods over which the resampling operation has been performed !
- Parameters:
ds (xarray.Dataset) – The input dataset to be resampled.
sample_interval (int) – The sample interval (in seconds) of the input dataset.
temporal_resolution (str) – The desired temporal resolution for resampling. It should be a string representing the accumulation interval, e.g., “5MIN” for 5 minutes, “1H” for 1 hour, “30S” for 30 seconds, etc. Prefixed with “ROLL” for rolling resampling, e.g., “ROLL5MIN”.
- Returns:
The resampled dataset with updated attributes.
- Return type:
Notes
The function regularizes the dataset (infill possible missing timesteps) before performing the resampling operation.
Variables are categorized into those to be averaged, accumulated, minimized, and maximized.
Custom processing for quality flags and handling of NaNs is defined.
The function updates the dataset attributes and the sample_interval coordinate.
Module contents#
DISDRODB L1 module.
- disdrodb.l1.generate_l1(ds, fall_velocity_model='Beard1976', minimum_diameter=0, maximum_diameter=10, minimum_velocity=0, maximum_velocity=12, above_velocity_fraction=0.5, above_velocity_tolerance=None, below_velocity_fraction=0.5, below_velocity_tolerance=None, small_diameter_threshold=1, small_velocity_threshold=2.5, maintain_smallest_drops=True)[source][source]#
Generate DISDRODB L1 Dataset from DISDRODB L0C Dataset.
- Parameters:
ds (xarray.Dataset) – DISDRODB L0C dataset.
fall_velocity_model (str, optional) – Method to compute 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.small_diameter_threshold (float, optional) – Threshold for small diameter drops. The default value is 1.
small_velocity_threshold (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.
- Returns:
DISDRODB L1 dataset.
- Return type: