disdrodb 0.2.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

disdrodb/l2/processing.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------.
-# Copyright (c) 2021-2023 DISDRODB developers
+# Copyright (c) 2021-2026 DISDRODB developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -19,8 +19,8 @@
 import numpy as np
 import xarray as xr
 
-from disdrodb.constants import DIAMETER_DIMENSION
-from disdrodb.l1.fall_velocity import get_raindrop_fall_velocity
+from disdrodb.constants import DIAMETER_DIMENSION, METEOROLOGICAL_VARIABLES, VELOCITY_DIMENSION
+from disdrodb.fall_velocity import get_rain_fall_velocity, get_rain_fall_velocity_from_ds
 from disdrodb.l1_env.routines import load_env_dataset
 from disdrodb.l2.empirical_dsd import (
     BINS_METRICS,
@@ -29,55 +29,23 @@ from disdrodb.l2.empirical_dsd import (
     compute_spectrum_parameters,
     get_drop_number_concentration,
     get_effective_sampling_area,
+    get_effective_sampling_interval,
     get_kinetic_energy_variables_from_drop_number,
+    get_min_max_diameter,
     get_rain_accumulation,
     get_rain_rate_from_drop_number,
 )
 from disdrodb.psd import create_psd, estimate_model_parameters
 from disdrodb.psd.fitting import compute_gof_stats
 from disdrodb.utils.decorators import check_pytmatrix_availability
-from disdrodb.utils.time import ensure_sample_interval_in_seconds
+from disdrodb.utils.manipulations import (
+    define_diameter_array,
+    filter_diameter_bins,
+    filter_velocity_bins,
+)
 from disdrodb.utils.writer import finalize_product
 
 
-def define_diameter_array(diameter_min=0, diameter_max=10, diameter_spacing=0.05):
-    """
-    Define an array of diameters and their corresponding bin properties.
-
-    Parameters
-    ----------
-    diameter_min : float, optional
-        The minimum diameter value. The default value is 0 mm.
-    diameter_max : float, optional
-        The maximum diameter value. The default value is 10 mm.
-    diameter_spacing : float, optional
-        The spacing between diameter values. The default value is 0.05 mm.
-
-    Returns
-    -------
-    xr.DataArray
-        A DataArray containing the center of each diameter bin, with coordinates for
-        the bin width, lower bound, upper bound, and center.
-
-    """
-    diameters_bounds = np.arange(diameter_min, diameter_max + diameter_spacing / 2, step=diameter_spacing)
-    diameters_bin_lower = diameters_bounds[:-1]
-    diameters_bin_upper = diameters_bounds[1:]
-    diameters_bin_width = diameters_bin_upper - diameters_bin_lower
-    diameters_bin_center = diameters_bin_lower + diameters_bin_width / 2
-    da = xr.DataArray(
-        diameters_bin_center,
-        dims="diameter_bin_center",
-        coords={
-            "diameter_bin_width": ("diameter_bin_center", diameters_bin_width),
-            "diameter_bin_lower": ("diameter_bin_center", diameters_bin_lower),
-            "diameter_bin_upper": ("diameter_bin_center", diameters_bin_upper),
-            "diameter_bin_center": ("diameter_bin_center", diameters_bin_center),
-        },
-    )
-    return da
-
-
 def define_velocity_array(ds):
     """
     Create the fall velocity DataArray using various methods.
@@ -99,7 +67,7 @@ def define_velocity_array(ds):
     if "velocity_bin_center" in ds.dims:
         velocity = xr.Dataset(
             {
-                "fall_velocity": xr.ones_like(drop_number) * ds["fall_velocity"],
+                "theoretical_velocity": xr.ones_like(drop_number) * ds["fall_velocity"],
                 "measured_velocity": xr.ones_like(drop_number) * ds["velocity_bin_center"],
             },
         ).to_array(dim="velocity_method")
@@ -108,12 +76,183 @@ def define_velocity_array(ds):
     return velocity
 
 
+####--------------------------------------------------------------------------
+#### Extract drop spectrum
+
+
+def 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",
+):
+    """Retrieve the drop spectrum from the DISDRODB L1 product."""
+    from disdrodb.fall_velocity.rain import get_rain_fall_velocity
+
+    # Retrieve spectrum
+    raw_spectrum = ds["raw_drop_number"].copy()
+
+    # Retrieve coordinates
+    diameter_upper = raw_spectrum["diameter_bin_upper"]
+    diameter_lower = raw_spectrum["diameter_bin_lower"]
+    velocity_upper = raw_spectrum["velocity_bin_upper"]
+
+    # Retrieve rainfall mask
+    raindrop_fall_velocity_upper = get_rain_fall_velocity(
+        diameter=diameter_upper,
+        model=fall_velocity_model,
+        ds_env=ds_env,
+    )
+    raindrop_fall_velocity_lower = get_rain_fall_velocity(
+        diameter=diameter_lower,
+        model=fall_velocity_model,
+        ds_env=ds_env,
+    )
+    rain_mask = define_rain_spectrum_mask(
+        drop_number=raw_spectrum,
+        fall_velocity_lower=raindrop_fall_velocity_lower,
+        fall_velocity_upper=raindrop_fall_velocity_upper,
+        above_velocity_fraction=above_velocity_fraction,
+        above_velocity_tolerance=above_velocity_tolerance,
+        below_velocity_fraction=below_velocity_fraction,
+        below_velocity_tolerance=below_velocity_tolerance,
+        maintain_drops_smaller_than=maintain_drops_smaller_than,
+        maintain_drops_slower_than=maintain_drops_slower_than,
+        maintain_smallest_drops=maintain_smallest_drops,
+    )
+
+    # Set to 0 spectrum not classified as liquid or mixed
+    if "precipitation_type" in ds:
+        raw_spectrum = xr.where(ds["precipitation_type"].isin([0, 2]), raw_spectrum, 0)
+
+    # Retrieve drop spectrum
+    # - Liquid + Mixed
+    drop_spectrum = raw_spectrum.where(rain_mask, 0)
+
+    # Optionally mask area affected by splashing
+    if remove_splashing_drops and "flag_splashing" in ds:
+        flag_splashing = ds["flag_splashing"]
+        splash_mask = (diameter_lower >= 0.0) & (diameter_upper <= 6) & (velocity_upper <= 0.6)
+
+        drop_spectrum = xr.where(flag_splashing == 1, drop_spectrum.where(~splash_mask, 0), drop_spectrum)
+    return drop_spectrum
+
+
+def 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,  # 1,   # 2
+    maintain_drops_slower_than=2.5,  # 2.5, # 3
+    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_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
+    -------
+    xarray.DataArray
+        A boolean mask array indicating valid bins according to the specified criteria.
+
+    """
+    # Ensure it creates a 2D mask if the fall_velocity does not vary over time
+    if "time" in drop_number.dims and "time" not in fall_velocity_lower.dims:
+        drop_number = drop_number.isel(time=0)
+
+    # Check arguments
+    if above_velocity_fraction is not None and above_velocity_tolerance is not None:
+        raise ValueError("Either specify 'above_velocity_fraction' or 'above_velocity_tolerance'.")
+    if below_velocity_fraction is not None and below_velocity_tolerance is not None:
+        raise ValueError("Either specify 'below_velocity_fraction' or 'below_velocity_tolerance'.")
+
+    # Define above/below velocity thresholds
+    if above_velocity_fraction is not None:
+        above_fall_velocity = fall_velocity_upper * (1 + above_velocity_fraction)
+    elif above_velocity_tolerance is not None:
+        above_fall_velocity = fall_velocity_upper + above_velocity_tolerance
+    else:
+        above_fall_velocity = np.inf
+
+    if below_velocity_fraction is not None:
+        below_fall_velocity = fall_velocity_lower * (1 - below_velocity_fraction)
+    elif below_velocity_tolerance is not None:
+        below_fall_velocity = fall_velocity_lower - below_velocity_tolerance
+    else:
+        below_fall_velocity = 0
+
+    # Define velocity 2D array
+    velocity_lower = xr.ones_like(drop_number) * drop_number["velocity_bin_lower"]
+    velocity_upper = xr.ones_like(drop_number) * drop_number["velocity_bin_upper"]
+
+    # Define mask
+    mask = np.logical_and(
+        velocity_upper > below_fall_velocity,
+        velocity_lower < above_fall_velocity,
+    )
+
+    # Maintant smallest drops
+    if maintain_smallest_drops:
+        mask_smallest = np.logical_and(
+            drop_number["diameter_bin_upper"] <= maintain_drops_smaller_than,
+            drop_number["velocity_bin_upper"] <= maintain_drops_slower_than,
+        )
+        mask = np.logical_or(mask, mask_smallest)
+
+    return mask
+
+
 ####--------------------------------------------------------------------------
 #### Timesteps filtering functions
 
 
 def select_timesteps_with_drops(ds, minimum_ndrops=0):
     """Select timesteps with at least the specified number of drops."""
+    # If not a unique time dimension, skip subsetting
+    if ds["N"].dims != ("time",):
+        return ds
+    # Otherwise subset time dimension
     valid_timesteps = ds["N"].to_numpy() >= minimum_ndrops
     if not valid_timesteps.any().item():
         raise ValueError(f"No timesteps with N >= {minimum_ndrops}.")
@@ -124,6 +263,10 @@ def select_timesteps_with_drops(ds, minimum_ndrops=0):
 
 def select_timesteps_with_minimum_nbins(ds, minimum_nbins):
     """Select timesteps with at least the specified number of diameter bins with drops."""
+    # If not a unique time dimension, skip subsetting
+    if ds["Nbins"].dims != ("time",):
+        return ds
+    # Otherwise subset time dimension
     if minimum_nbins == 0:
         return ds
     valid_timesteps = ds["Nbins"].to_numpy() >= minimum_nbins
@@ -167,7 +310,7 @@ def check_l2e_input_dataset(ds):
     from disdrodb.scattering import RADAR_OPTIONS
 
     # Check minimum required variables, coordinates and dimensions are presents
-    required_variables = ["drop_number", "fall_velocity"]
+    required_variables = ["raw_drop_number"]
     required_coords = [
         "diameter_bin_center",
         "diameter_bin_width",
@@ -194,9 +337,25 @@ def generate_l2e(
     ds_env=None,
     compute_spectra=False,
     compute_percentage_contribution=False,
+    # Filtering options
     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,
+    # Spectrum filtering options
+    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,  # 2
+    maintain_drops_slower_than=2.5,  # 3
+    maintain_smallest_drops=True,
+    remove_splashing_drops=True,
 ):
     """Generate the DISDRODB L2E dataset from the DISDRODB L1 dataset.
 
@@ -205,15 +364,40 @@ def generate_l2e(
     ds : xarray.Dataset
         DISDRODB L1 dataset.
         Alternatively, a xarray dataset with at least:
-
-            - variables: drop_number, fall_velocity
+            - 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
     -------
@@ -223,6 +407,67 @@ def generate_l2e(
     # Check and prepapre input dataset
     ds = check_l2e_input_dataset(ds)
 
+    # Select only dry and rainy timesteps
+    if "precipitation_type" in ds:
+        if keep_mixed_precipitation:  # class 4
+            ds = ds.isel(time=ds["precipitation_type"].isin([-1, 0, 4]), drop=True)
+        else:
+            ds = ds.isel(time=ds["precipitation_type"].isin([-1, 0]), drop=True)
+
+    # Determine if the velocity dimension is available
+    has_velocity_dimension = VELOCITY_DIMENSION in ds.dims
+
+    # - Filter diameter bins
+    ds = filter_diameter_bins(ds=ds, minimum_diameter=minimum_diameter, maximum_diameter=maximum_diameter)
+    # - Filter velocity bins
+    if has_velocity_dimension:
+        ds = filter_velocity_bins(ds=ds, minimum_velocity=minimum_velocity, maximum_velocity=maximum_velocity)
+
+    # -------------------------------------------------------------------------------------------
+    # Compute fall velocity
+    ds["fall_velocity"] = get_rain_fall_velocity_from_ds(ds=ds, ds_env=ds_env, model=fall_velocity_model)
+
+    # -------------------------------------------------------
+    # Retrieve filtered spectrum and drop counts (summing over velocity dimension if present)
+    if has_velocity_dimension:
+        drop_number = retrieve_drop_spectrum(
+            ds=ds,
+            ds_env=ds_env,
+            above_velocity_fraction=above_velocity_fraction,
+            above_velocity_tolerance=above_velocity_tolerance,
+            below_velocity_fraction=below_velocity_fraction,
+            below_velocity_tolerance=below_velocity_tolerance,
+            maintain_drops_smaller_than=maintain_drops_smaller_than,
+            maintain_drops_slower_than=maintain_drops_slower_than,
+            maintain_smallest_drops=maintain_smallest_drops,
+            remove_splashing_drops=remove_splashing_drops,
+            fall_velocity_model=fall_velocity_model,
+        )
+        drop_counts = drop_number.sum(dim=VELOCITY_DIMENSION)  # 1D (diameter)
+        drop_counts_raw = ds["raw_drop_number"].sum(dim=VELOCITY_DIMENSION)  # 1D (diameter)
+    else:
+        drop_number = ds["raw_drop_number"]  # no filtering applied
+        drop_counts = ds["raw_drop_number"]  # 1D (diameter)
+        drop_counts_raw = ds["raw_drop_number"]
+
+    ds["drop_number"] = drop_number
+    ds["drop_counts"] = drop_counts
+
+    # -------------------------------------------------------
+    # Compute drop statistics
+    # - Compute minimum and max drop diameter observed
+    min_drop_diameter, max_drop_diameter = get_min_max_diameter(drop_counts)
+
+    # - Add rain drop statistics
+    ds["Dmin"] = min_drop_diameter
+    ds["Dmax"] = max_drop_diameter
+    ds["N"] = drop_counts.sum(dim=DIAMETER_DIMENSION)
+    ds["Nraw"] = drop_counts_raw.sum(dim=DIAMETER_DIMENSION)
+    ds["Nremoved"] = ds["Nraw"] - ds["N"]
+
+    # - Add bins statistics
+    ds = add_bins_metrics(ds)
+
     # -------------------------------------------------------
     # Initialize L2E dataset
     ds_l2 = xr.Dataset()
@@ -235,9 +480,6 @@ def generate_l2e(
     # Select timesteps with at least the specified number of drops
     ds = select_timesteps_with_drops(ds, minimum_ndrops=minimum_ndrops)
 
-    # Add bins metrics to resampled data if missing
-    ds = add_bins_metrics(ds)
-
     # Remove timesteps with not enough bins with drops
     ds = select_timesteps_with_minimum_nbins(ds, minimum_nbins=minimum_nbins)
 
@@ -256,24 +498,41 @@ def generate_l2e(
     diameter = ds["diameter_bin_center"] / 1000  # m
     diameter_bin_width = ds["diameter_bin_width"]  # mm
     drop_number = ds["drop_number"]
-    sample_interval = ensure_sample_interval_in_seconds(ds["sample_interval"])  # s
 
-    # Compute sampling area [m2]
+    # Retrieve effective sampling interval [s]
+    sample_interval = get_effective_sampling_interval(ds, sensor_name=sensor_name)  # s
+
+    # Retrieve effective sampling area [m2]
     sampling_area = get_effective_sampling_area(sensor_name=sensor_name, diameter=diameter)  # m2
 
     # Copy relevant L1 variables to L2 product
     variables = [
+        # L1 inputs
+        "sample_interval",
+        "fall_velocity",
         "raw_drop_number",  # 2D V x D
         "drop_number",  # 2D V x D
+        # Drop statistics
         "drop_counts",  # 1D D
-        "sample_interval",
         "N",
         "Nremoved",
+        "Nraw",
         "Dmin",
         "Dmax",
-        "fall_velocity",
+        # L0C QC
+        "qc_time",
+        # L1 flags and variables
         "qc_resampling",
-        "time_qc",
+        "precipitation_type",
+        "hydrometeor_type",
+        "n_margin_fallers",
+        "n_splashing",
+        "flag_graupel",
+        "flag_hail",
+        "flag_spikes",
+        "flag_splashing",
+        "flag_wind_artefacts",
+        *METEOROLOGICAL_VARIABLES,
     ]
 
     variables = [var for var in variables if var in ds]
@@ -289,6 +548,7 @@ def generate_l2e(
     # -------------------------------------------------------------------------------------------
     # Define velocity array with dimension 'velocity_method'
     velocity = define_velocity_array(ds)
+    velocity = velocity.fillna(0)
 
     # Compute drop number concentration (Nt) [#/m3/mm]
     drop_number_concentration = get_drop_number_concentration(
@@ -398,7 +658,7 @@ def check_l2m_input_dataset(ds):
     if "drop_number_concentration" not in ds:
         if "drop_number" in ds:
             check_l2e_input_dataset(ds)
-            sample_interval = ensure_sample_interval_in_seconds(ds["sample_interval"])
+            sample_interval = get_effective_sampling_interval(ds, sensor_name=ds.attrs["sensor_name"])
             sampling_area = get_effective_sampling_area(
                 sensor_name=ds.attrs["sensor_name"],
                 diameter=ds["diameter_bin_center"] / 1000,
@@ -503,7 +763,7 @@ def generate_l2m(
 
     # Retrieve measurement interval
     # - If dataset is opened with decode_timedelta=False, sample_interval is already in seconds !
-    sample_interval = ensure_sample_interval_in_seconds(ds["sample_interval"])
+    sample_interval = get_effective_sampling_interval(ds, sensor_name=ds.attrs["sensor_name"])
 
     # Select timesteps with at least the specified number of drops
     ds = select_timesteps_with_drops(ds, minimum_ndrops=minimum_ndrops)
@@ -549,7 +809,7 @@ def generate_l2m(
     drop_number_concentration = psd(diameter)
 
     # Retrieve fall velocity for each new diameter bin
-    velocity = get_raindrop_fall_velocity(diameter=diameter, model=fall_velocity_model, ds_env=ds_env)  # mm
+    velocity = get_rain_fall_velocity(diameter=diameter, model=fall_velocity_model, ds_env=ds_env)  # mm
 
     # Compute integral parameters
     ds_params = compute_integral_parameters(
@@ -576,9 +836,15 @@ def generate_l2m(
 
     # Add empirical drop_number_concentration and fall velocity
     # - To reuse output dataset to create another L2M dataset or to compute other GOF metrics
-    ds_params["drop_number_concentration"] = ds["drop_number_concentration"]
-    ds_params["fall_velocity"] = ds["fall_velocity"]
-    ds_params["N"] = ds["N"]
+    # Copy relevant L1 variables to L2 product
+    variables = [
+        "drop_number_concentration",
+        "fall_velocity",
+        "N",
+        *METEOROLOGICAL_VARIABLES,
+    ]
+    variables = [var for var in variables if var in ds]
+    ds_params.update(ds[variables])
     ds_params.update(ds[BINS_METRICS])
 
     #### ----------------------------------------------------------------------------.

disdrodb/metadata/checks.py

@@ -1,7 +1,5 @@
-#!/usr/bin/env python3
-
 # -----------------------------------------------------------------------------.
-# Copyright (c) 2021-2023 DISDRODB developers
+# Copyright (c) 2021-2026 DISDRODB developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -19,7 +17,6 @@
 """Check metadata."""
 
 import os
-from typing import Optional, Union
 
 import numpy as np
 
@@ -192,7 +189,7 @@ def check_station_metadata_geolocation(metadata, raise_error_if_unknown=True) ->
         _check_lonlat_validity(longitude=longitude, latitude=latitude, raise_error_if_unknown=raise_error_if_unknown)
 
 
-def check_metadata_archive_geolocation(metadata_archive_dir: Optional[str] = None, raise_error_if_unknown=True):
+def check_metadata_archive_geolocation(metadata_archive_dir: str | None = None, raise_error_if_unknown=True):
     """Check the metadata files have missing or wrong geolocation..
 
     Parameters
@@ -261,7 +258,7 @@ def check_station_metadata(data_source, campaign_name, station_name, metadata_ar
     check_metadata_reader(metadata)
 
 
-def check_metadata_archive(metadata_archive_dir: Optional[str] = None, raise_error=False):
+def check_metadata_archive(metadata_archive_dir: str | None = None, raise_error=False):
     """Check the archive metadata compliance.
 
     Parameters
@@ -336,7 +333,7 @@ def identify_missing_metadata_coords(metadata_filepaths: str) -> None:
         check_station_metadata_geolocation(metadata)
 
 
-def identify_empty_metadata_keys(metadata_filepaths: list, keys: Union[str, list]) -> None:
+def identify_empty_metadata_keys(metadata_filepaths: list, keys: str | list) -> None:
     """Identify empty metadata keys.
 
     Parameters
@@ -360,7 +357,7 @@ def identify_empty_metadata_keys(metadata_filepaths: list, keys: Union[str, list
 #### Metadata Archive Utilities
 
 
-def check_metadata_archive_keys(metadata_archive_dir: Optional[str] = None) -> bool:
+def check_metadata_archive_keys(metadata_archive_dir: str | None = None) -> bool:
     """Check that all metadata files have valid keys.
 
     Parameters
@@ -407,7 +404,7 @@ def check_metadata_archive_keys(metadata_archive_dir: Optional[str] = None) -> b
     return is_valid
 
 
-def check_metadata_archive_campaign_name(metadata_archive_dir: Optional[str] = None) -> bool:
+def check_metadata_archive_campaign_name(metadata_archive_dir: str | None = None) -> bool:
     """Check metadata ``campaign_name``.
 
     Parameters
@@ -453,7 +450,7 @@ def check_metadata_archive_campaign_name(metadata_archive_dir: Optional[str] = N
     return is_valid
 
 
-def check_metadata_archive_data_source(metadata_archive_dir: Optional[str] = None) -> bool:
+def check_metadata_archive_data_source(metadata_archive_dir: str | None = None) -> bool:
     """Check metadata ``data_source``.
 
     Parameters
@@ -499,7 +496,7 @@ def check_metadata_archive_data_source(metadata_archive_dir: Optional[str] = Non
     return is_valid
 
 
-def check_metadata_archive_sensor_name(metadata_archive_dir: Optional[str] = None) -> bool:
+def check_metadata_archive_sensor_name(metadata_archive_dir: str | None = None) -> bool:
     """Check metadata ``sensor_name``.
 
     Parameters
@@ -545,7 +542,7 @@ def check_metadata_archive_sensor_name(metadata_archive_dir: Optional[str] = Non
     return is_valid
 
 
-def check_metadata_archive_station_name(metadata_archive_dir: Optional[str] = None) -> bool:
+def check_metadata_archive_station_name(metadata_archive_dir: str | None = None) -> bool:
     """Check metadata ``station_name``.
 
     Parameters
@@ -591,7 +588,7 @@ def check_metadata_archive_station_name(metadata_archive_dir: Optional[str] = No
     return is_valid
 
 
-def check_metadata_archive_reader(metadata_archive_dir: Optional[str] = None) -> bool:
+def check_metadata_archive_reader(metadata_archive_dir: str | None = None) -> bool:
     """Check if the ``reader`` key is available and there is the associated reader.
 
     Parameters

disdrodb/metadata/download.py

@@ -1,7 +1,5 @@
-#!/usr/bin/env python3
-
 # -----------------------------------------------------------------------------.
-# Copyright (c) 2021-2023 DISDRODB developers
+# Copyright (c) 2021-2026 DISDRODB developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -17,12 +15,15 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
 """Routine to download the DISDRODB Metadata Archive from GitHub."""
+
 import io
 import os
 import shutil
 import urllib.request
 import zipfile
 
+from disdrodb.utils.directories import remove_file_or_directories
+
 
 def download_metadata_archive(directory_path, force=False):
     """Download the DISDRODB Metadata Archive to the specified directory.
@@ -64,7 +65,7 @@ def download_metadata_archive(directory_path, force=False):
     # Handle existing target directory
     if os.path.exists(target_dir):
         if force:
-            shutil.rmtree(target_dir)
+            remove_file_or_directories(target_dir)
         else:
             raise FileExistsError(
                 f"A DISDRODB Metadata Archive already exists at '{target_dir}'. Use force=True to update it.",