### CLI Help Output Example

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/README.md

This is an example of the output you can expect when running the copernicusmarine --help command. It outlines the usage, options, and available commands.

```bash
Usage: copernicusmarine [OPTIONS] COMMAND [ARGS]...

Options:
  -V, --version  Show the version and exit.
  -h, --help     Show this message and exit.

Commands:
  describe  Print Copernicus Marine catalogue as JSON.
  get       Download originally produced data files.
  login     Create a configuration file with your Copernicus Marine credentials.
  subset    Download subsets of datasets as NetCDF files or Zarr stores.
```

--------------------------------

### Install with Pip

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/README.md

Install the copernicusmarine package using Python's pip package installer.

```bash
python -m pip install copernicusmarine
```

--------------------------------

### Example file_list.txt with correct paths

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/get-usage.md

This example demonstrates correct path formats for the file_list.txt when using the --file-list option. It includes absolute paths, partial paths relative to the user's definition, and relative paths.

```text
# correct paths
> s3://mdl-native-01/native/INSITU_GLO_PHYBGCWAV_DISCRETE_MYNRT_013_030/cmems_obs-ins_glo_phybgcwav_mynrt_na_irr_202311/history/BO/AR_PR_BO_58JM.nc
> INSITU_GLO_PHYBGCWAV_DISCRETE_MYNRT_013_030/cmems_obs-ins_glo_phybgcwav_mynrt_na_irr_202311/history/BO/AR_PR_BO_58JM.nc
> cmems_obs-ins_glo_phybgcwav_mynrt_na_irr_202311/history/BO/AR_PR_BO_58JM.nc
> history/BO/AR_PR_BO_58JM.nc
> index_history.txt
# incorrect paths
# version is missing
> INSITU_GLO_PHYBGCWAV_DISCRETE_MYNRT_013_030/cmems_obs-ins_glo_phybgcwav_mynrt_na_irr/history/BO/AR_PR_BO_58JM.nc
# only the file name and not the path to the file
> AR_PR_BO_58JM.nc
# not the same dataset
> another_dataset/history/BO/AR_PR_BO_58JM.nc
```

--------------------------------

### Example file_list.txt with absolute paths

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/get-usage.md

This example shows how to specify absolute S3 paths in the file_list.txt for direct download. Paths can include wildcards or regular expressions.

```text
s3://mdl-native-10/native/IBI_MULTIYEAR_PHY_005_002/cmems_mod_ibi_phy-temp_my_0.027deg_P1M-m_202511/2021/CMEMS_v6r1_IBI_PHY_MY_NL_01mav_temp_20210101_20210131_R20251125_RE01.nc
s3://mdl-native-10/native/IBI_MULTIYEAR_PHY_005_002/cmems_mod_ibi_phy-temp_my_0.027deg_P1M-m_202511/2021/CMEMS_v6r1_IBI_PHY_MY_NL_01mav_temp_20210201_20210228_R20251125_RE01.nc
s3://mdl-native-10/native/IBI_MULTIYEAR_PHY_005_002/cmems_mod_ibi_phy-temp_my_0.027deg_P1M-m_202511/2021/CMEMS_v6r1_IBI_PHY_MY_NL_01mav_temp_20210301_20210331_R20251125_RE01.nc
```

--------------------------------

### Save CLI Get Response to JSON

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/response-types.md

Example of how to capture the JSON output from the command line interface 'get' command into a local file.

```bash
copernicusmarine get -i cmems_mod_glo_phy_anfc_0.083deg_P1M-m --filter "*202501*" > get_response.json
```

--------------------------------

### Concurrent Data Downloading

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/command-line-interface.md

Example of using the '--concurrent-processes' option to specify the number of concurrent processes for downloading data.

```bash
copernicusmarine subset [SUBSET-OPTIONS] split-on --concurrent-processes 4
```

--------------------------------

### Create Get Request Template

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/shared-options.md

Use this option to generate a JSON template for getting data. No other action is performed.

```bash
copernicusmarine get --create-template
```

--------------------------------

### Verify Copernicus Marine Toolbox Installation

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/quickoverview.ipynb

Import the copernicusmarine package in Python to check if the installation was successful. This is a basic verification step.

```python
import copernicusmarine
copernicusmarine.__version__
```

--------------------------------

### Get Command Usage

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/command-line-interface.md

Basic usage of the 'get' command, specifying the dataset ID and a filter pattern for files.

```bash
copernicusmarine get -i cmems_mod_glo_phy_anfc_0.083deg_P1M-m --filter "*202501*"
```

--------------------------------

### JSON output example with filtered fields

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/migration-guide/v2.md

Example JSON output after applying `--return-fields` to the `describe` command, showing only the specified fields and their parents.

```json
{
  "product_id": "ANTARCTIC_OMI_SI_extent",
  "datasets": [
    {
      "dataset_id": "antarctic_omi_si_extent",
      "versions": [
        {
          "parts": [
            {
              "services": [
                {
                  "service_name": "original-files",
                  "uri": "https://s3.waw3-1.cloudferro.com/mdl-native-10/native/ANTARCTIC_OMI_SI_extent/antarctic_omi_si_extent_202207/antarctic_omi_si_extent_19930115_P20220328.nc"
                },
                {
                  "service_name": "omi-arco",
                  "uri": "https://s3.waw3-1.cloudferro.com/mdl-arco-time-001/arco/ANTARCTIC_OMI_SI_extent/antarctic_omi_si_extent_202207/omi.zarr"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Fetch Specific Dataset Version (Python API)

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/shared-options.md

This Python example demonstrates fetching a specific dataset version using the `dataset_version` argument, which is the recommended approach.

```python
import copernicusmarine

copernicusmarine.get(
    dataset_id="cmems_mod_ibi_phy-temp_my_0.027deg_P1D-m",
    dataset_version="202511",
    dry_run=True,
)
```

--------------------------------

### Install netCDF4 with Pip

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/installation.md

Use this command to install the netCDF4 library if you need to save files in NetCDF3 format and are using h5netcdf as the backend.

```bash
python -m pip install netCDF4
```

--------------------------------

### Install with Conda

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/README.md

Use Conda to install the copernicusmarine package from the conda-forge channel.

```bash
conda install -c conda-forge copernicusmarine
```

--------------------------------

### Install CLI (Mac/OS)

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/CONTRIBUTION.md

Install the Copernicus Marine Toolbox CLI in editable mode on macOS or other OS. This is typically done after activating the test environment.

```bash
pip install --editable .
```

--------------------------------

### Split Output Files by Variable

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/command-line-interface.md

Example of using the 'split-on' command with the '--on-variables' option to split output files based on variable names.

```bash
copernicusmarine subset [SUBSET-OPTIONS] split-on --on-variables
```

--------------------------------

### Install netCDF4 with Conda/Mamba

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/installation.md

Use this command to install the netCDF4 library if you need to save files in NetCDF3 format and are using h5netcdf as the backend.

```bash
conda install -c conda-forge netCDF4
```

--------------------------------

### Subset with Original-Grid Projection and Unit Verification

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/stereo_subset.ipynb

This example demonstrates subsetting with an original-grid projection and includes a `--dry-run` to check coordinate extents. Always verify unit variations (meters vs. 100km) for original-grid datasets.

```bash
copernicusmarine subset -i cmems_mod_arc_phy_my_hflux_P1M-m -y 25000 -Y 850000 -x -10000 -X 1800000 --dry-run --dataset-part originalGrid
```

--------------------------------

### Subset Data with Short Form Arguments

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/command-line-interface.md

Equivalent command to the long-form example, demonstrating the use of short-form arguments for the 'copernicusmarine subset' command.

```bash
copernicusmarine subset -i cmems_mod_glo_phy_anfc_0.083deg_P1M-m -v siconc -v siage -t 2023-01-01 -T 2024-01-03 -x 0.0 -X 0.1 -y 28.0 -Y 28.1 -z 1 -Z 2
```

--------------------------------

### Split Output Files by Time Interval

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/command-line-interface.md

Example of using the 'split-on' command with the '--on-time' option to split output files based on specified time intervals (e.g., 'month').

```bash
copernicusmarine subset [SUBSET-OPTIONS] split-on --on-time month
```

--------------------------------

### Subset Command Output

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/subset-usage.md

This is an example of the output returned after executing the `subset` command. It includes informational messages about the dataset selection and download size, followed by a JSON object detailing the file size, data transfer size, status, and a success message.

```bash
INFO - 2026-03-31T15:25:20Z - Selected dataset version: "202406"
INFO - 2026-03-31T15:25:20Z - Selected dataset part: "default"
INFO - 2026-03-31T15:25:24Z - Total size of the download: 13.53 KB.
{
  "file_size": "0.01 MB",
  "data_transfer_size": "0.49 MB",
  "status": "000",
  "message": "The request was successful."
}
```

--------------------------------

### Fetch Dataset Version in Dataset ID (Not Recommended)

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/shared-options.md

This Python example shows how to specify the dataset version directly within the dataset ID. This method is not recommended and may raise warnings or errors if used with other version specification methods.

```python
import copernicusmarine

copernicusmarine.get(
    dataset_id="cmems_mod_ibi_phy-temp_my_0.027deg_P1D-m_202511", dry_run=True
)
```

--------------------------------

### Split Dataset by Variable (CLI)

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/subset-split-on-usage.md

Splits a dataset into separate files, with each file containing data for a single variable. This command-line example demonstrates splitting by variables within a specified geographic bounding box and time range.

```bash
copernicusmarine subset --dataset-id cmems_mod_glo_phy_anfc_0.083deg_P1M-m -x -9 -X -7 -y 34 -Y 38 -Z 2 -t 2024-01-01 -T 2025-05-01 split-on --on-variables
```

--------------------------------

### Subset with Original-Grid Projection Shortcuts

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/stereo_subset.ipynb

When using `--dataset-part originalGrid`, the shortcuts -x/-X (x-axis) and -y/-Y (y-axis) are interpreted as length units. This example uses shortcuts for subsetting with original-grid projection.

```bash
copernicusmarine subset -i cmems_mod_arc_bgc_my_ecosmo_P1D-m -v chl -v zooc -v o2 -y -5 -Y 5 -x -10 -X 10 --dry-run --dataset-part originalGrid
```

--------------------------------

### Python get function output type change (v1 vs v2)

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/migration-guide/v2.md

Compares the output type of the `copernicusmarine.get` function between v1 (list of paths) and v2 (ResponseGet object). The v2 example demonstrates iterating through the ResponseGet object to print file details.

```python
# In v1
get_file_paths = copernicusmarine.get(
    dataset_id="cmems_mod_glo_phy-cur_anfc_0.083deg_P1M-m",
    filter="*glo12_rg_1m-m_202411-202411_3D-uovo_hcst.nc",
)
print(type(get_file_paths))  # <class 'list'>
# [pathlib.Path("GLOBAL_ANALYSISFORECAST_PHY_001_024/cmems_mod_glo_phy-cur_anfc_0.083deg_P1M-m_202406/2024/glo12_rg_1m-m_202411-202411_3D-uovo_hcst.nc")]

# In v2
response_get = copernicusmarine.get(
    dataset_id="cmems_mod_glo_phy-cur_anfc_0.083deg_P1M-m",
    filter="*glo12_rg_1m-m_202411-202411_3D-uovo_hcst.nc",
    dry_run=True,
)
print(type(response_get))  # <class 'copernicusmarine.ResponseGet'>

for field, value in response_get.model_dump(
    exclude_none=True, exclude_unset=True
).items():
    if field == "files":
        for file_get in value:
            for file_field, file_value in file_get.items():
                print(f"{file_field}: {file_value}")
    else:
        print(f"{field}: {value}")

# s3_url: s3://mdl-native-14/native/GLOBAL_ANALYSISFORECAST_PHY_001_024/cmems_mod_glo_phy-cur_anfc_0.083deg_P1M-m_202406/2024/glo12_rg_1m-m_202411-202411_3D-uovo_hcst.nc
# https_url: https://s3.waw3-1.cloudferro.com/mdl-native-14/native/GLOBAL_ANALYSISFORECAST_PHY_001_024/cmems_mod_glo_phy-cur_anfc_0.083deg_P1M-m_202406/2024/glo12_rg_1m-m_202411-202411_3D-uovo_hcst.nc
# file_size: 1857.429880142212
# last_modified_datetime: 2024-12-10T10:04:18.141000+00:00
# etag: "430b098c4bd6ed9da8fa011b2c57a10a-233"
# file_format: .nc
# output_directory: .
# filename: glo12_rg_1m-m_202411-202411_3D-uovo_hcst.nc
# file_path: GLOBAL_ANALYSISFORECAST_PHY_001_024/cmems_mod_glo_phy-cur_anfc_0.083deg_P1M-m_202406/2024/glo12_rg_1m-m_202411-202411_3D-uovo_hcst.nc
# file_status: DOWNLOADED
# number_of_files_to_download: 1
# total_size: 1857.429880142212
# status: 001
```

--------------------------------

### Describe All Products and Datasets

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/describe-usage.md

Retrieves metadata for all products and datasets, displaying it as JSON output. Use redirection to save the output to a file.

```bash
copernicusmarine describe
```

```bash
copernicusmarine describe > all_products_copernicus_marine_service.json
```

--------------------------------

### Install with Mamba

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/README.md

Use Mamba to install the copernicusmarine package from the conda-forge channel. The --yes flag automatically confirms the installation.

```bash
mamba install conda-forge::copernicusmarine --yes
```

--------------------------------

### Display CLI Help Information

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/README.md

Use the --help option to discover available commands and their options in the CLI. This is useful for understanding the toolbox's capabilities.

```bash
copernicusmarine --help
```

--------------------------------

### Build Sphinx Documentation

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/CONTRIBUTION.md

Navigate to the 'doc' directory and run this command to build the HTML documentation locally. This process uses Sphinx to generate documentation from source files.

```bash
cd doc/
make html
```

--------------------------------

### Execute Copernicus Marine Toolbox binary on Windows

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/installation.md

Run the downloaded Windows executable from the command prompt. Use --help for available commands or specify a command like 'subset'.

```bash
copernicusmarine.exe --help
```

```bash
copernicusmarine.exe subset --create-template
```

```bash
copernicusmarine.exe subset --request-file subset_template.json
```

--------------------------------

### Build and Publish Docker Image

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/CONTRIBUTION.md

Build and push the Docker image to Docker Hub. Requires the 'moi' command-line tool and credentials for Docker Hub. Replace <VERSION> with the desired image tag.

```bash
VERSION=<VERSION> DOCKER_HUB_USERNAME=`moi read-secret --name DOCKER_HUB_USERNAME` DOCKER_HUB_PUSH_TOKEN=`moi read-secret --name DOCKER_HUB_PUSH_TOKEN` make build-and-publish-dockerhub-image
```

--------------------------------

### Replicating v1 describe output in v2

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/migration-guide/v2.md

To achieve output similar to v1, exclude the 'datasets', 'description', and 'keywords' fields using the `--exclude-fields` option.

```bash
copernicusmarine describe --exclude-fields datasets,description,keywords
```

--------------------------------

### Execute Copernicus Marine Toolbox binary on macOS/Linux

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/installation.md

Run the downloaded binary directly from the terminal. Use --help for a list of available commands or specify a command like 'subset'.

```bash
./copernicusmarine_macos-x86_64.cli --help
```

```bash
./copernicusmarine_macos-x86_64.cli subset --create-template
```

```bash
./copernicusmarine_macos-x86_64.cli subset --request-file subset_template.json
```

--------------------------------

### Show all versions of a dataset

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/describe-usage.md

Use the `--show-all-versions` option to display all available versions of a dataset, including those planned for retirement or recently released.

--------------------------------

### Login using command-line arguments

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/command-line-interface.md

Log in by providing your username and password directly as command-line arguments. This method is straightforward for interactive use but may expose credentials in shell history.

```bash
copernicusmarine login --username <USERNAME> --password <PASSWORD>
```

--------------------------------

### Install netCDF4 for netCDF3 compatibility

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/migration-guide/v2.md

To ensure netCDF3 file compatibility in v2, you may need to install the `netCDF4` library. This is shown for both pip and conda environments.

```bash
# In v1
copernicusmarine subset --dataset-id cmems_mod_glo_phy-cur_anfc_0.083deg_P1M-m -t 2022 --netcdf3-compatible

# In v2
# maybe need to install netCDF4 to have netCDF3 files
pip install netCDF4
# or depending on the environment
conda -c conda-forge install netCDF4
# then it should work
copernicusmarine subset --dataset-id cmems_mod_glo_phy-cur_anfc_0.083deg_P1M-m -t 2022 --netcdf3-compatible
```

--------------------------------

### Describe Command: Filter by Content

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/command-line-interface.md

Use the 'describe' command to filter catalogue products by a specific string token.

```bash
copernicusmarine describe -c METOFFICE-GLO-SST-L4-NRT-OBS-SST-V2
```

--------------------------------

### Run Tests (Linux)

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/CONTRIBUTION.md

Execute the test suite on Linux after setting up the environment and credentials. This command runs all defined tests.

```bash
make run-tests
```

--------------------------------

### Copernicus Marine Toolbox - Get Function

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/quickoverview.ipynb

The `get` function allows downloading original data from Copernicus Marine Service datasets. It supports filtering, regex matching, specifying output directories, overwriting existing files, and synchronization.

```APIDOC
## Copernicus Marine Toolbox - Get Function

### Description
The `get` function in the `copernicusmarine` library is used to download original data from Copernicus Marine Service datasets. It offers various options for specifying datasets, filtering files, managing output, and synchronizing local data with remote sources.

### Method Signature
`copernicusmarine.get(dataset_id, filter=None, regex=None, output_directory=None, overwrite=False, sync=False, sync_delete=False, dataset_version=None, max_concurrent_requests=None, dry_run=False)`

### Parameters
- **dataset_id** (str) - Required - The identifier of the dataset to download.
- **filter** (str) - Optional - A filter pattern to select files.
- **regex** (str) - Optional - A regex pattern to select files.
- **output_directory** (str) - Optional - The directory where files will be saved.
- **overwrite** (bool) - Optional - If True, existing files will be overwritten. Defaults to False.
- **sync** (bool) - Optional - If True, synchronizes local files with the remote server. Defaults to False.
- **sync_delete** (bool) - Optional - If True and `sync` is True, deletes local files not present on the server. Defaults to False.
- **dataset_version** (str) - Optional - The specific version of the dataset to use.
- **max_concurrent_requests** (int) - Optional - Maximum number of concurrent download requests.
- **dry_run** (bool) - Optional - If True, simulates the download process without actually downloading files. Defaults to False.

### Examples

#### Example 1: Download all files from a dataset (dry run)
```python
# Download all the files from a dataset
response_with_all_the_files = copernicusmarine.get(dataset_id="cmems_mod_ibi_bgc_anfc_0.027deg-3D_P1D-m", dry_run=True)
```

#### Example 2: Download with filter, regex, and specify output directory
```python
# You can combine the filter and regex argument (it will be as an "OR" condition)
response = copernicusmarine.get(dataset_id="cmems_mod_ibi_bgc_anfc_0.027deg-3D_P1D-m", 
                     filter="*20241221_20241221_R20241212_FC10*", 
                     regex="20241220_20241220_R20241212_FC09", 
                     output_directory="data", # we can specify the output directory
                     overwrite=True, # if files already exist, they will be overwritten
                     )

for file_metadata in response.files:
    print(file_metadata.file_path)
```

#### Example 3: Synchronize local data with remote server
```python
response_sync = copernicusmarine.get(
    dataset_id="cmems_mod_ibi_bgc_anfc_0.027deg-3D_P1D-m", 
    filter="*20241221_20241221_R20241212_FC10*", 
    regex="20241220_20241220_R20241212_FC09",  
    dataset_version="202411", 
    output_directory="data",
    sync=True,
    sync_delete=True, # delete the files that are not in the server
    max_concurrent_requests=0, # not in parallel
    # can be useful to be sure to not overload the process 
)

for file_metadata in response_sync.files:
    print(f"Found {file_metadata.filename} on server and it was {file_metadata.file_status}")
```
```

--------------------------------

### Create Text File List

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/get-usage.md

Create a .txt file containing the S3 paths of selected dataset files instead of downloading them. This file list is compatible with the `--file-list` option.

```bash
copernicusmarine get --dataset-id cmems_mod_ibi_phy-temp_my_0.027deg_P1M-m --filter "*2021*" --create-file-list selected_files_for_2021.txt
```

--------------------------------

### Get Data Using Request File

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/shared-options.md

Specify request parameters in a JSON file for batch processing data retrieval requests.

```json
{
    "dataset_id": "cmems_mod_ibi_phy-temp_my_0.027deg_P1Y-m",
    "dataset_version": null,
    "dataset_part": null,
    "username": null,
    "password": null,
    "no_directories": false,
    "filter": "*01yav_temp_200[0-2]*",
    "regex": null,
    "output_directory": "copernicusmarine_data",
    "file_list": null,
    "sync": false,
    "sync_delete": false,
    "index_parts": false,
    "disable_progress_bar": false,
    "overwrite": false,
    "log_level": "INFO"
}
```

```bash
copernicusmarine get --request-file get_template.json
```

--------------------------------

### Describe Command: Filter by Content and Return Specific Fields

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/command-line-interface.md

Use the 'describe' command to filter catalogue products by a specific string token and return only the 'datasets' field.

```bash
copernicusmarine describe --contains METOFFICE-GLO-SST-L4-NRT-OBS-SST-V2 --return-fields datasets
```

--------------------------------

### Activate Test Environment (Mac/OS)

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/CONTRIBUTION.md

Activate the conda test environment created on macOS or other OS. This step is required before installing packages or running tests.

```bash
conda activate copernicusmarine-test
```

--------------------------------

### Prepare for patch release

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/CONTRIBUTION.md

Checkout the release branch and create a new local branch for developing the patch.

```sh
git checkout release/vX.Y
git checkout -b copernicusmarine-release
```

--------------------------------

### login

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/python-interface.md

Creates a configuration file with Copernicus Marine credentials. It supports environment variables, credential files, and user input for authentication.

```APIDOC
## copernicusmarine.login

### Description
Create a configuration file with your Copernicus Marine credentials under the `$HOME/.copernicusmarine` directory (overwritable with the `force_overwrite` option).

### Method
`copernicusmarine.login(
    username: str | None = None,
    password: str | None = None,
    configuration_file_directory: Path | str = PosixPath('/root/.copernicusmarine'),
    force_overwrite: bool = False,
    check_credentials_valid: bool = False,
    credentials_file: Path | None = None
) -> bool`

### Parameters
#### Arguments
- **username** (str | None) - Optional - User's username. If not set, searches environment variables, then credential files, or prompts for input.
- **password** (str | None) - Optional - User's password. If not set, searches environment variables, then credential files, or prompts for input.
- **configuration_file_directory** (Path | str) - Optional - Directory to store the configuration file. Defaults to `/root/.copernicusmarine`.
- **force_overwrite** (bool) - Optional - If True, overwrites existing configuration file.
- **check_credentials_valid** (bool) - Optional - If True, checks if the provided credentials are valid.
- **credentials_file** (Path | None) - Optional - Path to a custom credentials file.

### Returns
- **bool** - True if the login was successful, False otherwise.
```

--------------------------------

### Filter datasets by dataset_id and product_id

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/describe-usage.md

Use `--dataset_id` or `--product_id` options to significantly reduce the time to get specific information. You can use one or both options.

```bash
copernicusmarine describe -i cmems_mod_glo_phy_my_0.083deg_P1D-m -e services -r datasets,product_id
```

--------------------------------

### Download Files with Regex Filter

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/get-usage.md

Use the `--regex` option with a regular expression for advanced file selection. This example selects files containing '01yav_temp_20(00|01|02)'.

```bash
copernicusmarine get -i cmems_mod_ibi_phy-temp_my_0.027deg_P1Y-m --regex ".*01yav_temp_20(00|01|02).*\.nc"
```

--------------------------------

### Download Gridded Data as Zarr (File Format Argument)

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/subset-usage.md

Use the --file-format argument to specify Zarr as the output format for gridded data.

```bash
copernicusmarine subset --dataset-id cmems_mod_ibi_phy-temp_my_0.027deg_P1D-m -v thetao -t "20251028" -T "20251029" --file-format zarr
```

--------------------------------

### Download Arctic Data with Geographical Coordinates

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/stereo_subset.ipynb

Use this snippet to download Arctic region data using standard longitude and latitude boundaries. Ensure the `copernicusmarine` library is installed.

```python
import copernicusmarine 
dataset_lonlat = copernicusmarine.open_dataset(
    dataset_id="cmems_mod_arc_bgc_my_ecosmo_P1D-m", 
    variables=["chl", "zooc", "o2"],
    minimum_latitude=64.99684, 
    maximum_latitude=90, 
    minimum_longitude=-180, 
    maximum_longitude=180,
)
dataset_lonlat
```

--------------------------------

### ResponseGet Class

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/response-types.md

Metadata returned when using the `get()` function. This includes information about files, deleted files, files not found, download counts, total size, status, and messages.

```APIDOC
## Class: copernicusmarine.ResponseGet

### Description
Metadata returned when using [`get()`](python-interface.md#copernicusmarine.get).

### Fields
- **files** (*list*[[FileGet](#copernicusmarine.FileGet)]) - Description of the files concerned by the query.
- **files_deleted** (*list*[*str*] | *None*) - List of deleted files. Only if option `sync-delete` is passed.
- **files_not_found** (*list*[*str*] | *None*) - List of not found files from the file list input.
- **number_of_files_to_download** (*int*) - Number of files to be downloaded.
- **total_size** (*float* | *None*) - Total size of the files that would be downloaded in MB.
- **status** (*[StatusCode](#copernicusmarine.StatusCode)*) - Status of the request.
- **message** (*[StatusMessage](#copernicusmarine.StatusMessage)*) - Message explaining the status.

### Methods
- **serialize_total_size**(total_size: *float* | *None*) → *str* | *None*
```

--------------------------------

### Subset Data with Long Form Arguments

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/command-line-interface.md

Example of using the 'copernicusmarine subset' command with long-form arguments to specify dataset details, variables, time range, and spatial boundaries.

```bash
copernicusmarine subset --dataset-id cmems_mod_glo_phy_anfc_0.083deg_P1M-m --variable siconc --variable siage --start-datetime 2023-01-01 --end-datetime 2024-01-03 --minimum-longitude 0.0 --maximum-longitude 0.1 --minimum-latitude 28.0 --maximum-latitude 28.1 --minimum-depth 1 --maximum-depth 2
```

--------------------------------

### Subset with Geographic Coordinate Shortcuts

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/stereo_subset.ipynb

Without the `originalGrid` part specification, the shortcuts -x/-X and -y/-Y default to degree units for geographic coordinates. This example demonstrates subsetting using these shortcuts.

```bash
copernicusmarine subset -i cmems_mod_arc_bgc_my_ecosmo_P1D-m -v chl -v zooc -v o2 -y 65 -Y 85 -x -180 -X 180 --dry-run
```

--------------------------------

### Describe Command Usage

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/command-line-interface.md

Retrieve and parse metadata information from the Copernicus Marine catalogue.

```shell
describe [OPTIONS]
```

--------------------------------

### Search Products by Variables and Regions

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/quickoverview.ipynb

Use `copernicusmarine.describe` to find products containing specific variables and regions. This helps in identifying relevant datasets for your analysis.

```python
variables = ["chl", "o2"]
regions = ["Iberian Biscay"]

# We find the products that offer the variables we are interested in:
describe_varriable = copernicusmarine.describe(contains=[variables[0], variables[1]])
prod_variable = []
for product in describe_varriable.products:
    prod_variable.append(product.product_id)
print(f"Products that offer the variables {variables}: {len(prod_variable)}")

# We save the products that offer the region we are interested in:
describe_location = copernicusmarine.describe(contains=[regions[0]])
prod_location = []
for product in describe_location.products:
    prod_location.append(product.product_id)
print(f"Products in the region {regions}: {len(prod_location)}")

# And we search the intersection of both lists:
products = [prod_variable, prod_location]
final_selected_products = set.intersection(*map(set,products))

pairs_dataset_step = {}

for product in describe_location.products:
    # We add a filter to clarify specific products, in this case the "OMI" (Ocean Monitoring Indicators)
        if product.product_id in final_selected_products and "OMI_" not in product.product_id:
            for dataset in product.datasets:
                for version in dataset.versions:
                    for part in version.parts:
                        for part in version.parts:
                            for service in part.services[:-1]:
                            # And we filter the datasets that can be subsetted:
                                if 'arco-' in service.service_name and 'zarr' == service.service_format:
                                    for variable in service.variables:
                                        if (variable.short_name == variables[0], variable.short_name == variables[1]) and variable.coordinates != []:
                                            pairs_dataset_step[dataset.dataset_id] = (product.product_id, variable.coordinates[2].step)

for key, value in pairs_dataset_step.items():
    print("______________________")
    print(f"Product: {value[0]}")
    print(f"Dataset: {key}")
    print(f"Spatial resolution : {value[1]}")
```

--------------------------------

### Subset Dataset Example

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/subset-usage.md

Use this command to remotely subset a dataset by specifying dataset ID, time range, and geographical coordinates. Ensure all required parameters are provided for a successful subset operation.

```bash
copernicusmarine subset --dataset-id cmems_mod_glo_phy_anfc_0.083deg_P1M-m --start-datetime 2026-01-01 --end-datetime 2026-01-03 --minimum-longitude 0.0 --maximum-longitude 0.1 --minimum-latitude 28.0 --maximum-latitude 28.1
```

--------------------------------

### Download Files with Unix Shell-Style Filter

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/get-usage.md

Use the `--filter` option with Unix shell-style wildcards to select specific files for download. This example selects files containing '01yav_temp_200[0-2]'.

```bash
copernicusmarine get --dataset-id cmems_mod_ibi_phy-temp_my_0.027deg_P1Y-m --filter "*01yav_temp_200[0-2]*"
```

--------------------------------

### Plotting Data with Xarray and Matplotlib

Source: https://github.com/mercator-ocean/copernicus-marine-toolbox/blob/main/doc/usage/quickoverview.ipynb

Use xarray and matplotlib to plot a specific variable (e.g., 'chl') from a dataset, visualizing its temporal evolution across different depths. Requires `matplotlib` and `xarray` to be installed.

```python
import matplotlib.pyplot as plt

response_bay["chl"].isel(depth=10).plot(col="time", col_wrap=3)
plt.suptitle("Temporal evolution at sea surface", fontsize=20, y=1.2)
plt.show()
```