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

disdrodb/cli/disdrodb_open_data_archive.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 @@
 """Routine to open the DISDRODB Data Archive."""
 
 import sys
-from typing import Optional
 
 import click
 
@@ -34,16 +31,23 @@ sys.tracebacklimit = 0  # avoid full traceback error if occur
 @click.command()
 @click_data_archive_dir_option
 def disdrodb_open_data_archive(
-    data_archive_dir: Optional[str] = None,
+    data_archive_dir: str | None = None,
 ):
-    """Open the DISDRODB Data Archive.
-
-    Parameters
-    ----------
-    data_archive_dir : str, optional
-        The base directory of DISDRODB, expected in the format ``<...>/DISDRODB``.
-        If not specified, the path specified in the DISDRODB active configuration will be used.
-    """
+    """Open the DISDRODB Data Archive directory in the system file explorer.
+
+    \b
+    Archive Directory:
+        --data_archive_dir: Custom path to DISDRODB data archive
+        If not specified, the path from the active DISDRODB configuration is used
+
+    \b
+    Examples:
+        # Open the data archive from active configuration
+        disdrodb_open_data_archive
+
+        # Open a custom data archive directory
+        disdrodb_open_data_archive --data_archive_dir /path/to/DISDRODB
+    """  # noqa: D301
     from disdrodb.api.io import open_data_archive
 
     data_archive_dir = parse_archive_dir(data_archive_dir)

disdrodb/cli/disdrodb_open_logs_directory.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 @@
 """Routine to open the DISDRODB Data Archive logs directory."""
 
 import sys
-from typing import Optional
 
 import click
 
@@ -38,25 +35,38 @@ sys.tracebacklimit = 0  # avoid full traceback error if occur
 def disdrodb_open_logs_directory(
     data_source: str,
     campaign_name: str,
-    station_name: Optional[str] = None,
-    data_archive_dir: Optional[str] = None,
+    station_name: str | None = None,
+    data_archive_dir: str | None = None,
 ):
-    """Open the DISDRODB Data Archive logs directory of a station.
+    """Open the DISDRODB Data Archive station logs directory in the system file explorer.
+
+    It allows to easily browse processing logs and error reports.
+
+    \b
+    Station Specification:
+        Requires data_source and campaign_name (UPPER CASE required).
+        station_name is optional.
+
+    \b
+    Archive Directory:
+        --data_archive_dir: Custom path to DISDRODB data archive
+        If not specified, the path from the active DISDRODB configuration is used
+
+    \b
+    Examples:
+        # Open logs directory for a specific station
+        disdrodb_open_logs_directory EPFL HYMEX_LTE_SOP2 10
+
+        # Open logs directory for an entire campaign
+        disdrodb_open_logs_directory NASA IFLOODS
+
+        # Open with custom data archive directory
+        disdrodb_open_logs_directory EPFL HYMEX_LTE_SOP2 10 --data_archive_dir /path/to/DISDRODB
 
-    Parameters
-    ----------
-    data_source : str
-        The name of the institution (for campaigns spanning multiple countries) or
-        the name of the country (for campaigns or sensor networks within a single country).
-        Must be provided in UPPER CASE.
-    campaign_name : str
-        The name of the campaign. Must be provided in UPPER CASE.
-    station_name : str
-        The name of the station.
-    data_archive_dir : str, optional
-        The base directory of DISDRODB, expected in the format ``<...>/DISDRODB``.
-        If not specified, the path specified in the DISDRODB active configuration will be used.
-    """
+    \b
+    Important Notes:
+        - Data source and campaign names must be in UPPER CASE
+    """  # noqa: D301
     from disdrodb.api.io import open_logs_directory
 
     data_archive_dir = parse_archive_dir(data_archive_dir)

disdrodb/cli/disdrodb_open_metadata_archive.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 @@
 """Routine to open the DISDRODB Metadata Data Archive."""
 
 import sys
-from typing import Optional
 
 import click
 
@@ -34,16 +31,32 @@ sys.tracebacklimit = 0  # avoid full traceback error if occur
 @click.command()
 @click_metadata_archive_dir_option
 def disdrodb_open_metadata_archive(
-    metadata_archive_dir: Optional[str] = None,
+    metadata_archive_dir: str | None = None,
 ):
-    """Open the DISDRODB Metadata Archive.
-
-    Parameters
-    ----------
-    metadata_archive_dir : str, optional
-        The base directory of DISDRODB, expected in the format ``<...>/DISDRODB``.
-        If not specified, the path specified in the DISDRODB active configuration will be used.
-    """
+    """Open the DISDRODB Metadata Archive directory in the system file explorer.
+
+    Opens the metadata archive directory using the system's default file manager,
+    allowing you to browse station metadata files and YAML configurations.
+
+    \b
+    Archive Directory:
+        --metadata_archive_dir: Custom path to DISDRODB metadata archive
+        If not specified, the path from the active DISDRODB configuration is used
+
+    \b
+    Examples:
+        # Open the metadata archive from active configuration
+        disdrodb_open_metadata_archive
+
+        # Open a custom metadata archive directory
+        disdrodb_open_metadata_archive --metadata_archive_dir /path/to/DISDRODB-METADATA/DISDRODB
+
+    \b
+    Important Notes:
+        - Opens the directory in your system's default file manager
+        - The metadata archive contains station YAML files and issue reports
+        - Useful for manual inspection and verification of station metadata
+    """  # noqa: D301
     from disdrodb.api.io import open_metadata_archive
 
     metadata_archive_dir = parse_archive_dir(metadata_archive_dir)

disdrodb/cli/disdrodb_open_metadata_directory.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 @@
 """Routine to open the DISDRODB Data Archive logs directory."""
 
 import sys
-from typing import Optional
 
 import click
 
@@ -38,27 +35,41 @@ sys.tracebacklimit = 0  # avoid full traceback error if occur
 def disdrodb_open_metadata_directory(
     data_source: str,
     campaign_name: str,
-    station_name: Optional[str] = None,
-    metadata_archive_dir: Optional[str] = None,
+    station_name: str | None = None,
+    metadata_archive_dir: str | None = None,
 ):
-    """Open the DISDRODB Data Archive logs directory of a station.
+    """Open the DISDRODB Metadata Archive directory of a station in the system file explorer.
+
+    The command allows to easily browse stations metadata YAML files.
+
+    \b
+    Station Specification:
+        Requires data_source and campaign_name (UPPER CASE required).
+        station_name is optional.
+
+    \b
+    Archive Directory:
+        --metadata_archive_dir: Custom path to DISDRODB Metadata Archive
+        If not specified, the path from the active DISDRODB configuration is used
+
+    \b
+    Examples:
+        # Open metadata directory for a specific station
+        disdrodb_open_metadata_directory EPFL HYMEX_LTE_SOP2 10
+
+        # Open metadata directory for a specific station
+        disdrodb_open_metadata_directory NASA IFLOODS
+
+        # Open with custom metadata archive directory
+        disdrodb_open_metadata_directory EPFL HYMEX_LTE_SOP2 --metadata_archive_dir /path/to/DISDRODB-METADATA/DISDRODB
 
-    Parameters
-    ----------
-    data_source : str
-        The name of the institution (for campaigns spanning multiple countries) or
-        the name of the country (for campaigns or sensor networks within a single country).
-        Must be provided in UPPER CASE.
-    campaign_name : str
-        The name of the campaign. Must be provided in UPPER CASE.
-    station_name : str
-        The name of the station.
-    metadata_archive_dir : str, optional
-        The directory path where the DISDRODB Metadata Archive is located.
-        The directory path must end with ``<...>/DISDRODB``.
-        If ``None``, it uses the ``metadata_archive_dir`` path specified
-        in the DISDRODB active configuration.
-    """
+    \b
+    Important Notes:
+        - Data source and campaign names must be in UPPER CASE
+        - Opens the directory in your system's default file manager
+        - Useful for manual inspection and editing of station metadata YAML files
+        - If station_name is omitted, opens the campaign-level metadata directory
+    """  # noqa: D301
     from disdrodb.api.io import open_metadata_directory
 
     metadata_archive_dir = parse_archive_dir(metadata_archive_dir)

disdrodb/cli/disdrodb_open_product_directory.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 @@
 """Routine to open the DISDRODB Data Archive station product directory."""
 
 import sys
-from typing import Optional
 
 import click
 
@@ -41,26 +38,45 @@ def disdrodb_open_product_directory(
     data_source: str,
     campaign_name: str,
     station_name: str,
-    data_archive_dir: Optional[str] = None,
+    data_archive_dir: str | None = None,
 ):
-    """Open the DISDRODB Data Archive logs directory of a station.
-
-    Parameters
-    ----------
-    product : str
-        DISDRODB product.
-    data_source : str
-        The name of the institution (for campaigns spanning multiple countries) or
-        the name of the country (for campaigns or sensor networks within a single country).
-        Must be provided in UPPER CASE.
-    campaign_name : str
-        The name of the campaign. Must be provided in UPPER CASE.
-    station_name : str
-        The name of the station.
-    data_archive_dir : str, optional
-        The base directory of DISDRODB, expected in the format ``<...>/DISDRODB``.
-        If not specified, the path specified in the DISDRODB active configuration will be used.
-    """
+    """Open the DISDRODB Data Archive station product directory in the system file explorer.
+
+    Opens the data archive directory for a specific product level (RAW, L0A, L0B, etc.)
+    of a station using the system's default file manager, allowing you to browse
+    the data files.
+
+    \b
+    Station Specification:
+        Requires exact specification of product, data_source, campaign_name, and station_name.
+        All parameters must be provided and are case-sensitive (UPPER CASE required).
+
+    \b
+    Product Levels:
+        Valid products: RAW, L0A, L0B, L0C, L1, L2E, L2M
+        Specify the product level you want to browse
+
+    \b
+    Archive Directory:
+        --data_archive_dir: Custom path to DISDRODB data archive
+        If not specified, the path from the active DISDRODB configuration is used
+
+    \b
+    Examples:
+        # Open Raw data directory for a station
+        disdrodb_open_product_directory RAW EPFL HYMEX_LTE_SOP2 10
+
+        # Open L0B product directory
+        disdrodb_open_product_directory L0B NASA IFLOODS apu01
+
+        # Open L2M directory with custom archive path
+        disdrodb_open_product_directory L2M EPFL HYMEX_LTE_SOP2 10 --data_archive_dir /path/to/DISDRODB
+
+    \b
+    Important Notes:
+        - Product name must be valid: RAW, L0A, L0B, L0C, L1, L2E, or L2M
+        - Data source, campaign, and station names must be in UPPER CASE
+    """  # noqa: D301
     from disdrodb.api.io import open_product_directory
 
     data_archive_dir = parse_archive_dir(data_archive_dir)

disdrodb/cli/disdrodb_open_readers_directory.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,6 +15,7 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
 """Routine to open the disdrodb software readers directory."""
+
 import sys
 
 import click

disdrodb/cli/disdrodb_run.py

@@ -0,0 +1,189 @@
+# -----------------------------------------------------------------------------.
+# 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
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# -----------------------------------------------------------------------------.
+"""Script to launch DISDRODB products generation for the entire DISDRODB Archive."""
+
+import sys
+
+import click
+
+from disdrodb.utils.cli import (
+    click_data_archive_dir_option,
+    click_l0_archive_options,
+    click_metadata_archive_dir_option,
+    click_processing_options,
+    click_stations_options,
+    parse_archive_dir,
+    parse_arg_to_list,
+)
+
+sys.tracebacklimit = 0  # avoid full traceback error if occur
+
+
+@click.command()
+@click_stations_options
+@click_l0_archive_options
+@click.option(
+    "-l1",
+    "--l1_processing",
+    type=bool,
+    show_default=True,
+    default=True,
+    help="Run L1 processing",
+)
+@click.option(
+    "-l2e",
+    "--l2e_processing",
+    type=bool,
+    show_default=True,
+    default=True,
+    help="Run L2E processing",
+)
+@click.option(
+    "-l2m",
+    "--l2m_processing",
+    type=bool,
+    show_default=True,
+    default=True,
+    help="Run L2M processing.",
+)
+@click_processing_options
+@click_data_archive_dir_option
+@click_metadata_archive_dir_option
+def disdrodb_run(
+    # Stations options
+    data_sources: str | None = None,
+    campaign_names: str | None = None,
+    station_names: str | None = None,
+    # L0 archive options
+    l0a_processing: bool = True,
+    l0b_processing: bool = True,
+    l0c_processing: bool = True,
+    remove_l0a: bool = False,
+    remove_l0b: bool = False,
+    # Higher level processing options
+    l1_processing: bool = True,
+    l2e_processing: bool = True,
+    l2m_processing: bool = True,
+    # Processing options
+    force: bool = False,
+    verbose: bool = True,
+    parallel: bool = True,
+    debugging_mode: bool = False,
+    # DISDRODB root directories
+    data_archive_dir: str | None = None,
+    metadata_archive_dir: str | None = None,
+):
+    """Run the complete processing of DISDRODB stations.
+
+    This function allows to launch the complete processing of many DISDRODB stations with a single command.
+    From the list of all available DISDRODB stations, it runs the processing of the
+    stations matching the provided data_sources, campaign_names and station_names.
+
+    \b
+    Processing Levels:
+        L0A: Raw data converted to DISDRODB standardized Apache Parquet format
+        L0B: L0A data converted to DISDRODB standardized netCDF4 format
+        L0C: Apply time QC and consolidate L0B data into (by default daily) netCDF files.
+        L1:  Temporally resample L0C data to standard intervals (1-60 minutes), apply QC algorithms
+        and determine precipitation phase and hydrometeors types.
+        L2E: Compute empirical integral DSD variables (e.g., rain rate, liquid water content)
+        L2M: Fit parametric DSD models and compute model-based integral DSD variables
+
+    \b
+    Station Selection:
+        If no station filters are specified, processes ALL available stations.
+        Use data_sources, campaign_names, and station_names to filter stations.
+        Filters work together to narrow down the selection (AND logic).
+
+    \b
+    Performance Options:
+        --parallel: Uses multiple processes for faster processing (default: True)
+        If parallel processing is enabled, each process will use a single thread
+        to avoid issues with the HDF/netCDF library.
+        The DASK_NUM_WORKERS environment variable controls the number of processes
+        to use.A sensible default is automatically set by the software.
+        --debugging_mode: Processes only a subset of data for testing
+        --force: Overwrites existing output files (default: False)
+
+    \b
+    Examples:
+        # Process all stations with full processing chain
+        disdrodb_run
+
+        # Process specific data sources, skip L0A and L2M
+        disdrodb_run --data_sources 'USA EPFL' --l0a_processing False --l2m_processing False
+
+        # Process specific campaigns with debugging mode
+        disdrodb_run --campaign_names 'DELFT IMPACTS' --debugging_mode True
+
+        # Process specific stations with custom number of workers
+        DASK_NUM_WORKERS=8 disdrodb_run --data_sources 'NASA' --station_names 'apu01 apu02'
+
+        # Force overwrite existing files, verbose output
+        disdrodb_run --data_sources 'EPFL' --force True --verbose True
+
+    \b
+    Data Management:
+        --remove_l0a: Delete L0A files after L0B processing (saves disk space)
+        --remove_l0b: Delete L0B files after L0C processing (saves disk space)
+        Use with caution - removed files cannot be recovered without reprocessing
+
+    \b
+    Important Notes:
+        - Data source names must be UPPER CASE
+        - Campaign names must be UPPER CASE
+        - To specify multiple values, use space-separated strings in quotes
+        - Processing chain: L0A → L0B → L0C → L1 → L2E → L2M
+        - You can skip early or late processing levels, but not intermediate ones
+        - Processing validates chain consistency and will raise errors for gaps
+        - Large datasets may require significant disk space and processing time
+        - Use --debugging_mode for initial testing with reduced data volumes
+    """  # noqa: D301
+    from disdrodb.routines import run
+
+    # Parse data_sources, campaign_names and station arguments
+    data_archive_dir = parse_archive_dir(data_archive_dir)
+    metadata_archive_dir = parse_archive_dir(metadata_archive_dir)
+    data_sources = parse_arg_to_list(data_sources)
+    campaign_names = parse_arg_to_list(campaign_names)
+    station_names = parse_arg_to_list(station_names)
+
+    # Run processing
+    run(
+        # DISDRODB root directories
+        data_archive_dir=data_archive_dir,
+        metadata_archive_dir=metadata_archive_dir,
+        # Stations options
+        data_sources=data_sources,
+        campaign_names=campaign_names,
+        station_names=station_names,
+        # L0 archive options
+        l0a_processing=l0a_processing,
+        l0b_processing=l0b_processing,
+        l0c_processing=l0c_processing,
+        remove_l0a=remove_l0a,
+        remove_l0b=remove_l0b,
+        # Higher level processing options
+        l1_processing=l1_processing,
+        l2e_processing=l2e_processing,
+        l2m_processing=l2m_processing,
+        # Processing options
+        force=force,
+        verbose=verbose,
+        debugging_mode=debugging_mode,
+        parallel=parallel,
+    )