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

disdrodb/cli/disdrodb_run_l2e_station.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
@@ -53,42 +53,46 @@ def disdrodb_run_l2e_station(
     data_archive_dir: Optional[str] = None,
     metadata_archive_dir: Optional[str] = None,
 ):
-    """
-    Run the L2E processing of a specific DISDRODB station from the terminal.
-
-    Parameters
-    ----------
-    data_source : str
-        Institution name (when campaign data spans more than 1 country),
-        or country (when all campaigns (or sensor networks) are inside a given country).
-        Must be UPPER CASE.
-    campaign_name : str
-        Campaign name. Must be UPPER CASE.
-    station_name : str
-        Station name
-    force : bool
-        If True, overwrite existing data into destination directories.
-        If False, raise an error if there are already data into destination directories.
-        The default is False.
-    verbose : bool
-        Whether to print detailed processing information into terminal.
-        The default is True.
-    parallel : bool
-        If True, the files are processed simultaneously in multiple processes.
-        Each process will use a single thread.
-        By default, the number of process is defined with os.cpu_count().
-        However, you can customize it by typing: DASK_NUM_WORKERS=4 disdrodb_run_l0a_station
-        If False, the files are processed sequentially in a single process.
-        If False, multi-threading is automatically exploited to speed up I/0 tasks.
-    debugging_mode : bool
-        If True, it reduces the amount of data to process.
-        It processes just the first 3 raw data files.
-        The default is False.
-    data_archive_dir : str
-        DISDRODB Data Archive directory.
-        Format: <...>/DISDRODB
-        If not specified, uses path specified in the DISDRODB active configuration.
-    """
+    """Run the DISDRODB L2E processing chain for a specific DISDRODB station.
+
+    It produces DISDRODB L2E files from existing DISDRODB L1 data of the specified station.
+    DISDRODB L1 files must be available before launching the DISDRODB L2E processing.
+
+    The DISDRODB L2E processing chain filters the disdrometer raw spectra,
+    compute empirical integral DSD variables and optionally simulate
+    polarimetric radar variables at multiple frequencies.
+
+    \b
+    Station Specification:
+        Requires exact specification of data_source, campaign_name, and station_name.
+        All three parameters must be provided and are case-sensitive (UPPER CASE required).
+
+    \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 a single station with full processing chain
+        disdrodb_run_l2e_station EPFL HYMEX_LTE_SOP2 10
+
+        # Force overwrite existing files with verbose output
+        disdrodb_run_l2e_station EPFL HYMEX_LTE_SOP2 10 --force True --verbose True
+
+        # Process station with debugging mode and custom workers
+        DASK_NUM_WORKERS=4 disdrodb_run_l2e_station NETHERLANDS DELFT PAR001_Cabauw --debugging_mode True
+
+    \b
+    Important Notes:
+        - Data source, campaign, and station names must be UPPER CASE
+        - All three station identifiers are required (no wildcards or filtering)
+    """  # noqa: D301
     from disdrodb.routines.l2 import run_l2e_station
     from disdrodb.utils.dask import close_dask_cluster, initialize_dask_cluster
 

disdrodb/cli/disdrodb_run_l2m.py

@@ -1,6 +1,6 @@
 #!/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
@@ -52,50 +52,54 @@ def disdrodb_run_l2m(
     data_archive_dir: Optional[str] = None,
     metadata_archive_dir: Optional[str] = None,
 ):
-    """
-    Run the L2M processing of DISDRODB stations.
-
-    This function allows to launch the 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.
-
-    Parameters
-    ----------
-    data_sources : str
-        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.
-        To specify multiple data sources, write i.e.: --data_sources 'NASA EPFL NCAR'
-    campaign_names : str
-        Name of the campaign(s) to process.
-        The name(s) must be UPPER CASE.
-        To specify multiple campaigns, write i.e.: --campaign_names 'IPEX IMPACTS'
-    station_names : str
-        Station names.
-        To specify multiple stations, write i.e.: --station_names 'station1 station2'
-    force : bool
-        If True, overwrite existing data into destination directories.
-        If False, raise an error if there are already data into destination directories.
-        The default is False.
-    verbose : bool
-        Whether to print detailed processing information into terminal.
-        The default is False.
-    parallel : bool
-        If True, the files are processed simultaneously in multiple processes.
-        Each process will use a single thread.
-        By default, the number of process is defined with os.cpu_count().
-        However, you can customize it by typing: DASK_NUM_WORKERS=4 disdrodb_run_l0a
-        If False, the files are processed sequentially in a single process.
-        If False, multi-threading is automatically exploited to speed up I/0 tasks.
-    debugging_mode : bool
-        If True, it reduces the amount of data to process.
-        It processes just the first 3 raw data files for each station.
-        The default is False.
-    data_archive_dir : str
-        DISDRODB Data Archive directory
-        Format: <...>/DISDRODB
-        If not specified, uses path specified in the DISDRODB active configuration.
-    """
+    """Run the DISDRODB L2M processing chain for many/all DISDRODB stations.
+
+    It produces DISDRODB L2M files from existing DISDRODB L2E data of the specified stations.
+    DISDRODB L2E files must be available before launching the DISDRODB L2M processing.
+
+    The  DISDRODB L2M processing chain fits parametric DSD models
+    to the empirical DSDs and computes 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
+        disdrodb_run_l2m
+
+        # Process a specific data source and force overwrite existing files
+        disdrodb_run_l2m --data_sources EPFL --force True --verbose True
+
+        # Process specific data sources
+        disdrodb_run_l2m --data_sources 'USA EPFL'
+
+        # Process specific campaigns in debugging mode
+        disdrodb_run_l2m --campaign_names 'DELFT IMPACTS' --debugging_mode True
+
+        # Process specific stations with custom number of workers
+        DASK_NUM_WORKERS=8 disdrodb_run_l2m --data_sources NASA --station_names 'apu01 apu02'
+
+    \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
+        - Use --debugging_mode for initial testing with reduced data volumes
+    """  # noqa: D301
     from disdrodb.routines import run_l2m
 
     # Parse data_sources, campaign_names and station arguments

disdrodb/cli/disdrodb_run_l2m_station.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
@@ -53,42 +53,45 @@ def disdrodb_run_l2m_station(
     data_archive_dir: Optional[str] = None,
     metadata_archive_dir: Optional[str] = None,
 ):
-    """
-    Run the L2M processing of a specific DISDRODB station from the terminal.
-
-    Parameters
-    ----------
-    data_source : str
-        Institution name (when campaign data spans more than 1 country),
-        or country (when all campaigns (or sensor networks) are inside a given country).
-        Must be UPPER CASE.
-    campaign_name : str
-        Campaign name. Must be UPPER CASE.
-    station_name : str
-        Station name
-    force : bool
-        If True, overwrite existing data into destination directories.
-        If False, raise an error if there are already data into destination directories.
-        The default is False.
-    verbose : bool
-        Whether to print detailed processing information into terminal.
-        The default is True.
-    parallel : bool
-        If True, the files are processed simultaneously in multiple processes.
-        Each process will use a single thread.
-        By default, the number of process is defined with os.cpu_count().
-        However, you can customize it by typing: DASK_NUM_WORKERS=4 disdrodb_run_l0a_station
-        If False, the files are processed sequentially in a single process.
-        If False, multi-threading is automatically exploited to speed up I/0 tasks.
-    debugging_mode : bool
-        If True, it reduces the amount of data to process.
-        It processes just the first 3 raw data files.
-        The default is False.
-    data_archive_dir : str
-        DISDRODB Data Archive directory.
-        Format: <...>/DISDRODB
-        If not specified, uses path specified in the DISDRODB active configuration.
-    """
+    """Run the DISDRODB L2M processing chain for a specific DISDRODB station.
+
+    It produces L2M files from existing DISDRODB L2E data of the specified station.
+    DISDRODB L2E files must be available before launching the DISDRODB L2M processing.
+
+    The DISDRODB L2M processing chain fits parametric DSD models to the
+    empirical DSDs and computes model-based integral DSD variables.
+
+    \b
+    Station Specification:
+        Requires exact specification of data_source, campaign_name, and station_name.
+        All three parameters must be provided and are case-sensitive (UPPER CASE required).
+
+    \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 a single station with full processing chain
+        disdrodb_run_l2m_station EPFL HYMEX_LTE_SOP2 10
+
+        # Force overwrite existing files with verbose output
+        disdrodb_run_l2m_station EPFL HYMEX_LTE_SOP2 10 --force True --verbose True
+
+        # Process station with debugging mode and custom workers
+        DASK_NUM_WORKERS=4 disdrodb_run_l2m_station NETHERLANDS DELFT PAR001_Cabauw --debugging_mode True
+
+    \b
+    Important Notes:
+        - Data source, campaign, and station names must be UPPER CASE
+        - All three station identifiers are required (no wildcards or filtering)
+    """  # noqa: D301
     from disdrodb.routines.l2 import run_l2m_station
     from disdrodb.utils.dask import close_dask_cluster, initialize_dask_cluster
 

disdrodb/cli/disdrodb_run_station.py

@@ -0,0 +1,184 @@
+# -----------------------------------------------------------------------------.
+# 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 all DISDRODB products generation for a given station."""
+import sys
+from typing import Optional
+
+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_station_arguments,
+    parse_archive_dir,
+)
+
+sys.tracebacklimit = 0  # avoid full traceback error if occur
+
+
+# -------------------------------------------------------------------------.
+# Click Command Line Interface decorator
+@click.command()
+@click_station_arguments
+@click_processing_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_data_archive_dir_option
+@click_metadata_archive_dir_option
+def disdrodb_run_station(
+    # Station arguments
+    data_source: str,
+    campaign_name: str,
+    station_name: str,
+    # 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: Optional[str] = None,
+    metadata_archive_dir: Optional[str] = None,
+):
+    """Run the complete processing of a specific DISDRODB station.
+
+    This function processes a single station through the complete DISDRODB processing
+    chain, from raw data ingestion to final derived products. All processing levels
+    are executed in sequence for the specified station.
+
+    \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 Specification:
+        Requires exact specification of data_source, campaign_name, and station_name.
+        All three parameters must be provided and are case-sensitive (UPPER CASE required).
+
+    \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 a single station with full processing chain
+        disdrodb_run_station EPFL HYMEX_LTE_SOP2 10
+
+        # Process station, skip L0A processing (start from existing L0B data)
+        disdrodb_run_station NASA IFLOODS apu01 --l0a_processing False
+
+        # Process station with debugging mode and custom workers
+        DASK_NUM_WORKERS=4 disdrodb_run_station NETHERLANDS DELFT PAR001_Cabauw --debugging_mode True
+
+        # Process station, skip final L2M level
+        disdrodb_run_station FRANCE ENPC_CARNOT Carnot_Pars1 --l2m_processing False
+
+        # Force overwrite existing files with verbose output
+        disdrodb_run_station EPFL HYMEX_2012 10 --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, campaign, and station names must be UPPER CASE
+        - All three station identifiers are required (no wildcards or filtering)
+        - 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
+        - Station-specific processing may require significant time for large datasets
+        - Use --debugging_mode for initial testing with reduced data volumes
+    """  # noqa: D301
+    from disdrodb.routines import run_station
+
+    data_archive_dir = parse_archive_dir(data_archive_dir)
+    metadata_archive_dir = parse_archive_dir(metadata_archive_dir)
+
+    run_station(
+        # DISDRODB root directories
+        data_archive_dir=data_archive_dir,
+        metadata_archive_dir=metadata_archive_dir,
+        # Station arguments
+        data_source=data_source,
+        campaign_name=campaign_name,
+        station_name=station_name,
+        # 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,
+    )

disdrodb/cli/disdrodb_upload_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
@@ -51,38 +49,50 @@ def disdrodb_upload_archive(
     platform: Optional[str] = None,
     force: bool = False,
 ):
-    """Find all stations containing local data and upload them to a remote repository.
-
-    Parameters
-    ----------
-    platform: str, optional
-        Name of the remote platform.
-        The default platform is ``"sandbox.zenodo"`` (for testing purposes).
-        Switch to ``"zenodo"`` for final data dissemination.
-    force: bool, optional
-        If ``True``, upload even if data already exists on another remote location.
-        The default value is ``force=False``.
-    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.
-
-    Other Parameters
-    ----------------
-    data_sources: str or list of str, optional
-        Data source name (eg: EPFL).
-        If not provided (``None``), all data sources will be uploaded.
-        The default value is ``data_source=None``.
-    campaign_names: str or list of str, optional
-        Campaign name (eg:  EPFL_ROOF_2012).
-        If not provided (``None``), all campaigns will be uploaded.
-        The default value is ``campaign_name=None``.
-    station_names: str or list of str, optional
-        Station name.
-        If not provided (``None``), all stations will be uploaded.
-        The default value is ``station_name=None``.
-    """
+    """Upload raw data for multiple DISDRODB stations to the DISDRODB Decentralized Data Archive.
+
+    Currently, only upload to the Zenodo data repository is implemented.
+    The station metadata files are automatically updated with the remote data URL.
+
+    PLEASE UPLOAD JUST YOUR DATA !
+
+    \b
+    Station Selection:
+        If no station filters are specified, uploads ALL stations with local data.
+        Use data_sources, campaign_names, and station_names to filter stations.
+        Filters work together to narrow down the selection (AND logic).
+        Only stations with local raw data files will be uploaded.
+
+    \b
+    Upload Behavior:
+        By default, upload is skipped if data already exists on a remote location.
+        Use '--force True' to upload even if data already exists remotely.
+        Warning: Forcing upload may create duplicate versions on the remote platform.
+
+    \b
+    Upload Options:
+        --platform: Remote platform name (default: 'sandbox.zenodo' for testing)
+        Use 'zenodo' for final data dissemination.
+        --force: Upload even if data already exists remotely (default: False)
+
+    \b
+    Archive Directories:
+        --data_archive_dir: Custom path to DISDRODB data archive
+        --metadata_archive_dir: Custom path to DISDRODB metadata archive
+        If not specified, paths from the active DISDRODB configuration are used
+
+    \b
+    Examples:
+
+        # Upload a specific data sources to Zenodo Sandbox
+        disdrodb_upload_archive --data_sources 'YOUR_DATA_SOURCE' --platform sandbox.zenodo
+
+        # Upload a specific data sources to Zenodo and force upload
+        disdrodb_upload_archive --data_sources 'YOUR_DATA_SOURCE' --platform zenodo --force True
+
+        # Upload specific campaigns to Zenodo
+        disdrodb_upload_archive --campaign_names 'HYMEX_LTE_SOP2 IFLOODS' --platform zenodo
+    """  # noqa: D301
     from disdrodb.data_transfer.upload_data import upload_archive
 
     data_archive_dir = parse_archive_dir(data_archive_dir)