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

disdrodb/cli/disdrodb_check_products_options.py

@@ -0,0 +1,45 @@
+# -----------------------------------------------------------------------------.
+# 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 check the validity of the DISDRODB products configuration files."""
+
+import sys
+
+import click
+
+from disdrodb.utils.cli import parse_empty_string_and_none
+
+sys.tracebacklimit = 0  # avoid full traceback error if occur
+
+# -------------------------------------------------------------------------.
+# Click Command Line Interface decorator
+
+
+@click.command()
+@click.option(
+    "--products_configs_dir",
+    type=str,
+    show_default=True,
+    default=None,
+    help="Directory with DISDRODB products configurations files",
+)
+def disdrodb_check_products_options(products_configs_dir):
+    """Validate the DISDRODB products configuration files."""
+    from disdrodb.routines.options_validation import validate_products_configurations
+
+    products_configs_dir = parse_empty_string_and_none(products_configs_dir)
+
+    validate_products_configurations(products_configs_dir)

disdrodb/cli/disdrodb_create_summary.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 create summary figures and tables for a DISDRODB stationn."""
+
 import sys
-from typing import Optional
 
 import click
 
@@ -49,37 +49,63 @@ sys.tracebacklimit = 0  # avoid full traceback error if occur
 )
 def disdrodb_create_summary(
     # 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:
     parallel=False,
     temporal_resolution="1MIN",
     # 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,
 ):
-    r"""Create summary figures and tables for a specific set of DISDRODB stations.
-
-    Parameters \n
-    ---------- \n
-    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) for which to create stations summaries.
-        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'
-    data_archive_dir : str \n
-        DISDRODB Data Archive directory \n
-        Format: <...>/DISDRODB \n
-        If not specified, uses path specified in the DISDRODB active configuration. \n
-    """
+    """Create summary figures and tables for DISDRODB stations.
+
+    Generates summary visualizations and statistics from DISDRODB L2E data products.
+    The DISDRODB L2E files must be available.
+
+    \b
+    Station Selection:
+        If no station filters are specified, creates summaries for 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
+    Processing Options:
+        --parallel: Reads files in parallel for faster processing (default: False)
+        --temporal_resolution: Temporal resolution of L2E product to use (default: 1MIN)
+        Valid temporal resolutions depend on available L2E products.
+
+    \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:
+        # Create summaries for all stations
+        disdrodb_create_summary
+
+        # Create summaries for specific data sources
+        disdrodb_create_summary --data_sources 'EPFL NASA'
+
+        # Create summaries for specific campaigns
+        disdrodb_create_summary --campaign_names 'HYMEX_LTE_SOP2 IFLOODS'
+
+        # Create summaries for specific stations with custom temporal resolution
+        disdrodb_create_summary --station_names 'apu01 apu02' --temporal_resolution 5MIN
+
+        # Create summaries with custom archive directory
+        disdrodb_create_summary --data_sources EPFL --data_archive_dir /path/to/DISDRODB
+
+    \b
+    Important Notes:
+        - Data source names must be in UPPER CASE
+        - Campaign names must be in UPPER CASE
+        - To specify multiple values, use space-separated strings in quotes
+        - Requires L2E data products to be available for the selected stations
+    """  # noqa: D301
     from disdrodb.routines import create_summary
     from disdrodb.utils.dask import close_dask_cluster, initialize_dask_cluster
 

disdrodb/cli/disdrodb_create_summary_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 create summary figures and tables for a DISDRODB station."""
+
 import sys
-from typing import Optional
 
 import click
 
@@ -53,25 +53,46 @@ def disdrodb_create_summary_station(
     parallel=False,
     temporal_resolution="1MIN",
     # DISDRODB root directories
-    data_archive_dir: Optional[str] = None,
+    data_archive_dir: str | None = None,
 ):
-    r"""Create summary figures and tables for a specific DISDRODB station.
-
-    Parameters \n
-    ---------- \n
-    data_source : str \n
-        Institution name (when campaign data spans more than 1 country),
-        or country (when all campaigns (or sensor networks) are inside a given country).\n
-        Must be UPPER CASE.\n
-    campaign_name : str \n
-        Campaign name. Must be UPPER CASE.\n
-    station_name : str \n
-        Station name \n
-    data_archive_dir : str \n
-        DISDRODB Data Archive directory \n
-        Format: <...>/DISDRODB \n
-        If not specified, uses path specified in the DISDRODB active configuration. \n
-    """
+    """Create summary figures and tables for a specific DISDRODB station.
+
+    Generates summary visualizations and statistics using the DISDRODB L2E product
+    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
+    Processing Options:
+        --parallel: Reads files in parallel for faster processing (default: False)
+        --temporal_resolution: Temporal resolution of L2E product to use (default: 1MIN)
+        Valid temporal resolutions depend on available L2E products
+
+    \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:
+        # Create summary for a specific station
+        disdrodb_create_summary_station EPFL HYMEX_LTE_SOP2 10
+
+        # Create summary with custom temporal resolution
+        disdrodb_create_summary_station EPFL HYMEX_LTE_SOP2 10 --temporal_resolution 5MIN
+
+        # Create summary with custom archive directory
+        disdrodb_create_summary_station NASA IFLOODS apu01 --data_archive_dir /path/to/DISDRODB
+
+    \b
+    Important Notes:
+        - Data source, campaign, and station names must be in UPPER CASE
+        - All three station identifiers are required (no wildcards)
+        - Requires L2E data products to be available for the specified station
+    """  # noqa: D301
     from disdrodb.summary.routines import create_station_summary
     from disdrodb.utils.dask import close_dask_cluster, initialize_dask_cluster
 

disdrodb/cli/disdrodb_data_archive_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 print the DISDRODB Data Archive directory."""
+
 import sys
 
 import click

disdrodb/cli/disdrodb_download_archive.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
@@ -17,7 +17,6 @@
 """Wrapper to download stations from the DISDRODB Decentralized Data Archive."""
 
 import sys
-from typing import Optional
 
 import click
 
@@ -38,36 +37,57 @@ sys.tracebacklimit = 0  # avoid full traceback error if occur
 @click_metadata_archive_dir_option
 @click_download_options
 def disdrodb_download_archive(
-    data_sources: Optional[str] = None,
-    campaign_names: Optional[str] = None,
-    station_names: Optional[str] = None,
-    data_archive_dir: Optional[str] = None,
-    metadata_archive_dir: Optional[str] = None,
+    data_sources: str | None = None,
+    campaign_names: str | None = None,
+    station_names: str | None = None,
+    data_archive_dir: str | None = None,
+    metadata_archive_dir: str | None = None,
     force: bool = False,
 ):
-    """Download DISDRODB stations with the ``disdrodb_data_url`` in the metadata.
-
-    Parameters
-    ----------
-    data_sources : str or list of str, optional
-        Data source name (eg : EPFL).
-        If not provided (``None``), all data sources will be downloaded.
-        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 downloaded.
-        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 downloaded.
-        The default value is ``station_name=None``.
-    force : bool, optional
-        If ``True``, overwrite the already existing raw data file.
-        The default value is ``False``.
-    data_archive_dir : str (optional)
-        DISDRODB Data Archive directory. Format: ``<...>/DISDRODB``.
-        If ``None`` (the default), the disdrodb config variable ``data_archive_dir`` is used.
-    """
+    """Download raw data for multiple DISDRODB stations from the DISDRODB Decentralized Data Archive.
+
+    It downloads station raw data files and stores them in the local DISDRODB Data Archive.
+    The data are organized by data_source, campaign_name, and station_name.
+
+    \b
+    Station Selection:
+        If no station filters are specified, downloads ALL stations.
+        Use data_sources, campaign_names, and station_names to filter stations.
+        Filters work together to narrow down the selection (AND logic).
+        Only stations with a ``disdrodb_data_url`` in their metadata will be downloaded.
+
+    \b
+    Download Behavior:
+        For webserver/FTP-hosted data:
+            - Incremental downloads: Fetch only new files when they become available
+            - Existing files on disk are skipped unless '--force True' is used
+
+        For repository-hosted data (e.g., Zenodo):
+            - Use '--force True' to download new versions when available
+            - Without '--force True', download is skipped if data already exists locally
+
+    \b
+    Download Options:
+        --force: Removes existing raw data files and forces complete re-download (default: False)
+        Warning: All existing station data will be deleted before re-downloading
+
+    \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:
+        # Download all stations with available download URLs
+        disdrodb_download_archive
+
+        # Download all stations from specific data sources
+        disdrodb_download_archive --data_sources 'EPFL NASA'
+
+        # Download specific campaigns and force re-download
+        disdrodb_download_archive --campaign_names 'HYMEX_LTE_SOP2 IFLOODS' --force True
+    """  # noqa: D301
     from disdrodb.data_transfer.download_data import download_archive
 
     data_archive_dir = parse_archive_dir(data_archive_dir)

disdrodb/cli/disdrodb_download_metadata_archive.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,7 +15,9 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------.
 """Routine to download the DISDRODB Metadata Data Archive."""
+
 import sys
+from pathlib import Path
 
 import click
 
@@ -25,7 +27,7 @@ sys.tracebacklimit = 0  # avoid full traceback error if occur
 
 
 @click.command()
-@click.argument("directory_path", metavar="<station>")
+@click.argument("directory_path", required=False, metavar="[directory]", type=click.Path())
 @click.option("-f", "--force", type=bool, show_default=True, default=False, help="Force overwriting")
 def disdrodb_download_metadata_archive(
     directory_path,
@@ -33,21 +35,31 @@ def disdrodb_download_metadata_archive(
 ):
     """Download the DISDRODB Metadata Archive to the specified directory.
 
-    Parameters
-    ----------
-    directory_path : str
-        The directory path where the DISDRODB-METADATA directory will be downloaded.
-    force : bool, optional
-         If ``True``, the existing DISDRODB-METADATA directory will be removed
-         and a new one will be downloaded. The default value is ``False``.
-
-    Returns
-    -------
-    metadata_archive_dir
-        The DISDRODB Metadata Archive directory path.
-    """
+    \b
+    Download Options:
+        '--force True' removes the existing DISDRODB-METADATA directory and forces re-download.
+        The default is --force False. If the DISDRODB-METADATA directory already exists, it raises an error.
+
+    \b
+    Examples:
+        # Download metadata archive to current directory
+        disdrodb_download_metadata_archive
+
+        # Download to specific directory
+        disdrodb_download_metadata_archive /path/to/directory
+
+        # Force re-download of existing metadata archive
+        disdrodb_download_metadata_archive /path/to/directory --force True
+
+    \b
+    Important Notes:
+        - Use --force with caution as it will delete the existing metadata archive
+    """  # noqa: D301
     from disdrodb import download_metadata_archive
 
-    directory_path = parse_archive_dir(directory_path)
+    # Default to current directory if none provided
+    directory_path = Path(directory_path or ".").resolve()
+    directory_path = parse_archive_dir(str(directory_path))
 
+    # Download metadata archive
     download_metadata_archive(directory_path, force=force)

disdrodb/cli/disdrodb_download_station.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 download station data from the DISDRODB Decentralized Data Archive."""
 
 import sys
-from typing import Optional
 
 import click
 
@@ -43,33 +40,65 @@ def disdrodb_download_station(
     data_source: str,
     campaign_name: str,
     station_name: str,
-    data_archive_dir: Optional[str] = None,
-    metadata_archive_dir: Optional[str] = None,
+    data_archive_dir: str | None = None,
+    metadata_archive_dir: str | None = None,
     force: bool = False,
 ):
-    """
-    Download data of a single DISDRODB station from the DISDRODB remote repository.
-
-    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.
-    force: bool, optional
-        If ``True``, overwrite the already existing raw data file.
-        The default value is ``False``.
-    data_archive_dir : str (optional)
-        DISDRODB Data Archive directory. Format: ``<...>/DISDRODB``.
-        If ``None`` (the default), the disdrodb config variable ``data_archive_dir`` is used.
-    """
+    """Download raw data of a single station from the DISDRODB Decentralized Data Archive.
+
+    It downloads station raw data files and stores them in the local DISDRODB Data Archive.
+    The data are organized by data_source, campaign_name, and station_name.
+
+    For stations data hosted on FTP/webservers, recursive calls of
+    this command allows to fetch and download just the new data when becomes available.
+
+    For stations data hosted on data repository such as Zenodo in ZIP archives,
+    if a new version becomes available, you must set force=True to download the new version.
+
+    \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
+    Download Behavior:
+        For webserver/FTP-hosted data:
+            - Incremental downloads: Fetch only new files when they become available
+            - Existing files on disk are skipped unless --force is used
+
+        For repository-hosted data (e.g., Zenodo):
+            - Use --force to download new versions when available
+            - Without --force, download is skipped if data already exists locally
+
+    \b
+    Download Options:
+        --force: Removes existing raw data files and forces complete re-download (default: False)
+        WARNING: All existing station data will be deleted before re-downloading.
+
+    \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:
+        # Download data for a single station
+        disdrodb_download_station EPFL HYMEX_LTE_SOP2 10
+
+        # Force re-download of existing data
+        disdrodb_download_station EPFL HYMEX_LTE_SOP2 10 --force True
+
+        # Download with custom archive directory
+        disdrodb_download_station NASA IFLOODS apu01 --data_archive_dir /path/to/DISDRODB
+
+    \b
+    Important Notes:
+        - Data source, campaign, and station names must be UPPER CASE
+        - All three station identifiers are required (no wildcards)
+        - Downloaded files are placed in <data_archive_dir>/Raw/<data_source>/<campaign_name>/<station_name>/
+        - Use --force with caution as it will remove data on disk before starting to re-download them.
+    """  # noqa: D301
     from disdrodb.data_transfer.download_data import download_station
 
     data_archive_dir = parse_archive_dir(data_archive_dir)

disdrodb/cli/disdrodb_initialize_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 initialize the DISDRODB station directory structure."""
+
 import sys
-from typing import Optional
 
 import click
 
@@ -43,28 +43,48 @@ def disdrodb_initialize_station(
     campaign_name: str,
     station_name: str,
     # 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,
 ):
-    r"""Initialize the DISDRODB directory structure for a station.
-
-    It adds the relevant directories and the default issue and metadata YAML files..
-
-    Parameters \n
-    ---------- \n
-    data_source : str \n
-        Institution name (when campaign data spans more than 1 country), or country (when all campaigns (or sensor
-        networks) are inside a given country).\n
-        Must be UPPER CASE.\n
-    campaign_name : str \n
-        Campaign name. Must be UPPER CASE.\n
-    station_name : str \n
-        Station name \n
-    data_archive_dir : str \n
-        DISDRODB Data Archive directory \n
-        Format: <...>/DISDRODB \n
-        If not specified, uses path specified in the DISDRODB active configuration. \n
-    """
+    """Initialize the DISDRODB directory structure for a new station.
+
+    Creates the required directory structure and default YAML configuration files
+    for a new station in both the DISDRODB Data and Metadata archives.
+
+    \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
+    Created Structure:
+        Data Archive:
+            - Data directory for the station where to place the raw data files
+
+        Metadata Archive:
+            - Station metadata YAML file (template)
+            - Station issue YAML file (template)
+
+    \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:
+        # Initialize a new station with default configuration
+        disdrodb_initialize_station DATA_SOURCE CAMPAIGN_NAME STATION_NAME
+
+        # Initialize with custom archive directories
+        disdrodb_initialize_station DATA_SOURCE CAMPAIGN_NAME STATION_NAME --data_archive_dir /path/to/DISDRODB
+
+    \b
+    Important Notes:
+        - Data source, campaign, and station names must be in UPPER CASE
+        - All three station identifiers are required (no wildcards)
+        - Creates template YAML files that need to be manually filled in
+    """  # noqa: D301
     from disdrodb.api.create_directories import create_initial_station_structure
 
     data_archive_dir = parse_archive_dir(data_archive_dir)

disdrodb/cli/disdrodb_metadata_archive_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 print the DISDRODB Data Archive directory."""
+
 import sys
 
 import click