Introduction to rgee

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.

2. The purpose of Earth Engine is to:

Perform highly interactive algorithm development at global scale
Push 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

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. To install rgee run:

Stable version:

install.packages("rgee")

Dev version:

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

rgee has two types of dependencies: strict dependencies that must be present before rgee initialization (i.e. ee_Initialize()) 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 installed, rgee just will not work. These dependencies 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 have 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 perform the following six tasks:

If you do not have a Python environment, it will display an interactive menu to install Miniconda (a free minimal installer for conda).
Remove the previous Python environment defined with the same name if it exists.
Create a new Python environment.
Set the environmental variables EARTHENGINE_PYTHON and EARTHENGINE_ENV. These variables will be used to define the reticulate environmental variable RETICULATE_PYTHON when rgee is loaded.
Install rgee Python dependencies: Earth Engine Python API and numpy.
Ask to restart the R session in order to see changes.

However, the use of rgee::ee_install() is not mandatory; you can instead use your own custom installation. If you are an 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.

On 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. These dependencies are:

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 deals 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:

library(rgee)
#ee_reattach() # reattach ee as a reserve word
# Initialize just Earth Engine
ee_Initialize() 
ee_Initialize(user = 'csaybar@gmail.com') # Use the argument email is not mandatory, but it's helpful to change of EE user.
# Initialize Earth Engine and GD
ee_Initialize(user = 'csaybar@gmail.com', drive = TRUE)
# Initialize Earth Engine and GCS
ee_Initialize(user = 'csaybar@gmail.com', gcs = TRUE)
# Initialize Earth Engine, GD and GCS
ee_Initialize(user = 'csaybar@gmail.com', 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 needs to set up its credential manually (link1 and link2). In all cases, the user’s credentials will be stored in:

ee_get_earthengine_path()

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

8. Hello World

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

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()