安装#

推荐使用mamba或者conda安装该软件：

1mamba install conda-forge::copernicusmarine

或者使用pip安装：

1pip install copernicusmarine

使用方法#

在当前版本中，copernicusmarine 工具共包含四个核心命令：

• Login (登录)： 用于设置配置文件，让用户无需反复管理繁琐的身份验证凭据。
• Describe (描述)： 用于解析产品目录，检索与特定产品和数据集相关的详细元数据信息。
• Subset (子集)： 支持远程数据子集化操作，用户可按需提取 NetCDF 文件或 Zarr 存储格式的数据子集，且不受数据量额度限制。
• Get (获取)： 用于下载由数据生产者原始发布的完整文件，同样不受数据量额度限制。

1. Login

login 命令的核心功能是帮助用户验证哥白尼海洋账号凭据，并创建配置文件。创建后的配置文件将自动被工具箱读取，方便用户在使用需要身份验证的服务时，无需重复输入账号密码。

只需运行以下命令，并根据提示输入您的哥白尼海洋用户名和密码即可。

命令行(CLI):

1copernicusmarine login

Python库 (API):

1import copernicusmarine.login()

默认情况下，配置文件将保存在用户的主目录中。用户也可以通过 --configuration-file-directory 选项，自定义配置文件的保存路径。

2. Describe

describe 命令的核心作用是帮助用户浏览哥白尼海洋数据存储平台，并检索所有数据产品或数据集的元数据信息。

用户可以输入关键词进行结果过滤，软件将智能搜索产品目录，并返回最相关的匹配结果。

针对每个产品或数据集条目，该工具都会提供详尽的元数据信息，包括空间和时间覆盖范围、数据来源、日期、格式、版本、平台、数据提供商、要素参数等关键信息，并附带背景文档的参考链接，方便用户深入了解数据。

以下示例展示如何在命令行和API中使用describe命令，搜索元数据中包含海水温度 (thetao) 的产品和数据集：

命令行(CLI):

1copernicusmarine describe —include-datasets -c thetao

Python(API):

1import copernicusmarine
2copernicusmarine.describe(
3 include_datasets = True,
4 contains = [‘thetao’]
5)

3. Subset

subset 命令提供下载数据集子集的功能。用户可以精确指定所需的变量、空间区域、时间范围和深度范围，实现数据的按需获取。此功能在用户仅需部分数据时尤为实用，避免了下载完整数据集的冗余和耗时。

subset 命令的默认输出格式为NetCDF (.nc) 文件。用户也可以通过 --file-format zarr 选项，或在 -f/--output-filename 参数中指定 .zarr 扩展名，将结果导出为Zarr格式。

subset 命令支持多种参数，用于精细化数据子集操作：

命令行(CLI):

1copernicusmarine subset —dataset-id [OPTION]

其中，[OPTION] 代表用于数据子集化的参数选项。

Python(API):

1import copernicusmarine
2copernicusmarine.subset(
3 dataset_id = <dataset_id>,
4 [OPTION] = ,
5)

其中，[OPTION] 同样代表用于数据子集化的参数选项。

假设用户需要下载以下数据，该数据代表佛得角群岛海域，从海面至水下5米深度范围内的海水温度，时间跨度为两周：

• 产品: GLOBAL_ANALYSISFORECAST_PHY_001_024
• 数据集: cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m
• 变量: thetao (海水温度)
• 经度范围: [-26, -22]
• 纬度范围: [14, 18]
• 深度范围: [0, 5]
• 时间范围: 2023-08-07 至 2023-08-21

用户可以使用以下命令来完成数据下载：

命令行(CLI):

1copernicusmarine subset —dataset-id cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m —variable thetao —start-datetime 2023-08-07T00:00:00 —end-datetime 2023-08-21T23:59:59 —minimum-longitude -26 —maximum-longitude -22 —minimum-latitude 14 —maximum-latitude 18 —minimum-depth 0 —maximum-depth 5

Python(API):

1import copernicusmarine
2copernicusmarine.subset (
3 dataset_id = “cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m”,
4 variables = [“thetao”],
5 start_datetime = “2023-08-07T00:00:00”,
6 end_datetime = “2023-08-21T23:59:59”,
7 minimum_longitude = -26,
8 maximum_longitude = -22,
9 minimum_latitude = 14,
10 maximum_latitude = 18,
11 minimum_depth = 0,
12 maximum_depth = 5
13)

当然，用户也可以先使用 describe 命令获取目标数据集的元数据信息，再根据元数据构建 subset 请求，以更精准地提取所需数据。

4. Get

get命令允许用户下载由数据生产者在哥白尼海洋数据存储平台上打包和存储的原始文件。当用户需要获取一个或多个完整文件，甚至是整个数据集的原始格式时，get 命令将是理想选择。

只需简单运行 get 命令，即可轻松获取数据集中所有可用的文件：

命令行(CLI):

1copernicusmarine get —dataset-id

Python(API):

1import copernicusmarine.get(
2 dataset_id = ,
3)

下面我们来看几个具体的应用示例：

Get命令示例1：下载完整数据集

假设用户需要下载Iberian Biscay Irish海域海洋物理状态的年平均数据，并希望获取完整的时间序列数据（即下载所有文件，构成完整数据集）。

• 产品: IBI_MULTIYEAR_PHY_005_002
• 数据集: cmems_mod_ibi_phy_my_0.083deg-3D_P1Y-m

可以使用以下命令来下载完整数据集：

命令行(CLI):

1copernicusmarine get —dataset-id cmems_mod_ibi_phy_my_0.083deg-3D_P1Y-m

Python(API):

1import copernicusmarine.get(
2 dataset_id = “cmems_mod_ibi_phy_my_0.083deg-3D_P1Y-m”
3)

Get命令示例2：下载特定文件

假设用户需要下载Iberian Biscay Irish海域海洋物理状态的年平均数据，但仅需下载2000年、2001年和2002年的数据。

可以使用以下命令来下载特定文件：

命令行(CLI):

1copernicusmarine get —dataset-id cmems_mod_ibi_phy_my_0.083deg-3D_P1Y-m —filter ”*_200[0-2]R”

Python(API):

1import copernicusmarine.get(
2 dataset_id = “cmems_mod_ibi_phy_my_0.083deg-3D_P1Y-m”,
3 filter = ”*_200[0-2]R”
4)

**PS：**Copernicus Marine Toolbox于2025年1月8日发布了2.0版本。这是一个重要的版本更新，带来了诸多新功能和性能提升。 此外，新版本还显著提升了易用性和可访问性，并移除了已弃用的选项，旨在为用户提供更高效的数据访问体验，强烈建议进行版本升级。