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)

Computes the air density according to the equation of state for moist air.

Reference: Brutsaert 1982

Parameters:

• temperature (float) – Temperature in Kelvin.

• air_pressure (float) – Air pressure in Pascals.

• vapor_pressure (float) – Vapor pressure in Pascals.

• 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 density in kg/m^3.

Return type:

float

disdrodb.l1.beard_model.get_air_dynamic_viscosity(temperature)

Computes the dynamic viscosity of dry air.

Reference: Beard 1977; Pruppacher & Klett 1978

Parameters:

temperature (float) – Temperature in Kelvin.

Returns:

Dynamic viscosity of dry air in kg/(m*s) (aka Pa*s).

Return type:

float

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)

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:

float

disdrodb.l1.beard_model.get_air_temperature_at_height(altitude, sea_level_temperature, lapse_rate=0.0065)

Computes the air temperature at a given height in a standard atmosphere.

Reference: Brutsaert 1982; Ulaby et al. 1981

Parameters:

• altitude (float) – Altitude in meters.

• sea_level_temperature (float) – Standard temperature at sea level in Kelvin.

• lapse_rate (float, optional) – Standard atmospheric lapse rate in K/m. The default is 0.0065 K/m.

Returns:

Air temperature in Kelvin.

Return type:

float

disdrodb.l1.beard_model.get_drag_coefficient(diameter, air_density, water_density, fall_velocity, g=9.81)

Computes the drag coefficient for a raindrop.

Parameters:

• diameter (float) – Diameter of the raindrop in meters.

• air_density (float) – Density of air in kg/m^3.

• water_density (float) – Density of water in kg/m^3.

• fall_velocity (float) – Terminal fall velocity of the raindrop in m/s.

• g (float) – Gravitational acceleration in m/s^2.

Returns:

Drag coefficient of the raindrop.

Return type:

float

disdrodb.l1.beard_model.get_fall_velocity_beard_1976(diameter, temperature, air_density, water_density, g)

Computes the terminal fall velocity of a raindrop in still air.

Reference: Beard 1976; Pruppacher & Klett 1978

Parameters:

• diameter (float) – Diameter of the raindrop in meters.

• temperature (float) – Temperature in Kelvin.

• air_density (float) – Density of air in kg/m^3.

• water_density (float) – Density of water in kg/m^3.

• g (float) – Gravitational acceleration in m/s^2.

Returns:

Terminal fall velocity of the raindrop in m/s.

Return type:

float

disdrodb.l1.beard_model.get_gravitational_acceleration(latitude, altitude=0)

Computes gravitational acceleration at a given altitude and latitude.

Parameters:

• altitude (float) – Altitude in meters. The default is 0 m (sea level).

• latitude (float) – Latitude in degrees.

Returns:

Gravitational acceleration in m/s^2.

Return type:

float

disdrodb.l1.beard_model.get_pure_water_compressibility(temperature)

Computes the isothermal compressibility of pure ordinary water.

Reference: Kell, Weast & Astle 1980

Parameters:

temperature (float) – Temperature in Kelvin.

Returns:

Compressibility of water in Pascals.

Return type:

float

disdrodb.l1.beard_model.get_pure_water_density(temperature)

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

Parameters:

temperature (float) – Temperature in Kelvin.

Returns:

Density of pure water in kg/m^3.

Return type:

float

disdrodb.l1.beard_model.get_pure_water_surface_tension(temperature)

Computes the surface tension of pure ordinary water against air.

Reference: Pruppacher & Klett 1978

Parameters:

temperature (float) – Temperature in Kelvin.

Returns:

Surface tension in N/m.

Return type:

float

disdrodb.l1.beard_model.get_raindrop_reynolds_number(diameter, temperature, air_density, water_density, g)

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

Parameters:

• diameter (float) – Diameter of the raindrop in meters.

• temperature (float) – Temperature in Kelvin.

• air_density (float) – Density of air in kg/m^3.

• water_density (float) – Density of water in kg/m^3.

• g (float) – Gravitational acceleration in m/s^2.

Returns:

Reynolds number for the raindrop.

Return type:

float

disdrodb.l1.beard_model.get_vapor_actual_pressure(relative_humidity, temperature)

Computes the actual vapor pressure over water.

Parameters:

• relative_humidity (float) – Relative humidity. A value between 0 and 1.

• temperature (float) – Temperature in Kelvin.

Returns:

Actual vapor pressure in Pascal.

Return type:

float

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)

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:

float

disdrodb.l1.beard_model.get_vapor_saturation_pressure(temperature)

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

Parameters:

temperature (float) – Temperature in Kelvin.

Returns:

Saturation vapor pressure in Pascal.

Return type:

float

disdrodb.l1.beard_model.get_water_density(temperature, air_pressure, sea_level_air_pressure=101325)

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:

float

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)

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:

tuple

disdrodb.l1.encoding_attrs module

Attributes and encoding options for DISDRODB products.

disdrodb.l1.encoding_attrs.get_attrs_dict()

Temporary attributes.

disdrodb.l1.encoding_attrs.get_encoding_dict()

Temporary encoding dictionary.

disdrodb.l1.fall_velocity module

Theoretical models to estimate the drop fall velocity.

disdrodb.l1.fall_velocity.ensure_valid_coordinates(ds, default_altitude=0, default_latitude=0, default_longitude=0)

Ensure dataset valid coordinates for altitude, latitude, and longitude.

Invalid values are np.nan and -9999.

Parameters:

• ds (xarray.Dataset) – The dataset for which to ensure valid geolocation coordinates.

• default_altitude (float, optional) – The default value to use for invalid altitude values. Defaults to 0.

• default_latitude (float, optional) – The default value to use for invalid latitude values. Defaults to 0.

• default_longitude (float, optional) – The default value to use for invalid longitude values. Defaults to 0.

Returns:

The dataset with invalid coordinates replaced by default values.

Return type:

xarray.Dataset

disdrodb.l1.fall_velocity.get_fall_velocity_atlas_1973(diameter)

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

Atlas, D., & Ulbrich, C. W. (1977). Path- and area-integrated rainfall measurement by microwave attenuation in the 1-3 cm band. Journal of Applied Meteorology, 16(12), 1322-1331. https://doi.org/10.1175/1520-0450(1977)016<1322:PAAIRM>2.0.CO;2

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)

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 Celsius (°C). - ‘relative_humidity’ : Relative humidity in percentage (%). - ‘sea_level_air_pressure’ : Sea level 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)

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)

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)

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, method, ds_env=None)

Calculate the fall velocity of raindrops based on their diameter.

Parameters:

• diameter (array-like) – The diameter of the raindrops in millimeters.

• method (str) – The method to use for calculating the fall velocity. Must be one of the following: ‘Atlas1973’, ‘Beard1976’, ‘Brandes2002’, ‘Uplinger1981’, ‘VanDijk2002’.

• ds_env (xr.Dataset, optional) – A dataset containing the following environmental variables: - ‘altitude’ : Altitude in meters (m). - ‘latitude’ : Latitude in degrees. - ‘temperature’ : Temperature in degrees Celsius (°C). - ‘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). It is required for for the ‘Beard1976’ method.

Returns:

fall_velocity – The calculated fall velocities of the raindrops.

Return type:

array-like

Notes

The ‘Beard1976’ method requires additional environmental parameters such as altitude and latitude. These parameters can be provided through the ds_env argument. If not provided, default values will be used.

disdrodb.l1.filters module

Utilities for filtering the disdrometer raw drop spectra.

disdrodb.l1.filters.define_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)

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 drops of given sizes.

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

• above_velocity_tolerance (float, optional) – Absolute tolerance above which 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 drops are considered too slow. Either specify below_velocity_fraction or below_velocity_tolerance.

• below_velocity_tolerance (float, optional) –

  Absolute tolerance below which 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 drops in the spectrum are retained in the mask. The smallest drops are characterized by small_diameter_threshold and small_velocity_threshold arguments. Defaults to False.

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

• small_velocity_threshold (float, optional) – The fall velocity threshold to use for keeping the smallest 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.l1.filters.filter_diameter_bins(ds, minimum_diameter=None, maximum_diameter=None)

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 include in the filter, in millimeters. Defaults to the minimum value in ds[“diameter_bin_lower”].

• maximum_diameter (float, optional) – The maximum diameter to include in the filter, in millimeters. Defaults to the maximum value in ds[“diameter_bin_upper”].

Returns:

The filtered dataset containing only the specified diameter bins.

Return type:

xarray.Dataset

disdrodb.l1.filters.filter_velocity_bins(ds, minimum_velocity=0, maximum_velocity=12)

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 0 m/s.

• maximum_velocity (float, optional) – The maximum velocity to include in the filter, in meters per second. Defaults to 12 m/s.

Returns:

The filtered dataset containing only the specified velocity bins.

Return type:

xarray.Dataset

disdrodb.l1.processing module

Core functions for DISDRODB L1 production.

disdrodb.l1.processing.generate_l1(ds, fall_velocity_method='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)

Generate the DISDRODB L1 dataset from the DISDRODB L0C dataset.

Parameters:

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

• fall_velocity_method (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:

DISRODB L1 dataset.

Return type:

xarray.Dataset

disdrodb.l1.resampling module

Utilities for temporal resampling.

disdrodb.l1.resampling.add_sample_interval(ds, sample_interval)

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:

xarray.Dataset

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)

Calculate the rolling window size based on sampling and accumulation intervals.

Parameters:

• sampling_interval (int) – The sampling interval in seconds.

• accumulation_interval (int) – The desired accumulation interval in seconds.

Returns:

The calculated window size as the number of sampling intervals required to cover the accumulation interval.

Return type:

int

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.get_possible_accumulations(sample_interval, accumulations=None)

Get a list of valid accumulation intervals based on the sampling time.

Parameters:

• (int) (- sample_interval) –

• string) (- accumulations (list of int or) –

• integers (If provide) –

• seconds. (specify accumulation in) –

Returns:

- list of int

Return type:

Valid accumulation intervals in seconds.

disdrodb.l1.resampling.resample_dataset(ds, sample_interval, accumulation_interval, rolling=True)

Resample the dataset to a specified accumulation interval.

Parameters:

• ds (xarray.Dataset) – The input dataset to be resampled.

• sample_interval (int) – The sample interval of the input dataset.

• accumulation_interval (int) – The interval in seconds over which to accumulate the data.

• rolling (bool, optional) – If True, apply a rolling window before resampling. Default is True. If True, forward rolling is performed. The output timesteps correspond to the starts of the periods over which the resampling operation has been performed !

Returns:

The resampled dataset with updated attributes.

Return type:

xarray.Dataset

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.

disdrodb.l1.routines module

Implement DISDRODB L1 processing.

disdrodb.l1.routines.get_l1_options()

Get L1 options.

disdrodb.l1.routines.run_l1_station(data_source, campaign_name, station_name, force: bool = False, verbose: bool = True, parallel: bool = True, debugging_mode: bool = False, data_archive_dir: str | None = None, metadata_archive_dir: str | None = None)

Run the L1 processing of a specific DISDRODB station when invoked from the terminal.

The L1 routines just filter the raw drop spectrum and compute basic statistics. The L1 routine expects as input L0C files where each file has a unique sample interval.

This function is intended to be called through the disdrodb_run_l1_station command-line interface.

Parameters:

• data_source (str) – The name of the institution (for campaigns spanning multiple countries) or the name of the country (for campaigns or sensor networks within a single country). Must be provided in UPPER CASE.

• campaign_name (str) – The name of the campaign. Must be provided in UPPER CASE.

• station_name (str) – The name of the station.

• force (bool, optional) – If True, existing data in the destination directories will be overwritten. If False (default), an error will be raised if data already exists in the destination directories.

• verbose (bool, optional) – If True (default), detailed processing information will be printed to the terminal. If False, less information will be displayed.

• parallel (bool, optional) – If True, files will be processed in multiple processes simultaneously, with each process using a single thread to avoid issues with the HDF/netCDF library. If False (default), files will be processed sequentially in a single process, and multi-threading will be automatically exploited to speed up I/O tasks.

• debugging_mode (bool, optional) – If True, the amount of data processed will be reduced. Only the first 3 files will be processed. The default value is False.

• data_archive_dir (str, optional) – The base directory of DISDRODB, expected in the format <...>/DISDRODB. If not specified, the path specified in the DISDRODB active configuration will be used.

Module contents

DISDRODB L1 module.