disdrodb 0.1.2__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
@@ -91,7 +91,7 @@ def run_l0_station(
     debugging_mode : bool
         If ``True``, it reduces the amount of data to process.
         For L0A, it processes just the first 3 raw data files for each station.
-        For L0B, it processes just the first 100 rows of 3 L0A files for each station.
+        For L0B, it processes 100 rows sampled from 3 L0A files for each station.
         The default value is ``False``.
     data_archive_dir : str (optional)
         The directory path where the DISDRODB Data Archive is located.
@@ -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)
 
 
 ####--------------------------------------------------------------------------.
@@ -794,7 +820,7 @@ def run_l0b(
         If ``False``, the files are processed sequentially in a single process.
     debugging_mode : bool
         If ``True``, it reduces the amount of data to process.
-        For L0B, it processes just the first 100 rows of 3 L0A files.
+        For L0B, it processes 100 rows sampled from 3 L0A files.
         The default value is ``False``.
     data_archive_dir : str (optional)
         The directory path where the DISDRODB Data Archive is located.
@@ -1033,7 +1059,7 @@ def run_l0(
     debugging_mode : bool
         If ``True``, it reduces the amount of data to process.
         For L0A, it processes just the first 3 raw data files.
-        For L0B, it processes just the first 100 rows of 3 L0A files.
+        For L0B, it processes 100 rows sampled from 3 L0A files.
         The default value is ``False``.
     data_archive_dir : str (optional)
         The directory path where the DISDRODB Data Archive is located.
@@ -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/__init__.py

@@ -17,12 +17,24 @@
 """Implement PSD scattering routines."""
 
 
-from disdrodb.scattering.axis_ratio import available_axis_ratio, get_axis_ratio
-from disdrodb.scattering.routines import available_radar_bands, get_radar_parameters
+from disdrodb.scattering.axis_ratio import available_axis_ratio_models, get_axis_ratio_model
+from disdrodb.scattering.permittivity import available_permittivity_models, get_refractive_index
+from disdrodb.scattering.routines import (
+    RADAR_OPTIONS,
+    RADAR_VARIABLES,
+    available_radar_bands,
+    get_radar_parameters,
+    load_scatterer,
+)
 
 __all__ = [
-    "available_axis_ratio",
+    "RADAR_OPTIONS",
+    "RADAR_VARIABLES",
+    "available_axis_ratio_models",
+    "available_permittivity_models",
     "available_radar_bands",
-    "get_axis_ratio",
+    "get_axis_ratio_model",
     "get_radar_parameters",
+    "get_refractive_index",
+    "load_scatterer",
 ]

disdrodb/scattering/axis_ratio.py

@@ -14,70 +14,90 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
-"""Implement drop axis ratio theoretical models."""
+"""Implement drop (vertical-to-horizontal) axis ratio theoretical models."""
 
 import numpy as np
 import xarray as xr
 
 
-def available_axis_ratio():
-    """Return a list of the available drop axis ratio methods."""
-    return list(AXIS_RATIO_METHODS)
+def available_axis_ratio_models():
+    """Return a list of the available drop axis ratio models."""
+    return list(AXIS_RATIO_MODELS)
 
 
-def get_axis_ratio_method(method):
-    """Return the specified drop axis ratio method."""
-    method = check_axis_ratio(method)
-    return AXIS_RATIO_METHODS[method]
+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.
 
-def check_axis_ratio(method):
-    """Check validity of the specified drop axis ratio method."""
-    available_methods = available_axis_ratio()
-    if method not in available_methods:
-        raise ValueError(f"{method} is an invalid axis-ratio method. Valid methods: {available_methods}.")
-    return method
+    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 !
 
-def get_axis_ratio(diameter, method):
     """
-    Compute the axis ratio of raindrops using the specified method.
+    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.
-    method : str
-        The method to use for calculating the axis ratio. Available methods are:
+    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
-        Calculated axis ratios corresponding to the input diameters.
-
-    Raises
-    ------
-    ValueError
-        If the specified method is not one of the available methods.
+        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 `method` parameter.
+    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, method="Brandes2002")
+    >>> axis_ratio = get_axis_ratio(diameter, model="Brandes2002")
 
     """
     # Retrieve axis ratio function
-    func = get_axis_ratio_method(method)
+    axis_ratio_func = get_axis_ratio_model(model)
 
     # Retrieve axis ratio
-    axis_ratio = func(diameter)
+    axis_ratio = axis_ratio_func(diameter)
 
     # Clip values between 0 and 1
     axis_ratio = np.clip(axis_ratio, 0, 1)
@@ -86,7 +106,7 @@ def get_axis_ratio(diameter, method):
 
 def get_axis_ratio_andsager_1999(diameter):
     """
-    Compute the axis ratio of raindrops using the Andsager et al. (1999) method.
+    Compute the axis ratio of raindrops using the Andsager et al. (1999) model.
 
     Parameters
     ----------
@@ -145,7 +165,7 @@ def get_axis_ratio_andsager_1999(diameter):
 
 def get_axis_ratio_battaglia_2010(diameter):
     """
-    Compute the axis ratio of raindrops using the Battaglia et al. (2010) method.
+    Compute the axis ratio of raindrops using the Battaglia et al. (2010) model.
 
     Parameters
     ----------
@@ -185,7 +205,7 @@ def get_axis_ratio_battaglia_2010(diameter):
 
 def get_axis_ratio_beard_1987(diameter):
     """
-    Compute the axis ratio of raindrops using the Beard and Chuang (1987) method.
+    Compute the axis ratio of raindrops using the Beard and Chuang (1987) model.
 
     Parameters
     ----------
@@ -214,7 +234,7 @@ def get_axis_ratio_beard_1987(diameter):
 
 def get_axis_ratio_brandes_2002(diameter):
     """
-    Compute the axis ratio of raindrops using the Brandes et al. (2002) method.
+    Compute the axis ratio of raindrops using the Brandes et al. (2002) model.
 
     Parameters
     ----------
@@ -243,7 +263,7 @@ def get_axis_ratio_brandes_2002(diameter):
 
 def get_axis_ratio_pruppacher_1970(diameter):
     """
-    Compute the axis ratio of raindrops using the Pruppacher and Pitter (1971) method.
+    Compute the axis ratio of raindrops using the Pruppacher and Pitter (1971) model.
 
     Parameters
     ----------
@@ -273,7 +293,9 @@ def get_axis_ratio_pruppacher_1970(diameter):
 
 def get_axis_ratio_thurai_2005(diameter):
     """
-    Compute the axis ratio of raindrops using the Thurai et al. (2005) method.
+    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
     ----------
@@ -291,13 +313,12 @@ 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
 
 
 def get_axis_ratio_thurai_2007(diameter):
-    """Compute the axis ratio of raindrops using the Thurai et al. (2007) method.
+    """Compute the axis ratio of raindrops using the Thurai et al. (2007) model.
 
     Parameters
     ----------
@@ -330,10 +351,13 @@ 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
 
 
-AXIS_RATIO_METHODS = {
+AXIS_RATIO_MODELS = {
     "Thurai2005": get_axis_ratio_thurai_2005,
     "Thurai2007": get_axis_ratio_thurai_2007,
     "Battaglia2010": get_axis_ratio_battaglia_2010,