disdrodb.l1 package

Submodules

disdrodb.l1.classification module

DISDRODB hydrometeor classification and QC module.

disdrodb.l1.classification.add_hydrometeor_type_attrs(hydrometeor_type)

Add CF-attributes to hydrometeor_type DataArray.

disdrodb.l1.classification.classify_raw_spectrum(ds, ds_env, sample_interval, sensor_name, temperature=None, rain_temperature_lower_limit=-5, snow_temperature_upper_limit=5)

Run precipitation and hydrometeor type classification.

disdrodb.l1.classification.define_graupel_mask(spectrum, ds_env, minimum_diameter=0.5, maximum_diameter=5, minimum_density=50, maximum_density=600)

Define graupel mask.

disdrodb.l1.classification.define_hail_mask(spectrum, ds_env, minimum_diameter=5)

Define hail mask.

disdrodb.l1.classification.define_precipitation_type_from_hydrometeor_type(hydrometeor_type)

Define precipitation_type from hydrometeor_type.

disdrodb.l1.classification.define_qc_margin_fallers(spectrum, fall_velocity_upper, above_velocity_fraction=None, above_velocity_tolerance=2)

Define QC mask for margin fallers and splashing.

disdrodb.l1.classification.define_qc_rain_strong_wind_mask(spectrum)

Define QC mask for strong wind artefacts in heavy rainfall.

Based on Katia Friedrich et al. 2013.

disdrodb.l1.classification.define_qc_temperature(temperature, sample_interval, threshold_minutes=360)

Define segment-based QC rule for temperature.

Return a qc array with 1 when temperature is constant for over threshold_minutes. Return a qc of 2 if temperature is not available.

disdrodb.l1.classification.get_temperature(ds)

Retrieve temperature variable from L0C product.

This function extracts temperature data from DISDRODB L0C product. The temperature variable chosen varies with sensor types. It prioritize air_temperature when available, but can fallback to internal sensor temperature if more reliable variables are not present.

Parameters:

ds (xarray.Dataset) – DISDRODB L0C dataset containing one or more temperature variables defined in DICT_TEMPERATURES. Expected temperature variables include: ‘air_temperature’, ‘air_temperature_min’, ‘temperature_ambient’, ‘temperature_interior’, or ‘sensor_temperature’.

Returns:

• temperature (xarray.DataArray or None) – Temperature time series [°C] with invalid values removed. Returns None if no temperature variable is available in the dataset. Values are set to NaN for timesteps with unrealistic values or large sensor disagreement.

• snow_temperature_limit (xarray.DataArray or None) – Snow/rain temperature threshold [°C] corresponding to the selected temperature variable for each timestep. Returns None if no temperature variable is available.

Notes

The function applies the following processing steps:

1. Variable Selection Priority: Searches for temperature variables in the order defined by DICT_TEMPERATURES. Each variable has an associated snow temperature limit (e.g., air_temperature: 6°C, sensor_temperature: 10°C).

2. Quality Filtering: Filters out physically unrealistic temperature values outside the range [-40°C, 35°C].

3. Preference Handling: For each timestep, selects the first available valid temperature following the priority order in DICT_TEMPERATURES. This ensures more reliable variables (e.g., air_temperature) are preferred over less reliable ones (e.g., sensor_temperature).

4. Sensor Consistency Check: Computes the temperature spread across all available sensors at each timestep. If the spread exceeds 10°C, that timestep is flagged as inconsistent and set to NaN, indicating unreliable measurements.

5. Snow Limit Assignment: Returns the temperature threshold for snow/rain discrimination corresponding to the selected temperature variable for each timestep.

disdrodb.l1.classification.map_precip_flag_to_precipitation_type(precip_flag)

Map OCEANRAIN precip_flag to DISDRODB precipitation_type.

disdrodb.l1.classification.qc_spikes_isolated_precip(hydrometeor_type, sample_interval)

Identify isolated precipitation spikes based on hydrometeor classification.

This quality control (QC) routine flags short, isolated precipitation detections (spikes) that are not supported by neighboring precipitating timesteps within a defined time window. The test helps remove spurious single-sample precipitation detections caused by instrument noise or transient misclassification.

The algorithm:

1. Identifies potential precipitation timesteps where hydrometeor_type>= 1.

2. Computes time differences between consecutive potential precipitation samples.

3. Flags a timestep as a spike when both the previous and next precipitation detections are separated by more than the configured time window.

4. Skips the QC test entirely if the temporal resolution exceeds 2 minutes.

Parameters:

• hydrometeor_type (xarray.DataArray) – Hydrometeor type classification array with a time coordinate. Precipitation presence is defined where hydrometeor_type>= 1.

• sample_interval (float or int) – Nominal sampling interval of the dataset in seconds. If sample_interval >= 120 (2 minutes), the QC test is skipped.

Returns:

flag_spikes –

Binary QC flag array (same dimensions as input) with:

• 0 : no spike detected

• 1 : isolated precipitation spike

Return type:

xarray.DataArray of int

Notes

• The time window is currently fixed to ±60 seconds for typical 1-minute sampling intervals but can be adapted to scale with sample_interval.

• Designed to work with irregular time coordinates; relies on actual timestamp differences instead of fixed rolling windows.

• For datasets with coarse sampling (> 2 minutes), the function returns a zero-valued flag (QC not applied).

disdrodb.l1.processing module

Core functions for DISDRODB L1 production.

disdrodb.l1.processing.generate_l1(ds, **kwargs)

Generate DISDRODB L1 Dataset from DISDRODB L0C Dataset.

Parameters:

ds (xarray.Dataset) – DISDRODB L0C dataset.

Returns:

DISDRODB 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.resample_dataset(ds, sample_interval, temporal_resolution, time_is_interval_end=True, var_to_average=None, var_to_cumulate=None, var_to_max=None, var_to_min=None)

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”.

• time_is_interval_end (bool) – Whether time correspond to the end of the measurement/accumulation interval/period. The default is True.

• var_to_average (str or list[str], optional) – Additional variable name(s) to average during resampling. These are merged with the internal default averaging list.

• var_to_cumulate (str or list[str], optional) – Additional variable name(s) to sum (cumulate) during resampling. These are merged with the internal default cumulation list.

• var_to_max (str or list[str], optional) – Additional variable name(s) for maximum aggregation during resampling. These are merged with the internal default max list.

• var_to_min (str or list[str], optional) – Additional variable name(s) for minimum aggregation during resampling. These are merged with the internal default min list.

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.

  • The var_to_* arguments are optional extensions of the default variable

    groups; they do not replace the built-in defaults.

  • If provided as a string, each var_to_* argument is converted to a

    single-item list.

  • A ValueError is raised if any user-provided variable does not exist

    in the input dataset.

• Custom processing for quality flags and handling of NaNs is defined.

• The function updates the dataset attributes and the sample_interval coordinate.

disdrodb.l1.weather_codes module

DISDRODB weather codes module.

disdrodb.l1.weather_codes.get_hydroclass_from_weather_code(ds, weather_code)

Convert weather code to DISDRODB hydrometeor type using predefined mapping dictionaries.

Module contents

DISDRODB L1 module.

disdrodb.l1.generate_l1(ds, **kwargs)

Generate DISDRODB L1 Dataset from DISDRODB L0C Dataset.

Parameters:

ds (xarray.Dataset) – DISDRODB L0C dataset.

Returns:

DISDRODB L1 dataset.

Return type:

xarray.Dataset