disdrodb 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

disdrodb/{routines.py → routines/wrappers.py}

@@ -20,7 +20,7 @@ import time
 from typing import Optional
 
 from disdrodb.api.search import available_stations, get_required_product
-from disdrodb.utils.cli import _execute_cmd
+from disdrodb.utils.cli import execute_cmd
 
 ####--------------------------------------------------------------------------.
 #### Run DISDRODB Station Processing
@@ -239,7 +239,7 @@ def run_l0a_station(
         ],
     )
     # Execute command
-    _execute_cmd(cmd)
+    execute_cmd(cmd)
 
 
 def run_l0b_station(
@@ -323,7 +323,7 @@ def run_l0b_station(
         ],
     )
     # Execute command
-    _execute_cmd(cmd)
+    execute_cmd(cmd)
 
 
 def run_l0c_station(
@@ -407,7 +407,7 @@ def run_l0c_station(
         ],
     )
     # Execute command
-    _execute_cmd(cmd)
+    execute_cmd(cmd)
 
 
 def run_l1_station(
@@ -483,7 +483,7 @@ def run_l1_station(
         ],
     )
     # Execute command
-    _execute_cmd(cmd)
+    execute_cmd(cmd)
 
 
 def run_l2e_station(
@@ -559,7 +559,7 @@ def run_l2e_station(
         ],
     )
     # Execute command
-    _execute_cmd(cmd)
+    execute_cmd(cmd)
 
 
 def run_l2m_station(
@@ -635,7 +635,36 @@ def run_l2m_station(
         ],
     )
     # Execute command
-    _execute_cmd(cmd)
+    execute_cmd(cmd)
+
+
+def create_summary_station(
+    data_source,
+    campaign_name,
+    station_name,
+    parallel=False,
+    temporal_resolution="1MIN",
+    data_archive_dir=None,
+):
+    """Create summary figures and tables for a DISDRODB station."""
+    # Define command
+    cmd = " ".join(
+        [
+            "disdrodb_create_summary_station",
+            # Station arguments
+            data_source,
+            campaign_name,
+            station_name,
+            "--data_archive_dir",
+            str(data_archive_dir),
+            "--parallel",
+            str(parallel),
+            "--temporal_resolution",
+            str(temporal_resolution),
+        ],
+    )
+    # Execute command
+    execute_cmd(cmd)
 
 
 ####--------------------------------------------------------------------------.
@@ -1409,4 +1438,68 @@ def run_l2m(
         print(f"{product} processing of {data_source} {campaign_name} {station_name} station ended.")
 
 
+def create_summary(
+    data_sources=None,
+    campaign_names=None,
+    station_names=None,
+    parallel=False,
+    temporal_resolution="1MIN",
+    data_archive_dir=None,
+    metadata_archive_dir=None,
+):
+    """Create summary figures and tables for a set of DISDRODB station.
+
+    Parameters
+    ----------
+    data_sources : list
+        Name of data source(s) to process.
+        The name(s) must be UPPER CASE.
+        If campaign_names and station are not specified, process all stations.
+        The default value is ``None``.
+    campaign_names : list
+        Name of the campaign(s) to process.
+        The name(s) must be UPPER CASE.
+        The default value is ``None``.
+    station_names : list
+        Station names to process.
+        The default value is ``None``.
+    data_archive_dir : str (optional)
+        The directory path where the DISDRODB Data Archive is located.
+        The directory path must end with ``<...>/DISDRODB``.
+        If ``None``, it uses the ``data_archive_dir`` path specified
+        in the DISDRODB active configuration.
+    """
+    # Get list of available stations
+    list_info = available_stations(
+        # DISDRODB root directories
+        data_archive_dir=data_archive_dir,
+        metadata_archive_dir=metadata_archive_dir,
+        # Stations arguments
+        data_sources=data_sources,
+        campaign_names=campaign_names,
+        station_names=station_names,
+        # Search options
+        product="L2E",
+        product_kwargs={"rolling": False, "sample_interval": 60},
+        raise_error_if_empty=True,
+    )
+
+    # Loop over stations
+    print(f"Creation of summaries for {len(list_info)} stations has started.")
+    for data_source, campaign_name, station_name in list_info:
+        # Run processing
+        create_summary_station(
+            # DISDRODB root directories
+            data_archive_dir=data_archive_dir,
+            # Station arguments
+            data_source=data_source,
+            campaign_name=campaign_name,
+            station_name=station_name,
+            # Processing option
+            parallel=parallel,
+            temporal_resolution=temporal_resolution,
+        )
+    print("Creation of station summaries has terminated.")
+
+
 ####--------------------------------------------------------------------------.

disdrodb/scattering/axis_ratio.py

@@ -20,90 +20,6 @@ import numpy as np
 import xarray as xr
 
 
-def available_axis_ratio_models():
-    """Return a list of the available drop axis ratio models."""
-    return list(AXIS_RATIO_MODELS)
-
-
-def get_axis_ratio_model(model):
-    """Return the specified drop axis ratio model.
-
-    Parameters
-    ----------
-    model : str
-        The model to use for calculating the axis ratio. Available models are:
-        'Thurai2005', 'Thurai2007', 'Battaglia2010', 'Brandes2002',
-        'Pruppacher1970', 'Beard1987', 'Andsager1999'.
-
-    Returns
-    -------
-    callable
-        A function which compute the vertical-to-horizontal axis ratio given a
-        particle diameter in mm.
-
-    Notes
-    -----
-    This function serves as a wrapper to various axis ratio models for raindrops.
-    It returns the appropriate model based on the `model` parameter.
-
-    Please note that the axis ratio function to be provided to pyTmatrix expects to
-    return a horizontal-to-vertical axis ratio !
-
-    """
-    model = check_axis_ratio_model(model)
-    return AXIS_RATIO_MODELS[model]
-
-
-def check_axis_ratio_model(model):
-    """Check validity of the specified drop axis ratio model."""
-    available_models = available_axis_ratio_models()
-    if model not in available_models:
-        raise ValueError(f"{model} is an invalid axis-ratio model. Valid models: {available_models}.")
-    return model
-
-
-def get_axis_ratio(diameter, model):
-    """
-    Compute the axis ratio of raindrops using the specified model.
-
-    Parameters
-    ----------
-    diameter : array-like
-        Raindrops diameter in mm.
-    model : str
-        The axis ratio model to use for calculating the axis ratio. Available models are:
-        'Thurai2005', 'Thurai2007', 'Battaglia2010', 'Brandes2002',
-        'Pruppacher1970', 'Beard1987', 'Andsager1999'.
-
-    Returns
-    -------
-    axis_ratio : array-like
-        The vertical-to-horizontal drop axis ratio corresponding to the input diameters.
-        Values of 1 indicate spherical particles, while values <1 indicate oblate particles.
-        Values >1 means prolate particles.
-
-    Notes
-    -----
-    This function serves as a wrapper to various axis ratio models for raindrops.
-    It selects and applies the appropriate model based on the `model` parameter.
-
-    Examples
-    --------
-    >>> diameter = np.array([0.5, 1.0, 2.0, 3.0])
-    >>> axis_ratio = get_axis_ratio(diameter, model="Brandes2002")
-
-    """
-    # Retrieve axis ratio function
-    axis_ratio_func = get_axis_ratio_model(model)
-
-    # Retrieve axis ratio
-    axis_ratio = axis_ratio_func(diameter)
-
-    # Clip values between 0 and 1
-    axis_ratio = np.clip(axis_ratio, 0, 1)
-    return axis_ratio
-
-
 def get_axis_ratio_andsager_1999(diameter):
     """
     Compute the axis ratio of raindrops using the Andsager et al. (1999) model.
@@ -295,6 +211,8 @@ def get_axis_ratio_thurai_2005(diameter):
     """
     Compute the axis ratio of raindrops using the Thurai et al. (2005) model.
 
+    This model is assumed to be valid only for particles up to 5 mm.
+
     Parameters
     ----------
     diameter : array-like
@@ -311,7 +229,6 @@ def get_axis_ratio_thurai_2005(diameter):
     J. Atmos. Oceanic Technol., 22, 966-978, https://doi.org/10.1175/JTECH1767.1
 
     """
-    # Valid between 1 and 5 mm
     axis_ratio = 0.9707 + 4.26e-2 * diameter - 4.29e-2 * diameter**2 + 6.5e-3 * diameter**3 - 3e-4 * diameter**4
     return axis_ratio
 
@@ -350,6 +267,9 @@ def get_axis_ratio_thurai_2007(diameter):
     # Combine axis ratio
     axis_ratio_below_1_5 = xr.where(diameter > 0.7, axis_ratio_below_1_5, axis_ratio_below_0_7)
     axis_ratio = xr.where(diameter > 1.5, axis_ratio_above_1_5, axis_ratio_below_1_5)
+
+    # Ensure np.nan is preserved in arrays
+    axis_ratio = xr.where(np.isnan(diameter), np.nan, axis_ratio)
     return axis_ratio
 
 
@@ -362,3 +282,93 @@ AXIS_RATIO_MODELS = {
     "Beard1987": get_axis_ratio_beard_1987,
     "Andsager1999": get_axis_ratio_andsager_1999,
 }
+
+
+def available_axis_ratio_models():
+    """Return a list of the available drop axis ratio models."""
+    return list(AXIS_RATIO_MODELS)
+
+
+def check_axis_ratio_model(model):
+    """Check validity of the specified drop axis ratio model."""
+    available_models = available_axis_ratio_models()
+    if model not in available_models:
+        raise ValueError(f"{model} is an invalid axis-ratio model. Valid models: {available_models}.")
+    return model
+
+
+def get_axis_ratio_model(model):
+    """Return the specified drop axis ratio model.
+
+    Parameters
+    ----------
+    model : str
+        The model to use for calculating the axis ratio. Available models are:
+        'Thurai2005', 'Thurai2007', 'Battaglia2010', 'Brandes2002',
+        'Pruppacher1970', 'Beard1987', 'Andsager1999'.
+
+    Returns
+    -------
+    callable
+        A function which compute the vertical-to-horizontal axis ratio given a
+        particle diameter in mm.
+
+    Notes
+    -----
+    This function serves as a wrapper to various axis ratio models for raindrops.
+    It returns the appropriate model based on the `model` parameter.
+
+    Please note that the axis ratio function to be provided to pyTmatrix expects to
+    return a horizontal-to-vertical axis ratio !
+
+    """
+    model = check_axis_ratio_model(model)
+    return AXIS_RATIO_MODELS[model]
+
+
+def get_axis_ratio(diameter, model):
+    """
+    Compute the axis ratio of raindrops using the specified model.
+
+    Parameters
+    ----------
+    diameter : array-like
+        Raindrops diameter in mm.
+    model : str
+        The axis ratio model to use for calculating the axis ratio. Available models are:
+        'Thurai2005', 'Thurai2007', 'Battaglia2010', 'Brandes2002',
+        'Pruppacher1970', 'Beard1987', 'Andsager1999'.
+
+    Returns
+    -------
+    axis_ratio : array-like
+        The vertical-to-horizontal drop axis ratio corresponding to the input diameters.
+        Values of 1 indicate spherical particles, while values <1 indicate oblate particles.
+        Values >1 means prolate particles.
+
+    Notes
+    -----
+    This function serves as a wrapper to various axis ratio models for raindrops.
+    It selects and applies the appropriate model based on the `model` parameter.
+
+    Examples
+    --------
+    >>> diameter = np.array([0.5, 1.0, 2.0, 3.0])
+    >>> axis_ratio = get_axis_ratio(diameter, model="Brandes2002")
+
+    """
+    # Retrieve axis ratio function
+    axis_ratio_func = get_axis_ratio_model(model)
+
+    # Retrieve axis ratio
+    axis_ratio = axis_ratio_func(diameter)
+
+    # Clip values between 0 and 1
+    axis_ratio = np.clip(axis_ratio, 0, 1)
+
+    # Add attributes
+    if isinstance(axis_ratio, xr.DataArray):
+        axis_ratio.name = "axis_ratio"
+        axis_ratio.attrs["units"] = ""
+        axis_ratio.attrs["model"] = model
+    return axis_ratio

disdrodb/scattering/permittivity.py

@@ -124,11 +124,35 @@ def get_refractive_index(temperature, frequency, permittivity_model):
     >>> m = get_refractive_index(temperature=temperature, frequency=frequency, permittivity_model="Liebe1991")
 
     """
+    # Ensure input is numpy array or xr.DataArray
+    frequency = ensure_array(frequency)
+    temperature = ensure_array(temperature)
+
+    # If both inputs are numpy (or dask) arrays with size > 1 → raise error
+    if (
+        not isinstance(temperature, xr.DataArray)
+        and not isinstance(frequency, xr.DataArray)
+        and np.size(temperature) > 1
+        and np.size(frequency) > 1
+    ):
+        raise ValueError(
+            "get_refractive_index does not support broadcasting plain numpy/dask arrays "
+            "when both `temperature` and `frequency` have size > 1. "
+            "Please provide both input as xarray.DataArray objects "
+            "with different dimensions to enable labeled broadcasting.",
+        )
+
     # Retrieve refractive_index function
     func = get_refractive_index_function(permittivity_model)
 
     # Retrieve refractive_index
     refractive_index = func(temperature=temperature, frequency=frequency)
+
+    # Add attributes
+    if isinstance(refractive_index, xr.DataArray):
+        refractive_index.name = "refractive_index"
+        refractive_index.attrs["units"] = ""
+        refractive_index.attrs["model"] = permittivity_model
     return refractive_index
 
 

disdrodb/scattering/routines.py

@@ -432,6 +432,41 @@ def load_scatterer(
     return scatterer
 
 
+def precompute_scattering_tables(
+    frequency,
+    num_points,
+    diameter_max,
+    canting_angle_std,
+    axis_ratio_model,
+    permittivity_model,
+    water_temperature,
+    elevation_angle,
+    verbose=True,
+):
+    """Precompute the pyTMatrix scattering tables required for radar variables simulations."""
+    from disdrodb.scattering.routines import get_list_simulations_params, load_scatterer
+
+    # Define parameters for all requested simulations
+    list_params = get_list_simulations_params(
+        frequency=frequency,
+        num_points=num_points,
+        diameter_max=diameter_max,
+        canting_angle_std=canting_angle_std,
+        axis_ratio_model=axis_ratio_model,
+        permittivity_model=permittivity_model,
+        water_temperature=water_temperature,
+        elevation_angle=elevation_angle,
+    )
+
+    # Compute require scattering tables
+    for params in list_params:
+        # Initialize scattering table
+        _ = load_scatterer(
+            verbose=verbose,
+            **params,
+        )
+
+
 ####----------------------------------------------------------------------
 #### Scattering functions
 
@@ -458,12 +493,10 @@ def compute_radar_variables(scatterer):
         radar_vars["DBZV"] = 10 * np.log10(radar.refl(scatterer, h_pol=False))  # dBZ
 
         radar_vars["ZDR"] = 10 * np.log10(radar.Zdr(scatterer))  # dB
-        if ~np.isfinite(radar_vars["ZDR"]):
-            radar_vars["ZDR"] = np.nan
+        radar_vars["ZDR"] = np.where(np.isfinite(radar_vars["ZDR"]), radar_vars["ZDR"], np.nan)
 
         radar_vars["LDR"] = 10 * np.log10(radar.ldr(scatterer))  # dBZ
-        if ~np.isfinite(radar_vars["LDR"]):
-            radar_vars["LDR"] = np.nan
+        radar_vars["LDR"] = np.where(np.isfinite(radar_vars["LDR"]), radar_vars["LDR"], np.nan)
 
         radar_vars["RHOHV"] = radar.rho_hv(scatterer)  # deg/km
         radar_vars["DELTAHV"] = radar.delta_hv(scatterer) * 180.0 / np.pi  # [deg]
@@ -482,29 +515,26 @@ def compute_radar_variables(scatterer):
 RADAR_VARIABLES = ["DBZH", "DBZV", "ZDR", "LDR", "RHOHV", "DELTAHV", "KDP", "AH", "AV", "ADP"]
 
 
-def _initialize_null_output(output_dictionary):
-    if output_dictionary:
-        return dict.fromkeys(RADAR_VARIABLES, np.nan)
-    return np.zeros(len(RADAR_VARIABLES)) * np.nan
+def _try_compute_radar_variables(scatterer):
+    with suppress_warnings():
+        try:
+            radar_vars = compute_radar_variables(scatterer)
+            output = np.array(list(radar_vars.values()))
+        except Exception:
+            output = np.zeros(len(RADAR_VARIABLES)) * np.nan
+    return output
 
 
 def _estimate_empirical_radar_parameters(
     drop_number_concentration,
     bin_edges,
     scatterer,
-    output_dictionary,
 ):
     # Assign PSD model to the scatterer object
     scatterer.psd = BinnedPSD(bin_edges, drop_number_concentration)
 
     # Get radar variables
-    with suppress_warnings():
-        try:
-            radar_vars = compute_radar_variables(scatterer)
-            output = radar_vars if output_dictionary else np.array(list(radar_vars.values()))
-        except Exception:
-            output = _initialize_null_output(output_dictionary)
-    return output
+    return _try_compute_radar_variables(scatterer)
 
 
 def _estimate_model_radar_parameters(
@@ -512,23 +542,16 @@ def _estimate_model_radar_parameters(
     psd_model,
     psd_parameters_names,
     scatterer,
-    output_dictionary,
 ):
     # Assign PSD model to the scatterer object
     parameters = dict(zip(psd_parameters_names, parameters))
     scatterer.psd = create_psd(psd_model, parameters)
 
     # Get radar variables
-    with suppress_warnings():
-        try:
-            radar_vars = compute_radar_variables(scatterer)
-            output = radar_vars if output_dictionary else np.array(list(radar_vars.values()))
-        except Exception:
-            output = _initialize_null_output(output_dictionary)
-    return output
+    return _try_compute_radar_variables(scatterer)
 
 
-def get_psd_parameters(ds):
+def select_psd_parameters(ds):
     """Return a xr.Dataset with only the PSD parameters as variable."""
     psd_model = ds.attrs["disdrodb_psd_model"]
     required_parameters = get_required_parameters(psd_model)
@@ -587,14 +610,14 @@ def get_model_radar_parameters(
     # Retrieve psd model and parameters.
     psd_model = ds.attrs["disdrodb_psd_model"]
     required_parameters = get_required_parameters(psd_model)
-    ds_parameters = get_psd_parameters(ds)
+    ds_parameters = select_psd_parameters(ds)
 
     # Check argument validity
     axis_ratio_model = check_axis_ratio_model(axis_ratio_model)
     permittivity_model = check_permittivity_model(permittivity_model)
 
     # Create DataArray with PSD parameters
-    da_parameters = ds_parameters.to_array(dim="psd_parameters").compute()
+    da_parameters = ds_parameters.to_array(dim="psd_parameters")
 
     # Initialize scattering table
     scatterer = load_scatterer(
@@ -610,7 +633,6 @@ def get_model_radar_parameters(
 
     # Define kwargs
     kwargs = {
-        "output_dictionary": False,
         "psd_model": psd_model,
         "psd_parameters_names": required_parameters,
         "scatterer": scatterer,
@@ -624,9 +646,10 @@ def get_model_radar_parameters(
         input_core_dims=[["psd_parameters"]],
         output_core_dims=[["radar_variables"]],
         vectorize=True,
-        dask="forbidden",
+        dask="parallelized",
         dask_gufunc_kwargs={
             "output_sizes": {"radar_variables": len(RADAR_VARIABLES)},
+            "allow_rechunk": True,
         },  # lengths of the new output_core_dims dimensions.
         output_dtypes=["float64"],
     )
@@ -695,7 +718,7 @@ def get_empirical_radar_parameters(
     ds = filter_diameter_bins(ds=ds, maximum_diameter=diameter_max)
 
     # Define inputs
-    da_drop_number_concentration = ds["drop_number_concentration"].compute()
+    da_drop_number_concentration = ds["drop_number_concentration"]  # .compute()
 
     # Set all zeros drop number concentration to np.nan
     # --> Otherwise inf can appear in the output
@@ -724,11 +747,9 @@ def get_empirical_radar_parameters(
 
     # Define kwargs
     kwargs = {
-        "output_dictionary": False,
         "bin_edges": bin_edges,
         "scatterer": scatterer,
     }
-
     # Loop over each PSD (not in parallel --> dask="forbidden")
     # - It costs much more to initiate the scatterer rather than looping over timesteps !
     da_radar = xr.apply_ufunc(
@@ -738,13 +759,12 @@ def get_empirical_radar_parameters(
         input_core_dims=[["diameter_bin_center"]],
         output_core_dims=[["radar_variables"]],
         vectorize=True,
-        dask="forbidden",
+        dask="parallelized",
         dask_gufunc_kwargs={
             "output_sizes": {"radar_variables": len(RADAR_VARIABLES)},
         },  # lengths of the new output_core_dims dimensions.
         output_dtypes=["float64"],
     )
-
     # Finalize radar dataset (add name, coordinates)
     ds_radar = _finalize_radar_dataset(
         da_radar=da_radar,
@@ -922,11 +942,11 @@ def get_radar_parameters(
     # Model-based simulation
     if "disdrodb_psd_model" in ds.attrs:
         func = get_model_radar_parameters
-        ds_subset = get_psd_parameters(ds).compute()
+        ds_subset = select_psd_parameters(ds)
     # Empirical PSD simulation
     else:
         func = get_empirical_radar_parameters
-        ds_subset = ds[["drop_number_concentration"]].compute()
+        ds_subset = ds[["drop_number_concentration"]]
 
     # Define default frequencies if not specified
     if frequency is None: