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

disdrodb/cli/disdrodb_run_l0b.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
@@ -16,8 +16,8 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
 """Script to run the DISDRODB L0B processing."""
+
 import sys
-from typing import Optional
 
 import click
 
@@ -42,9 +42,9 @@ sys.tracebacklimit = 0  # avoid full traceback error if occur
 @click_metadata_archive_dir_option
 def disdrodb_run_l0b(
     # Stations options
-    data_sources: Optional[str] = None,
-    campaign_names: Optional[str] = None,
-    station_names: Optional[str] = None,
+    data_sources: str | None = None,
+    campaign_names: str | None = None,
+    station_names: str | None = None,
     # Processing options
     force: bool = False,
     verbose: bool = True,
@@ -52,53 +52,53 @@ def disdrodb_run_l0b(
     debugging_mode: bool = False,
     remove_l0a: bool = False,
     # DISDRODB root directories
-    data_archive_dir: Optional[str] = None,
-    metadata_archive_dir: Optional[str] = None,
+    data_archive_dir: str | None = None,
+    metadata_archive_dir: str | None = None,
 ):
-    """
-    Run the L0B 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 True.
-    parallel : bool
-        If True, the files are processed simultaneously in multiple processes.
-        Each process will use a single thread to avoid issues with the HDF/netCDF library.
-        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_l0b
-        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 100 rows sampled from 3 L0A 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 L0B processing chain for many/all DISDRODB stations.
+
+    It produces a DISDRODB L0B file for each DISDRODB L0A Apache Parquet file of the specified stations.
+
+    \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_l0b
+
+        # Process a specific data source and force overwrite existing files
+        disdrodb_run_l0b --data_sources EPFL --force True --verbose True
+
+        # Process specific data sources
+        disdrodb_run_l0b --data_sources 'USA EPFL'
+
+        # Process specific campaigns in debugging mode
+        disdrodb_run_l0b --campaign_names 'DELFT IMPACTS' --debugging_mode True
+
+        # Process specific stations with custom number of workers
+        DASK_NUM_WORKERS=8 disdrodb_run_l0b --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_l0b
 
     # Parse data_sources, campaign_names and station arguments

disdrodb/cli/disdrodb_run_l0b_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
@@ -15,8 +15,8 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
 """Script to run the DISDRODB L0B station processing."""
+
 import sys
-from typing import Optional
 
 import click
 
@@ -53,44 +53,45 @@ def disdrodb_run_l0b_station(
     debugging_mode: bool = False,
     remove_l0a: bool = False,
     # DISDRODB root directories
-    data_archive_dir: Optional[str] = None,
-    metadata_archive_dir: Optional[str] = None,
+    data_archive_dir: str | None = None,
+    metadata_archive_dir: str | None = None,
 ):
-    """Run the L0B 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 to avoid issues with the HDF/netCDF library.
-        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_l0b_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 100 rows sampled from 3 L0A 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 L0B processing  chain for a specific DISDRODB station.
+
+    It produces a DISDRODB L0B netCDF file for each DISDRODB L0A Apache Parquet file
+    of the specified station.
+
+    \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_l0b_station EPFL HYMEX_LTE_SOP2 10
+
+        # Force overwrite existing files with verbose output
+        disdrodb_run_l0b_station EPFL HYMEX_LTE_SOP2 10 --force True --verbose True
+
+        # Process station with debugging mode and custom workers
+        DASK_NUM_WORKERS=4 disdrodb_run_l0b_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.l0 import run_l0b_station
     from disdrodb.utils.dask import close_dask_cluster, initialize_dask_cluster
 

disdrodb/cli/disdrodb_run_l0c.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
@@ -16,8 +16,8 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
 """Script to run the DISDRODB L0C processing."""
+
 import sys
-from typing import Optional
 
 import click
 
@@ -42,9 +42,9 @@ sys.tracebacklimit = 0  # avoid full traceback error if occur
 @click_metadata_archive_dir_option
 def disdrodb_run_l0c(
     # Stations options
-    data_sources: Optional[str] = None,
-    campaign_names: Optional[str] = None,
-    station_names: Optional[str] = None,
+    data_sources: str | None = None,
+    campaign_names: str | None = None,
+    station_names: str | None = None,
     # L0C processing options
     remove_l0b: bool = False,
     # Processing options
@@ -53,55 +53,58 @@ def disdrodb_run_l0c(
     parallel: bool = True,
     debugging_mode: bool = False,
     # DISDRODB root directories
-    data_archive_dir: Optional[str] = None,
-    metadata_archive_dir: Optional[str] = None,
+    data_archive_dir: str | None = None,
+    metadata_archive_dir: str | None = None,
 ):
-    """
-    Run the L0C 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 True.
-    parallel : bool
-        If True, the files are processed simultaneously in multiple processes.
-        Each process will use a single thread to avoid issues with the HDF/netCDF library.
-        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_l0b
-        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 100 rows sampled from 3 L0A files for each station.
-        The default is False.
-    remove_l0b: bool, optional
-        Whether to remove the processed L0B files. The default value 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 L0C processing chain for many/all DISDRODB stations.
+
+    It produces DISDRODB L0C files from existing DISDRODB L0B data of the specified stations.
+    DISDRODB L0B files must be available before launching the DISDRODB L0C processing.
+
+    The DISDRODB L0C processing chain performs time-based quality control by
+    removing duplicate timesteps and correcting trailing-second offsets.
+    Then, it consolidate L0B data into by default daily netCDF files.
+
+    \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_l0c
+
+        # Process a specific data source and force overwrite existing files
+        disdrodb_run_l0c --data_sources EPFL --force True --verbose True
+
+        # Process specific data sources
+        disdrodb_run_l0c --data_sources 'USA EPFL'
+
+        # Process specific campaigns in debugging mode
+        disdrodb_run_l0c --campaign_names 'DELFT IMPACTS' --debugging_mode True
+
+        # Process specific stations with custom number of workers
+        DASK_NUM_WORKERS=8 disdrodb_run_l0c --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_l0c
 
     # Parse data_sources, campaign_names and station arguments

disdrodb/cli/disdrodb_run_l0c_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
@@ -15,8 +15,8 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
 """Script to run the DISDRODB L0C station processing."""
+
 import sys
-from typing import Optional
 
 import click
 
@@ -54,46 +54,49 @@ def disdrodb_run_l0c_station(
     parallel: bool = True,
     debugging_mode: bool = False,
     # DISDRODB root directories
-    data_archive_dir: Optional[str] = None,
-    metadata_archive_dir: Optional[str] = None,
+    data_archive_dir: str | None = None,
+    metadata_archive_dir: str | None = None,
 ):
-    """Run the L0C 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 to avoid issues with the HDF/netCDF library.
-        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_l0b_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 100 rows sampled from 3 L0A files.
-        The default is False.
-    remove_l0b: bool, optional
-        Whether to remove the processed L0B files. The default value 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 L0C processing chain for a specific DISDRODB station.
+
+    It produces DISDRODB L0C files from existing DISDRODB L0B data of the specified station.
+    DISDRODB L0B files must be available before launching the DISDRODB L0C processing.
+
+    The DISDRODB L0C processing chain performs time-based quality control by
+    removing duplicate timesteps and correcting trailing-second offsets.
+    Then, it consolidate L0B data into by default daily netCDF files.
+
+    \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_l0c_station EPFL HYMEX_LTE_SOP2 10
+
+        # Force overwrite existing files with verbose output
+        disdrodb_run_l0c_station EPFL HYMEX_LTE_SOP2 10 --force True --verbose True
+
+        # Process station with debugging mode and custom workers
+        DASK_NUM_WORKERS=4 disdrodb_run_l0c_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.l0 import run_l0c_station
     from disdrodb.utils.dask import close_dask_cluster, initialize_dask_cluster
 

disdrodb/cli/disdrodb_run_l1.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
@@ -16,8 +16,8 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
 """Script to run the DISDRODB L1B processing."""
+
 import sys
-from typing import Optional
 
 import click
 
@@ -40,62 +40,66 @@ sys.tracebacklimit = 0  # avoid full traceback error if occur
 @click_metadata_archive_dir_option
 def disdrodb_run_l1(
     # Stations options
-    data_sources: Optional[str] = None,
-    campaign_names: Optional[str] = None,
-    station_names: Optional[str] = None,
+    data_sources: str | None = None,
+    campaign_names: str | None = None,
+    station_names: str | None = None,
     # 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,
+    data_archive_dir: str | None = None,
+    metadata_archive_dir: str | None = None,
 ):
-    """
-    Run the L1 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 L1 processing chain for many/all DISDRODB stations.
+
+    It produces DISDRODB L1 files from existing DISDRODB L0C data of the specified stations.
+    DISDRODB L0C files must be available before launching the DISDRODB L1 processing.
+
+    The DISDRODB L1 processing chain temporally aggregates L0C data at the specified temporal intervals,
+    applies quality control (QC) algorithms, and detetermines precipitation phase and hydrometeor types.
+
+    \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_l1
+
+        # Process a specific data source and force overwrite existing files
+        disdrodb_run_l1 --data_sources EPFL --force True --verbose True
+
+        # Process specific data sources
+        disdrodb_run_l1 --data_sources 'USA EPFL'
+
+        # Process specific campaigns in debugging mode
+        disdrodb_run_l1 --campaign_names 'DELFT IMPACTS' --debugging_mode True
+
+        # Process specific stations with custom number of workers
+        DASK_NUM_WORKERS=8 disdrodb_run_l1 --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_l1
 
     # Parse data_sources, campaign_names and station arguments