Title:	R Interface to Copernicus Marine Service
Version:	0.1.0
Description:	Provides an R interface to the Copernicus Marine Service for downloading and accessing marine data. Integrates with the official 'copernicusmarine' Python library through 'reticulate'. Requires Python 3.7+ and a free Copernicus Marine account. See https://marine.copernicus.eu/ and https://pypi.org/project/copernicusmarine/ for more information.
License:	MIT + file LICENSE
URL:	https://github.com/HansTtito/copernicusR
BugReports:	https://github.com/HansTtito/copernicusR/issues
Encoding:	UTF-8
RoxygenNote:	7.3.2
Imports:	reticulate (≥ 1.20)
Suggests:	getPass, testthat (≥ 3.0.0), withr, terra, stars, knitr, rmarkdown
VignetteBuilder:	knitr
SystemRequirements:	Python (>= 3.7), copernicusmarine Python library
NeedsCompilation:	no
Packaged:	2025-07-05 21:04:49 UTC; hkev2
Author:	Hans Ttito [aut, cre]
Maintainer:	Hans Ttito <kvttitos@gmail.com>
Repository:	CRAN
Date/Publication:	2025-07-09 10:50:02 UTC

Copernicus private environment (internal use)

Description

This function creates and manages the internal environment where the package stores persistent objects (e.g., Python module references, configurations, etc.). Uses the package namespace to avoid global environment pollution while providing robust handling for different execution contexts (normal use, testing, etc.).

Usage

.copernicus_env()

Value

An environment object for internal package state management.

Reset internal environment (for testing and cleanup)

Description

Reset internal environment (for testing and cleanup)

Usage

.reset_copernicus_env()

Clear Copernicus Marine credentials

Description

Removes stored Copernicus Marine credentials from session options and environment variables.

Usage

copernicus_clear_credentials()

Value

Invisible TRUE.

Examples

copernicus_clear_credentials()

Search and initialize Python on any operating system (internal use)

Description

Searches for the Python executable in common paths and the system PATH. If found, it initializes it via reticulate.

Usage

copernicus_configure_python(verbose = TRUE)

Value

The detected Python configuration (py_config object).

Download data from Copernicus Marine

Description

Downloads .nc files from the Copernicus Marine catalog. Allows specifying all options of the Python function. Uses stored credentials from options/environment variables if available.

Usage

copernicus_download(
  dataset_id,
  variables,
  start_date,
  end_date,
  bbox = c(-180, 179.92, -80, 90),
  depth = c(0.494, 0.494),
  dataset_version = "202406",
  output_file = NULL,
  username = NULL,
  password = NULL,
  verbose_download = TRUE,
  ...
)

Arguments

Value

Absolute path to the downloaded file, or NULL if it fails.

Get Copernicus Marine credentials

Description

Retrieves stored Copernicus Marine credentials from session options or environment variables.

Usage

copernicus_get_credentials(mask_password = TRUE)

Arguments

Value

List with username and password (optionally masked).

Examples

# Get credentials (password masked)
copernicus_get_credentials()

# Get credentials (password visible - use with caution)
copernicus_get_credentials(mask_password = FALSE)

Import the copernicusmarine Python module (internal use)

Description

Import the copernicusmarine Python module (internal use)

Usage

copernicus_import_module(py)

Arguments

Value

Imported copernicusmarine module.

Install the Python package copernicusmarine (internal use)

Description

Install the Python package copernicusmarine (internal use)

Usage

copernicus_install_package(py = NULL, verbose = TRUE)

Arguments

Value

Invisible TRUE if the installation is successful.

Check if Copernicus Marine Python module is ready

Description

Checks if the Python module is properly loaded and credentials are configured to use Copernicus Marine. Returns TRUE if everything is ready.

Usage

copernicus_is_ready(verbose = TRUE)

Arguments

Value

TRUE if the Python module is loaded and credentials are available.

Open dataset from Copernicus Marine without download

Description

Opens a dataset directly from Copernicus Marine using open_dataset. Returns a Python xarray.Dataset object that can be processed in R. Useful for exploring data without downloading full files. Uses stored credentials from options/environment variables if available.

Usage

copernicus_open_dataset(
  dataset_id,
  variables = NULL,
  start_date = NULL,
  end_date = NULL,
  bbox = NULL,
  depth = NULL,
  dataset_version = NULL,
  username = NULL,
  password = NULL,
  verbose_open = TRUE,
  ...
)

Arguments

Value

Python xarray.Dataset object, or NULL if it fails.

Set Copernicus Marine credentials in environment file

Description

Helper function to set credentials in .Renviron file for persistent storage. This is more secure than storing in scripts.

Usage

copernicus_set_env_credentials(username, password, overwrite = FALSE)

Arguments

Value

Invisible TRUE if successful.

Examples

## Not run: 
# Set credentials in .Renviron (will persist across R sessions)
copernicus_set_env_credentials("your_username", "your_password")

## End(Not run)

Configure Copernicus Marine credentials

Description

Sets up Copernicus Marine Service credentials using various methods:

1. Function parameters

2. R session options

3. Environment variables

4. Interactive prompt (only in interactive sessions)

Usage

copernicus_setup_credentials(
  username = NULL,
  password = NULL,
  store_credentials = TRUE,
  prompt_if_missing = interactive()
)

Arguments

Value

Invisible list with username and password (password is masked).

Examples

## Not run: 
# Set credentials directly
copernicus_setup_credentials("username", "password")

# Set credentials and store in options
copernicus_setup_credentials("username", "password", store_credentials = TRUE)

# Try to get from environment/options
copernicus_setup_credentials()

## End(Not run)

Test Copernicus integration

Description

Performs a small test download to validate that the whole system works. Uses stored credentials if available. Downloads to tempdir().

Usage

copernicus_test(username = NULL, password = NULL)

Arguments

Value

TRUE if the test was successful.

Test opening of Copernicus dataset

Description

Performs a test dataset opening to validate that the open_dataset function works. Uses stored credentials if available.

Usage

copernicus_test_open(username = NULL, password = NULL)

Arguments

Value

TRUE if the test was successful.

Validate Copernicus Marine credentials

Description

Tests if the stored credentials work by attempting a simple API call.

Usage

copernicus_validate_credentials()

Value

Logical. TRUE if credentials are valid, FALSE otherwise.

Examples

## Not run: 
copernicus_validate_credentials()

## End(Not run)

Set up Copernicus Marine integration with credentials

Description

Sets up the Python environment and loads the copernicusmarine module for use in R. Optionally configures Copernicus Marine credentials for the session. It is recommended to run this once per session before calling other functions in the package. Note: This function does not install Python packages by default for CRAN compliance.

Usage

setup_copernicus(
  install_copernicus = FALSE,
  username = NULL,
  password = NULL,
  store_credentials = TRUE
)

Arguments

Value

Invisible TRUE if the configuration was successful.

Examples

## Not run: 
# Basic setup without credentials (manual Python package installation required)
setup_copernicus()

# Setup with credentials
setup_copernicus(username = "your_username", password = "your_password")

# Setup reading from environment variables
setup_copernicus()  # Will look for COPERNICUS_USERNAME and COPERNICUS_PASSWORD

# Setup and store credentials for session
setup_copernicus(username = "user", password = "pass", store_credentials = TRUE)

## End(Not run)