Google Earth Engine for R

rgee is a binding package for calling Google Earth Engine API from within R. Additionally, several functions have been implemented to make simple the connection with the R spatial ecosystem. The current version of rgee has been built considering the earthengine-api 0.1.217. Note that access to Google Earth Engine is only available to registered users.

More than 250+ examples using Google Earth Engine with R are available here

What is Google Earth Engine?

Google Earth Engine is a cloud-based platform that allows users to have an easy access to a petabyte-scale archive of remote sensing data and run geospatial analysis on Google’s infrastructure. Currently, Google offers support only for Python and JavaScript. rgee will fill the gap starting to provide support to R!. Below you will find the comparison between the syntax of rgee and the two Google-supported client libraries.

Earth Engine Javascript API:

image = ee.Image('CGIAR/SRTM90_V4')
print(image.bandNames())
#> 'elevation'

Earth Engine Python API:

import ee
ee.Initialize()
image = ee.Image('CGIAR/SRTM90_V4')
image.bandNames().getInfo()
#> [u'elevation']

rgee:

library(rgee)
ee_Initialize()

# Python Style
image <- ee$Image('CGIAR/SRTM90_V4')
image$bandNames()$getInfo()
#> [1] "elevation"

# Or use Pipes instead!!
image <- ee$Image('CGIAR/SRTM90_V4') %>%
  ee$Image$bandNames() %>% 
  ee$List$getInfo()
#> [1] "elevation"

Quite similar, isn’t it?. However, there are additional smaller changes that you must consider when you use Google Earth Engine with R. Please check the consideration section before start coding!

Installation

Install the rgee package from GitHub is quite simple, you just have to run in your R console as follows:

remotes::install_github("csaybar/rgee")

rgee depends on sf. Therefore, it is necessary to install its external libraries, follow the installation steps specified here.

Docker image

docker pull csaybar/rgee
docker run -d -p 8787:8787 -e USER=rgee -e PASSWORD=rgee --name rgee-dev csaybar/rgee

After that, in your preferred browser, run:

127.0.0.1:8787

Requirements

Prior to using rgee you will need to install a Python version higher than 3.5 in your system. rgee counts with a installation module, use it to quickly set up the external dependencies of rgee:

library(rgee)

# 1. Initialize rgee with ee_Initialize(). If there is no any Python environment, miniconda
# will be installed by default.
ee_Initialize()

# 2. Create a Python environment, e.g. ee.
ee_create_pyenv(python_env = "ee")

# 3. Find all Python environments  in the system.
ee_discover_pyenvs()

# 4. Set a Python environment (e.g. ee) and restart R to see changes. e.g
ee_set_pyenv(
  python_path = '/home/MY_USER_HERE/.virtualenvs/ee/bin/python',
  python_env = 'ee'
)

# 5. Install Python package dependencies
ee_install_python_packages()

# 6. Initialize rgee again!
ee_Initialize()

Additionally, use the functions below, as many times as you want, for checking user info, check sanity of credentials and Python packages, and remove credentials.

ee_check() # Check non-R dependencies
ee_user_info() # Display credentials information
ee_users() # Display credentials information of all users
ee_remove_credentials() # Remove credentials of a specific user
ee_clean_pyenv() # Remove reticulate system variables

Also, consider checking the setup section for major information to customizing Python installation.

Package Conventions

• All rgee functions have the prefix ee_. Auto-completion is your friend :).
• Full access to the Earth Engine API with the prefix ee$…:.
• Authenticate and Initialize the Earth Engine R API with ee_Initialize:, you just will need to do it once by session!.
• rgee is “pipe-friendly”, we re-exports %>%, but rgee does not require its use.
• Wrap your R function using ee_pyfunc before passing them to the Earth Engine Web REST API. This is not compulsory, but it will help reduce possible bugs 🐛.

Quick Demo

1. Compute the trend of night-time lights (JS version)

Authenticate and Initialize the Earth Engine R API.

library(rgee)
ee_Initialize()
#ee_reattach() # reattach ee as a reserve word

Adds a band containing image date as years since 1991.

createTimeBand <-function(img) {
  year <- ee$Date(img$get('system:time_start'))$get('year')$subtract(1991L)
  ee$Image(year)$byte()$addBands(img)
}

Map the time band creation helper over the night-time lights collection.

collection = ee$
  ImageCollection('NOAA/DMSP-OLS/NIGHTTIME_LIGHTS')$
  select('stable_lights')$
  map(createTimeBand)

Compute a linear fit over the series of values at each pixel, visualizing the y-intercept in green, and positive/negative slopes as red/blue.

col_reduce <- collection$reduce(ee$Reducer$linearFit())
col_reduce <- col_reduce$addBands(
  col_reduce$select('scale'))
ee_print(col_reduce)

Create a interactive visualization!

Map$setCenter(9.08203, 47.39835, 3)
Map$addLayer(
  eeObject = col_reduce,
  visParams = list(
    bands = c("scale", "offset", "scale"),
    min = 0,
    max = c(0.18, 20, -0.18)
  ),
  name = "stable lights trend"
)

2. Extract precipitation values

Load sf and authenticate and initialize the Earth Engine R API.

library(rgee)
library(sf)
ee_Initialize()
# ee_reattach() # reattach ee as a reserve word

Read the nc shapefile.

nc <- st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE) %>%
  st_transform(4326) # Transform coordinates

Map each image from 2001 to extract the monthly precipitation (Pr) from the Terraclimate dataset

terraclimate <- ee$ImageCollection("IDAHO_EPSCOR/TERRACLIMATE")$
  filterDate("2000-01-01", "2001-01-01")$
  map(ee_pyfunc(function(x) x$select("pr")))

Extract monthly precipitation values from the Terraclimate ImageCollection through ee_extract. ee_extract works similar to raster::extract you just need to define: the ImageCollection object (x), the geometry (y), and a function to summarize the values (fun).

ee_nc_rain <- ee_extract(x = terraclimate, y = nc, fun = ee$Reducer$max(), id = "FIPS")
colnames(ee_nc_rain) <- c("FIPS", month.abb)
head(ee_nc_rain)

FIPS	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug	Sep	Oct	Nov	Dec
37009	93	68	106	168	73	97	117	107	166	4	89	56
37005	85	64	99	165	66	96	107	106	163	4	83	53
37171	95	54	87	143	59	114	101	119	162	2	67	48
37053	122	50	67	118	135	183	142	213	174	7	72	49
37131	115	49	63	108	115	163	152	195	132	0	57	44
37091	122	43	64	109	121	169	146	200	143	1	57	43

Create a simple plot!

ee_nc_rain <- merge(nc, ee_nc_rain, by = "FIPS")
plot(ee_nc_rain["Jan"], main = "2001 Jan Precipitation - Terraclimate", reset = FALSE)

3. Create an NDVI-animation (JS version)

Load sf and authenticate and initialize the Earth Engine R API.

library(rgee)
library(sf)
ee_Initialize()
# ee_reattach() # reattach ee as a reserve word

Define the regional bounds of animation frames and a mask to clip the NDVI data by.

mask <- system.file("shp/arequipa.shp", package = "rgee") %>% 
  st_read(quiet = TRUE) %>% 
  sf_as_ee()
region <- mask$geometry()$bounds()

Retrieve the MODIS Terra Vegetation Indices 16-Day Global 1km dataset as an ee.ImageCollection and select the NDVI band.

col <- ee$ImageCollection('MODIS/006/MOD13A2')$select('NDVI')

Group images by composite date

col <- col$map(function(img) {
  doy <- ee$Date(img$get('system:time_start'))$getRelative('day', 'year')
  img$set('doy', doy)
})
distinctDOY <- col$filterDate('2013-01-01', '2014-01-01')

Define a filter that identifies which images from the complete collection match the DOY from the distinct DOY collection.

filter <- ee$Filter$equals(leftField = 'doy', rightField = 'doy');

Define and Apply the join; convert the resulting FeatureCollection to an ImageCollection.

join <- ee$Join$saveAll('doy_matches')
joinCol <- ee$ImageCollection(join$apply(distinctDOY, col, filter))

Apply median reduction among matching DOY collections.

comp <- joinCol$map(function(img) {
  doyCol = ee$ImageCollection$fromImages(
    img$get('doy_matches')
  )
  doyCol$reduce(ee$Reducer$median())
})

Define RGB visualization parameters.

visParams = list(
  min = 0.0,
  max = 9000.0,
  bands = "NDVI_median",
  palette = c(
    'FFFFFF', 'CE7E45', 'DF923D', 'F1B555', 'FCD163', '99B718', '74A901',
    '66A000', '529400', '3E8601', '207401', '056201', '004C00', '023B01',
    '012E01', '011D01', '011301'
    )
)

Create RGB visualization images for use as animation frames.

rgbVis <- comp$map(function(img) {
  do.call(img$visualize, visParams) %>% 
    ee$Image$clip(mask)
})

Define GIF visualization parameters.

gifParams <- list(
  region = region,
  dimensions = 600,
  crs = 'EPSG:3857',
  framesPerSecond = 10
)

Render the GIF animation in the console.

print(rgbVis$getVideoThumbURL(gifParams))
browseURL(rgbVis$getVideoThumbURL(gifParams))

How does rgee work?

rgee is not a native Earth Engine API like the Javascript or Python client, to do this would be extremely hard, especially considering that the API is in active development. So, how is it possible to run Earth Engine using R? the answer is reticulate. reticulate is an R package designed to allow a seamless interoperability between R and Python. When an Earth Engine request is created in R, reticulate will transform this piece of code to Python. Once the Python code is obtained, the Earth Engine Python API transform the request to a JSON format. Finally, the query (in JSON) is received by the Google Earth Engine Platform thanks to a Web REST API. The response will follow the same path. If you are searching a way to interact with the Earth Engine Asset (EEA), rgee offers also functions to batch upload(download) spatial objects. Additionally, you could easily manage EEA through the ee_manage_* interface.

Code of Conduct

Please note that the rgee project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Contributing Guide

👍🎉 First off, thanks for taking the time to contribute! 🎉👍 Please review our Contributing Guide.

Share the love ❤️

Think rgee is useful? Let others discover it, by telling them in per on, via Twitter or a blog post.

Using rgee for a paper you are writing? Consider citing it

citation("rgee")
#> 
#> WORKING ON THIS :)

Credits 🙇

Most of the rgee functionalities were based in the following third-party R/Python packages:

• gee_asset_manager - Lukasz Tracewski
• geeup - Samapriya Roy
• geeadd - Samapriya Roy
• cartoee - Kel Markert
• geetools - Rodrigo E. Principe
• landsat-extract-gee - Loïc Dutrieux
• earthEngineGrabR - JesJehle
• sf - Edzer Pebesma
• stars - Edzer Pebesma
• gdalcubes - Marius Appel

Readme template obtained from dbparser