disdrodb 0.1.3__py3-none-any.whl → 0.1.4__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,33 @@ def run_l2m_station(
         ],
     )
     # Execute command
-    _execute_cmd(cmd)
+    execute_cmd(cmd)
+
+
+def create_summary_station(
+    data_source,
+    campaign_name,
+    station_name,
+    parallel=False,
+    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),
+        ],
+    )
+    # Execute command
+    execute_cmd(cmd)
 
 
 ####--------------------------------------------------------------------------.
@@ -1409,4 +1435,66 @@ 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,
+    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,
+        )
+    print("Creation of station summaries has terminated.")
+
+
 ####--------------------------------------------------------------------------.

disdrodb/scattering/axis_ratio.py

@@ -295,6 +295,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 +313,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 +351,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
 
 

disdrodb/scattering/permittivity.py

@@ -124,6 +124,24 @@ 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)
 

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: