Copernicus Marine Toolbox（哥白尼海洋工具箱）安装与使用（V1.3.5）

le丶serein

已于 2025-03-20 09:02:12 修改

阅读量1.3k

点赞数 35

文章标签： python

于 2025-02-27 23:10:06 首次发布

本文链接：https://blog.csdn.net/weixin_71132662/article/details/145840243

版权

由于有大量的海洋数据集可以使用FTP进行下载，在此附上FTP的使用以及如何利用FTP下载AVISO数据。

【AVISO 测高数据获取：注册与利用FileZilla下载】_aviso数据下载-CSDN博客

注：本篇内容由陈师兄与我共同完成，师兄完成第一、第二、第四章节以及第三章节的3.1至3.2.1内容的编写，其余内容以及编辑、排版和发布工作均由本人完成。

一、Copernicus Marine Data Store和Copernicus Marine Toolbox

1.1 目前CMEMS的数据获取方式

1.2 Copernicus Marine Data Store简介

1.3 Copernicus Marine Toolbox简介

二、工具箱的安装

2.1 创建虚拟环境（如果想安装于现有环境中，此步可省略）

2.2 安装copernicusmarine工具箱

2.3 测试copernicusmarine工具箱

一、Copernicus Marine Data Store和Copernicus Marine Toolbox

1.1 目前CMEMS的数据获取方式

现阶段，哥白尼海洋提供两种方式来获取数据：

文件浏览器（图形方法）
哥白尼海洋工具箱（Copernicus Marine Toolbox）（编程方法）

文件浏览器：可以从产品数据访问页面使用，为所有用户提供直观的图形机制来浏览文件夹并从网页下载原始文件。

哥白尼海洋工具箱（Copernicus Marine Toolbox）：对于编程方式，可以使用工具箱下载原始文件。

需要注意的是FTP服务已弃用：FTP是一种标准网络协议，用于在计算机网络上的客户端和服务器之间传输文件，通过启动与服务器的连接来检索文件并使用 Copernicus Marine 凭据（用户名和密码）进行身份验证。当前哥白尼海洋的FTP服务已被弃用，并于2024年3月被新的哥白尼海洋数据存储服务完全取代。

官方说明见以下链接：《How to download original files?》

How to download original files? | Copernicus Marine Help Center

1.2 Copernicus Marine Data Store简介

自2024年4月起，旧的MOTU、OPeNDAP、ERDDAP、FTP和WMS服务将不再使用，完全由新的哥白尼海洋数据存储（Copernicus Marine Data Store）服务取代。在新服务中，哥白尼海洋工具箱（Copernicus Marine Toolbox）允许以更高的性能下载数据，并且没有配额限制。

新的海洋数据存储库将能够利用其可扩展的云环境处理更大量的数据。用户已经习惯的丰富元数据、引文和收藏信息将得以保留，用户可以获得与以前相同水平的服务。用户将享有更高的灵活性，因为可以有选择性地访问、检索和以所需格式保存感兴趣的数据。

这种更方便、更快捷地下载大量数据的能力对哥白尼海洋数据的科学价值具有重大影响。当前的再分析模型产品为研究趋势、发现事件以及在相对较长的时间序列研究中发现现象提供了机会。然而，有部分数据集的时间序列跨度超过30年，这就增加了获取和分析的难度。

同时，能够在云环境中访问整个任务集合为研究人员提供了优势，例如能够有效地扩展资源，对覆盖全球的整个时间序列集合进行相对快速的数据分析。这在现有的用户下载模式下是不可能实现的。海洋数据存储库提供的新功能规模完全不同，为用户提供的功能超越了现有的海洋数据存储库。

此外，新的海洋数据存储库还能为数据分析做好准备，从而增强用户的能力。用户可以直接在云上分析和后处理数据，并浏览所有时间和空间方向的数据。用户还可使用Jupyter Notebook。

官方说明见以下链接：《Introducing the new Copernicus Marine Data Store》

Introducing the new Copernicus Marine Data Store | CMEMS

1.3 Copernicus Marine Toolbox简介

哥白尼海洋工具箱（Copernicus Marine Toolbox）是一款免费且易于使用的工具，可与哥白尼海洋数据存储（Copernicus Marine Data Store）进行互操作，旨在涵盖任何使用情况，从元数据检索到完整数据集或者只是子集，适用于任何类型的产品：数值模型、卫星以及现场观测。

命令行界面（CLI）和 Python界面（API）都提供这些功能：

元数据信息：列出并检索所有变量、数据集、产品及其相关文档的元数据信息。
子集数据集：以首选格式（如ARCO (Analysis-Ready Cloud-Optimized) Zarr或NetCDF文件格式）仅提取感兴趣的部分。
高级过滤器：通过海洋数据存储的直接连接，应用简单或高级过滤器，一次性获取多个原始格式（如NetCDF/GeoTIFF）的文件。
无配额限制：不受容量大小或带宽的限制。

总结而言，工具箱允许在没有配额的情况下探索和下载CMEMS目录中提供的所有产品！

官方说明见以下链接：《Copernicus Marine Toolbox - Introduction》

Copernicus Marine Toolbox - Introduction | Copernicus Marine Help Center

二、工具箱的安装

本节内容主要讲述通过Anaconda的conda-forge (Copernicusmarine | Anaconda.org)进行安装。如果未安装Anaconda，请预先进行安装。如果想通过其它方法进行安装，请参考本节结尾给出的官方说明。

2.1 创建虚拟环境（如果想安装于现有环境中，此步可省略）

1.在命令行界面（CLI）输入创建虚拟环境的命令

#创建python版本为x.x，名字为env_name的虚拟环境

conda create --name env_name python=x.x

注1：哥白尼海洋工具箱与Python 3.9至3.12版本的Windows、Mac和Linux操作系统兼容。

注2：本文创建的虚拟环境名字为“cmt_test”，python版本为3.9。

图：命令行界面输入命令

2.在 Proceed ([y]/n)? 后输入 y ，完成虚拟环境创建

图：完成创建

2.2 安装copernicusmarine工具箱

1.首先激活相应的虚拟环境

#激活名字为env_name的虚拟环境

activate env_name

图：激活虚拟环境

2.通过Anaconda安装工具箱

#安装工具箱

conda install conda-forge::copernicusmarine

图：安装工具箱

3.在 Proceed ([y]/n)? 后输入 y ，完成虚拟环境创建。通过 conda list 查看虚拟环境下的库，copernicusmarine与相应的支持库全部已经安装。

图：完成创建

2.3 测试copernicusmarine工具箱

#命令行界面（CLI）

copernicusmarine -h #查看工具箱帮助

copernicusmarine -V #查看工具箱版本

图：工具箱版本

#Python界面（API）

import copernicusmarine #导入工具箱

print('工具箱版本为：', copernicusmarine.__version__) #输出工具箱版本

图：工具箱版本（VS Code）

官方说明见以下链接：《Copernicus Marine Toolbox - Installation》

Copernicus Marine Toolbox - Installation | Copernicus Marine Help Center

三、工具箱的命令

工具箱执行基于两种界面：命令行界面（CLI）和Python界面（API），本节介绍了不同界面的命令查询方法以及各命令的基本信息。如果想要更加深入地了解，请参考本节结尾给出的官方说明。

3.1 工具箱命令查询方法

在命令行界面（CLI）和Python界面（API），通过以下方式查询各命令完整的描述以及可用选项和参数的详尽列表。需要注意的是：Python界面的查询命令可能无法直接运行，可在交互界面中查看，具体情况见图例。

命令行界面（CLI）	Python界面（API）	简要介绍
copernicusmarine describe -h	copernicusmarine.describe?	Print Copernicus Marine catalog as JSON.
copernicusmarine get -h	copernicusmarine.get?	Download originally produced data files.
copernicusmarine login -h	copernicusmarine.login?	Create a configuration file with your Copernicus Marine credentials.
copernicusmarine subset -h	copernicusmarine.subset?	Download subsets of datasets as NetCDF files or Zarr stores.

命令行界面（CLI）图例

图：命令行界面的查询命令，直接运行

Python界面（API）图例

图：Python界面的查询命令，直接运行报错（VS Code）

图：在Python界面，光标移动到命令位置显示帮助信息（VS Code）

图：在jupyter notebook中，Python查询命令可直接使用

3.2 工具箱命令介绍

工具箱包含四个主要命令（login、describe、subset、get）以及两个仅在Python界面（API）中使用的命令（open_dataset、read_dataframe）。在命令行界面（CLI）和Python界面（API），命令的编写格式略有不同。下表给出了所有命令的基本介绍。

copernicusmarine工具箱的主要命令介绍（CLI与API）
login		通过用户的 Copernicus Marine 凭据创建登录配置文件。
describe		根据指定的参数和选项从哥白尼海洋目录（Copernicus Marine catalogue）中获取元数据信息。
subset		使用给定参数从指定数据集中提取数据子集。
get		根据用户提供的参数从哥白尼海洋服务器（Copernicus Marine server）获取数据。
仅在API中可用	open_dataset	使用 ARCO 系列协议，以“lazy-loading”模式加载指定的 xarray 数据集。这意味着只有在调用计算时才会将数据加载到内存中，通过避免立即加载来优化 RAM 的使用。
	read_dataframe	立即将指定数据集中的 Pandas DataFrame 加载到内存中。与“lazy-loading”不同，该函数一经执行，数据就会立即加载，这在需要快速访问整个数据集时可能更可取，但可能需要谨慎的内存管理。

copernicusmarine工具箱的其它功能介绍（仅API）
__version__	显示工具箱版本
version(distribution_name)	获取指定软件包的版本字符串。
logging_configuration_dict	配置Python中的logging模块，管理日志的输出格式、级别和目标
load_pandas_dataframe	已弃用，使用“read_dataframe”代替。
load_xarray_dataset	已弃用，使用“open_dataset”代替。

注：本文所述的命令介绍基于1.3.1版本工具箱。

3.2.1 Login

#命令行界面（CLI）

copernicusmarine login #登录

图：CLI登录

#Python界面（API）

import copernicusmarine #导入工具箱

copernicusmarine.login() #登录

图：API登录

默认情况下，配置文件（.copernicusmarine-credentials）将保存在主目录中，用户也可以通过自定义指定保存路径。

#命令行界面（CLI）自定义凭据文件以及路径

copernicusmarine login --username <USERNAME> --password <PASSWORD> --configuration-file-directory <PATH>

图：CLI自定义凭据

#Python界面（API）自定义凭据文件以及路径

import copernicusmarine

from pathlib import Path

copernicusmarine.login(

username="********",

password="********",

configuration_file_directory=Path("D:/")

)

图：API自定义凭据

#创建配置文件后，通过在命令中加入以下代码进行使用

--credentials-file <PATH> #命令行界面（CLI）

credentials_file = <PATH> #Python界面（API）

如果没有配置文件，也没有在命令中输入凭据，则运行subset、get命令时会被要求输入凭据。

官方说明见以下链接：《Copernicus Marine Toolbox - Credentials configuration》

Copernicus Marine Toolbox - Credentials configuration | Copernicus Marine Help Center

3.2.2 Describe

通过 describe 命令，用户可以浏览哥白尼海洋数据存储库，并检索所有产品和数据集的元数据。用户可以通过输入感兴趣的关键字来过滤结果，工具箱将搜索目录并返回最相关的匹配结果。对于每个产品或数据集条目，工具箱都会提供所有元数据，描述其物理和时间覆盖范围、来源、日期、格式、版本、平台、提供者和参数，以及背景文件参考。接下来将从Python和CLI（命令行）的方式进行介绍。

Python：利用Python软件中的describe命令可以进行数据集的获取。在默认情况下，当您不带任何参数运行此函数时，它将获取整个目录，但不包括数据集。

为了获取所有产品和数据集的元数据，必须添加参数include_datasets。

图：describe命令获取产品与数据集

图：获取的所有产品的部分示例

在下载CMEMS数据时，会选择一种数据进行下载，因此建议使用contains参数对于具体的某种数据进行获取。假设只想查找GLOBAL_ANALYSISFORECAST_PHY_001_024。

有两种方式：

方式一是在contains中输入数据后的编号。

以GLOBAL_ANALYSISFORECAST_PHY_001_024为例则是“001_024”。

图：方式一，利用数据后的编号

方式二是在contains中输入数据名称。

图：方式二，利用数据名称

图：示例数据产品

如要获取示例数据中的第二个产品，如下图所示。

图：数据获取示例

官方说明请见以下连接：

《Copernicus Marine Toolbox API - Explore the catalogue and metadata》

Copernicus Marine Toolbox API - Explore the catalogue and metadata | Copernicus Marine Help Center

CLI命令行：

CLI中关于describe的所有命令可以通过调用help进行查找说明。

以下列举常用的命令，剩余其他命令请用户自行利用help函数进行查找学习。
1、在CLI中将结果保存在输出文件中，可利用“ > example.json”命令。如下图所示：

2、在CLI中获取所有产品和数据集的元数据，可利用“copernicusmarine describe —include-datasets”命令。如下图所示：

由于数据量庞大，建议将其储存在json文件中。
3、若是想获取某个数据集，则需要“--contains”（--c）命令，该命令可以获取某个数据集，亦可获取含有某种变量（例如温度、盐度）的所有数据集。如下图所示：

图：获取cmems_mod_glo_bgc-bio_anfc_0.25deg_P1D-m数据集的信息

图：获取含有海水温度的所有数据集信息并将其写入json文件

此外，还可以获取多个意向变量的命令，如下图所示：

图：获取所含多个变量数据集信息命令

注：变量之间为OR（或者）的关系，其余关系还有待开发

官方说明请见：

《Copernicus Marine Toolbox CLI - Explore the catalogue and metadata》

Copernicus Marine Toolbox CLI - Explore the catalogue and metadata | Copernicus Marine Help Center

3.2.3 页面下载

本节将介绍如何从页面进行数据下载，利用页面可以下载小于800MB的数据文件。

对于下载界面进行介绍。

3.2.4 Subset

卫星高度计能够准确测量海面高度，探测海洋表面风、波浪、潮汐等动态变化，从而更好地理解海洋的物理过程和气候变化。

该部分为获取数据的重要部分，用于下载CMEMS数据子集，例如选取特定的经纬度、深度、时间数据进行下载。下文将以Python的API命令以及CLI命令进行介绍如何获取数据子集。本文以印度洋上空的冬季洋流，从产品GLOBAL_ANALYSISFORECAST_PHY_001_024：cmems_mod_glo_phy-cur_anfc_0.083deg_PT6H-i为例进行介绍

Python：

对在subset中的常见命令进行介绍，其余命令请见本节最后的链接。

dataset_id：用于输入数据集名称

variables：用于设定下载数据集中的各种变量。

minimum_longitude、maximum_longitude、minimum_latitude、maximum_latitude：分别代表所下载的最小最大经纬度，即下载的区域。

start_time、end_time：所代表的为下载的开始和结束时间。

minimum_depth、maximum_depth：代表下载的最小和最大深度。

output_directory：代表下载输出的路径。

output_filename：代表下载所输出的文件名。

force_download：代表跳过下载该数据集时的确认。

subset_method：代表严格下载所规定数据的范围。

disable_progess_bar：代表是否显示下载进程，显示为True，不显示为False。

其中数据的id、变量、经纬度、开始结束时间等有关数据的具体内容既可以自网站中获取，可以利用describe进行获取。其具体程序如下：

图：subset下载示例
运行该程序，会在命令行中出现需要登陆信息。如下图所示：

图：登陆信息

此时会出现进度条以及新创建的output_directory文件夹以及output_filename的nc文件，如下图所示：

图：进度条示例

图：文件示例

注：下载较慢，请耐心等待！

下载成功之后将出现成功下载的提示，如下图所示：

图：下载成功示例

官方说明请见以下链接：

Copernicus Marine Toolbox API - Subset | Copernicus Marine Help Center

CLI命令：与describe命令相同，在命令行可以利用“--help”进行查看可以利用的subset中的所有命令，如下图所示：

图：subset函数命令部分示例

以下将介绍部分常用命名，“（）”中为简称：

--dataset-url（-u）：dataset的网站。

--dataset-id（-i）：dataset的ID名称。

--variable（-v）：特定的dataset变量。

--minimum-latitude（-y）：获取的最小纬度。

--maximum-latitude（-Y）：获取最大纬度。

--minimum-longitude（-x）：获取最小经度。

--maximum-longitude（-X）：获取的最大经度。

经纬度示例：--minimum-longitude 5.0 --maximum-longitude 10.0 --minimum-latitude 38.0 --maximum-latitude 42.0

--start-datetime（-t）：开始时间。

--end-datetime（-T）：结束时间。

输入时间示例：--start-datetime 2022-01-01 --end-datetime 2022-01-15

--minimum-depth（-z）：深度最小值。

--maximum-depth（-Z）：深度最大值。

深度示例：--minimum-depth 0. --maximum-depth 10.

除此之外，还有自定义下载文件名，保存文件路径等命令，详见-help函数，或者本节末的官方说明链接。

官方说明链接：

Copernicus Marine Toolbox CLI - Subset | Copernicus Marine Help Center

3.2.5 get

卫星高度计能够准确测量海面高度，探测海洋表面风、波浪、潮汐等动态变化，从而更好地理解海洋的物理过程和气候变化

get命令可以获取原始文件，即使用该函数浏览目录并获取元数据，并通过该函数下载数据集的子集。get函数中的命令与subset中的命令大致相同，包括dataset_url、dataset_id等，注意：get命令中不含有经纬度，时间，深度的界定！关于dataset_url、dataset_id等命令与subset中相同，请前往3.2.4 subset章节学习。本节重点介绍filter命令。

filter该命令为过滤器，用于下载特定文件，下图中介绍filter基本用法：
1、下载dataste的2023年1月份文件：

图：下载2023年1月份文件

2、下载特定日期范围内数据：例如2023年1月21-23日数据。

图：下载2023年1月21-23日数据

在基础命令介绍完成后，下面将介绍从多个数据集获取特定日期的所有文件：

图：下载多个数据集特定日期的所有文件

注：以上示例仅供参考，具体日期以及数据请依据describe中的data信息进行下载

官方说明请见以下链接：

Copernicus Marine Toolbox API - Get original files | Copernicus Marine Help Center

3.2.6 INSITU数据下载

INSITU数据下载相较于其他数据而言有较大的不同之处，本节主要就如何使用索引文件下载INSITU数据和python上的索引文件过滤INSITU数据文件进行介绍。

1、如何使用索引文件下载INSITU数据：

使用API界面：
利用index_parts命令获取索引文件，如下图所示：

图：获取的索引文件

注：红框中索引的4个文件。输入“y”进行下载。

在程序的当前目录中会存有下载的index_history、index_latest、index_monthly、index_platform数据txt文件，如下图红框所示：

图：下载的文件

接下来将获取感兴趣的文件，并将其进行存储，以TS_TG为例：

图：代码示例

图：df示例

下载成功后会在当前目录中显示下载的文件，如下图所示：

图：下载文件部分示例

之后将针对保存的文件进行下载，利用get以及get中的file_list进行下载。如下图所示；

图：下载代码示例

官方说明请见以下链接：

How to download INSITU data using index files? | Copernicus Marine Help Center

2、python上的索引文件过滤INSITU数据文件：

接下来将根据索引文件的不同类别来过滤文件：

product_id、file_name、geospatial_lat_min、geospatial_lat_max、geospatial_lon_min、geospatial_lon_max、time_coverage_star、time_coverage_end、institution、date_updat、data_mode、parameters

首先导入copernicusmarine以及pandas库。
后利用index_parts下载数据集的索引文件