In csaybar/rgee: R Bindings for Calling the 'Earth Engine' API

1. What is Google Earth Engine ?

Google Earth Engine is a computing platform that allows users to run geospatial analysis on Google's infrastructure. There are several ways to interact with the platform:

• Explorer
• Code Editor
• Javascript client library
• Python client library
• R client library

This website is focused on the last one, you can use the R client library to send/receive messages to/from the Earth Engine server and develop web applications.

knitr::opts_chunk$set(
  comment = '', fig.width = 6, fig.height = 6
)

2. The purpose of Earth Engine is to:

• Perform highly-interactive algorithm development at global scale

• Push the edge of the envelope for big data in remote sensing

• Enable high-impact, data-driven science

• Make substantive progress on global challenges that involve large geospatial datasets

3. Components:

The main components of Earth Engine are:

Datasets: A petabyte-scale archive of publicly available remotely sensed imagery and other data. Explore the data catalog.

Compute power: Google’s computational infrastructure optimized for parallel processing of geospatial data.

WEB REST API/Client libraries: For making requests to the Earth Engine servers.

4. Meet Earth Engine

Users must considerate that the Earth Engine API and advanced Earth Engine functionality are experimental and subject to change. Access is limited and requires requesting access via the form. See Earth Engine official website to obtain more information.

5. Why rgee instead of code editor (Javascript)?

A short comparison based on Tyler Erickson presentation.

Code Editor	R
Easy to get started	Easy to share code between scripts.
Trivial to share scripts	Easier transition to a web application (Shiny).
Built in authentication	An I/O API more friendly with R users.
Limited input/output functionality	Many, many plotting options
Integration with other JS libraries is not possible	Some assembly (& maintenance) required!.

6. Installation

rgee depends on reticulate, R6 and processx. Therefore, users should ensure that their system do not have problem to install those R packages. To install rgee run as follow:

Stable version:

install.packages("rgee")

Dev version:

remotes::install_github("r-spatial/rgee")

rgee has two types of dependencies: strict dependencies that must be satisfied before the rgee initialization (i.e. ee_Intialize()) and the credentials dependencies that unlock all rgee I/0 functionality with Google Drive (GD) and Google Cloud Storage (GCS).

If the strict dependencies are not fulfilled rgee just will not work. The dependencies that comprised this group are:

• Google account with Earth Engine activated

• Python >= v3.5

• EarthEngine Python API (Python package)

The activation of an Earth Engine account depends on each user, check the official website of Google Earth Engine for more details. If you do not count with a Python environment or a version of the EarthEngine Python API, we strongly recommend you run:

library(rgee)
ee_install(py_env = "rgee") # It is just necessary once!

This function will realize the following six tasks:

1. If you do not count with a Python environment, it will display an interactive menu to install Miniconda (a free minimal installer for conda).

2. Remove the previous Python environment defined with the same name if it exists.

3. Create a new Python environment.

4. Set the environmental variable EARTHENGINE_PYTHON and EARTHENGINE_ENV. These variables will be used to define the reticulate environmental variable RETICULATE_PYTHON when rgee is loaded.

5. Install rgee Python dependencies: Earth Engine Python API and numpy.

6. Interactive menu to confirm if restart the R session to see changes.

However, the use of rgee::ee_install() is not mandatory. You can count on with your own custom installation. This would be also allowed. If you are a Rstudio v.1.4 > user, this tutorial will help you to properly set a Python Environment with your R session without rgee::ee_install(). Take into account that the Python Environment you set must have installed the Earth Engine Python API and Numpy.

By the other hand, the credentials dependencies are only needed to move data from Google Drive and Google Cloud Storage to your local environment. These dependencies are not mandatory. However, they will help you to create a seamless connection between R and Earth Engine. The dependencies that comprised this group are shown below:

• Google Cloud Storage credential

• Google Drive credential

See the next section to learn how to correctly set both credentials.

7. Authentication

As we have seen previously, rgee deal with three different Google API's:

• Google Earth Engine

• Google Drive

• Google Cloud Storage

To authenticate/initialize either Google Drive or Google Cloud Storage, you just need to run as follow:

library(rgee)
#ee_reattach() # reattach ee as a reserve word
# Initialize just Earth Engine
ee_Initialize() 
ee_Initialize(email = '[e-mail]') # Use the argument email is not mandatory, but it's helpful to change of EE user.
# Initialize Earth Engine and GD
ee_Initialize(email = '[e-mail]', drive = TRUE)
# Initialize Earth Engine and GCS
ee_Initialize(email = '[e-mail]', gcs = TRUE)
# Initialize Earth Engine, GD and GCS
ee_Initialize(email = '[e-mail]', drive = TRUE, gcs = TRUE)

If the Google account is verified and the permission is granted, you will be directed to an authentication token. Copy this token and paste it in your R console. Unlike Earth Engine and Google Drive, Google Cloud Storage need to set up its credential manually (link1 and link2). In all cases, the users credentials always will be stored in:

``` {r eval = FALSE} ee_get_earthengine_path()

Remember you only have to authorize once, for next sessions it will not be necessary.

## 8. Hello World

we know that installing **rgee** can be frustrating sometimes :( , so, congratulations to go so far :D :D. In this small example will show you how to display SRTM elevation values worldwide!.

```r
library(rgee)
ee_Initialize()
srtm <- ee$Image("USGS/SRTMGL1_003")

Define visualization parameters

viz <- list(
  max = 4000,
  min = 0,
  palette = c("#000000","#5AAD5A","#A9AD84","#FFFFFF")
)

Use Map$addLayer to visualize the map interactively

Map$addLayer(
  eeObject = srtm,
  visParams =  viz,
  name = 'SRTM',
  legend = TRUE
)

9. Checking

The ee_check() function will help you for checking the sanity of your rgee installation and dependencies.

• ee_check_python() - Python version
• ee_check_credentials() - Google Drive and GCS credentials
• ee_check_python_packages() - Python packages

library(rgee)
ee_check()

ee_check_python()
ee_check_credentials()
ee_check_python_packages()

csaybar/rgee documentation built on March 11, 2021, 5:48 a.m.