Chapter 2 Download

The Copernicus Marine Toolbox is originally written in Python. There is also a new R package aimed to download and import data into R without the need of external software (see the CopernicusMarine R package); however, at the moment we write this tutorial, this R package is still in development and several features need to be added. For that reason, we are going to use the reticulate R package, which provides an interface to Python modules, classes, and functions from R.

For more information on how to use the Copernicus Marine Toolbox in R, see the official documentation.

2.1 Register

You need to register in the Copernicus Marine Service to get access to the data. You can register here. You must remember your username and password!

Of course, you can ignore this step in case you already have an account.

2.2 Installation

Install the reticulate package and then load the package:

install.packages("reticulate") 
library("reticulate")

The next step is to install Phyton (in case you do not have it). This should be only done once. This can be easily done by running the following line (it may take a few minutes):

reticulate::install_python()

2.3 Set up the Python environment

Now we create a dedicated Python virtual environment for the Copernicus Marine Toolbox. Using a separate environment ensures a clean, isolated space where the package and its dependencies will not interfere with other projects.

entorno = "DownloadCopernicus"
virtualenv_create(envname = entorno)
virtualenv_install(entorno, packages = c("copernicusmarine"))
use_virtualenv(entorno, required = TRUE)

Then, we store the copernicusmarine package in a variable to use the toolbox’s various functions:

atributos_cms <- import(module = "copernicusmarine")

We also need to provide the username and password of our account created in the first step. This should be only done if you have never used the toolbox before and never entered your login details:

atributos_cms$login("username", "password")

2.4 Explore the Marine Copernicus Data Store

We highly recommend exploring the Marine Copernicus Data Store. Each product has a manual with all the needed information. You must be particularly familiar with the temporal and spatial range and resolution of the chosen dataset, the dataset ID, and the variable names.

2.5 Download the data (single file)

Here, you are going to download the oceanographic data from the CMEMS. This data will be saved to a single netCDF file in a specified directory. We provide an example:

atributos_cms$subset(
    dataset_id        = "cmems_mod_glo_phy_my_0.083deg_P1D-m",
    variables         = list("thetao"),
    minimum_longitude = -83,
    maximum_longitude = -69,
    minimum_latitude  = -19,
    maximum_latitude  = -3,
    start_datetime    = format(x = as.Date("2015-02-01"), format = "%Y-%m-%dT00:00:00"),
    end_datetime      = format(x = as.Date("2015-04-30"), format = "%Y-%m-%dT00:00:00"),
    minimum_depth     = 0,
    maximum_depth     = 100,
    output_directory  = "C:/Use/env_data/"
    )

In this example, we are downloading daily data from the GLORYS12V1 product. The variable is potential temperature (thetao), the spatial extent is between -83 and -69 degrees longitude and between -19 and -3 degrees latitude, and the temporal extent is between 2015-02-01 and 2015-04-30. The data (.nc file) will be saved in the specified directory. We also specify the depth range (0-100 m), although that can be omitted in case we want to download all the depth layers.

2.6 Download the data (multiple files)

In case you want to download the data and save it in multiple files, you can adapt the previous example to work in a loop. We have done that in a wrapper function called downloadCOPERNICUS (you can find it here):

First, let’s load the function directly from Github and required library:

source("https://raw.githubusercontent.com/GiancarloMCorrea/extractOceanVariables/refs/heads/main/code/copernicus/multiple/downloadCOPERNICUS.R")
library("lubridate")

Then, download the data:

downloadCOPERNICUS(
    xlim        = c(-83, -69),
    ylim        = c(-19, -3),
    datelim     = c("2015-02-01", "2015-04-30"),
    depthlim    = c(0, 100),
    field       = "thetao",
    dataid      = "cmems_mod_glo_phy_my_0.083deg_P1D-m",
    savedir     = "C:/Use/env_data/"
    )

This function will download the oceanographic data and save it in several .nc files. For the example above, three .nc files will be created:

  • 2015-02-01.nc
  • 2015-03-01.nc
  • 2015-04-01.nc

As you may see, each .nc file will contain the data for a specific month. Note that the information contained in each netCDF file may have several time layers (e.g., daily temporal resolution) or a single time layer (e.g., monthly temporal resolution).