In r-tidy-remote-sensing/tidyrgee: 'tidyverse' Methods for 'Earth Engine'

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

tidyrgee

tidyrgee brings components of dplyr's syntax to remote sensing analysis, using the rgee package.

rgee is an R-API for the Google Earth Engine (GEE) which provides R support to the methods/functions available in the JavaScript code editor and python API. The rgee syntax was written to be very similar to the GEE Javascript/python. However, this syntax can feel unnatural and difficult at times especially to users with less experience in GEE. Simple concepts that are easy express verbally can be cumbersome even to advanced users (see Syntax Comparison). The tidyverse has provided principals and concepts that help data scientists/R-users efficiently write and communicate there code in a clear and concise manner. tidyrgee aims to bring these principals to GEE-remote sensing analyses.

tidyrgee provides the convenience of pipe-able dplyr style methods such as filter, group_by, summarise, select,mutate,etc. using rlang's style of non-standard evaluation (NSE)

try it out!

Installation

Install from CRAN with:

install.packages("tidyrgee")

You can install the development version of tidyrgee from GitHub with:

# install.packages("devtools")
devtools::install_github("r-tidy-remote-sensing/tidyrgee")

It is important to note that to use tidyrgee you must be signed up for a GEE developer account. Additionally you must install the rgee package following there installation and setup instructions here

Syntax Comparison

Below is a quick example demonstrating the simplified syntax. Note that the rgee syntax is very similar to the syntax in the Javascript code editor. In this example I want to simply calculate mean monthly NDVI (per pixel) for every year from 2000-2015. This is clearly a fairly simple analysis to verbalize/conceptualize. Yet, using using standard GEE conventions, the process is not so simple. Aside, from many peculiarities such as flattening a list and then calling and then rebuilding the imageCollection at the end, I also have to write and think about a double mapping statement using months and years (sort of like a double for-loop). By comparison the tidyrgee syntax removes the complexity and allows me to write the code in a more human readable/interpretable format.

rgee (similar to Javascript)	tidyrgee
wzxhzdk:3	wzxhzdk:4

Example usage

Below are a couple examples showing some of the available functions.

To load images/imageCollections you follow the standard approach using rgee:

• load libraries
• initialize the GEE session
• load ee$ImageCollection/ ee$Image

library(tidyrgee)
library(rgee)
ee_Initialize(quiet = T)

modis_ic <- ee$ImageCollection("MODIS/006/MOD13Q1")

Once the above steps are performed you can convert the ee$ImageCollection to a tidyee object with the function as_tidyee. The tidyee object stores the original ee$ImageCollection as ee_ob (for earth engine object) and produces as virtual table/data.frame stored as vrt. This vrt not only facilitates the use of dplyr/tidyverse methods, but also allows the user to better view the data stored in the accompanying imageCollection. The ee_ob and vrt inside the tidyee object are linked, any function applied to the tidyee object will apply to them both so that they remain in sync.

modis_tidy <-  as_tidyee(modis_ic)

the vrt comes with a few built in columns which you can use off the bat for filtering and grouping, but you can also mutate additional info for filtering and grouping (i.e using lubridate to create new temporal groupings)

knitr::kable(modis_tidy$vrt |> head())

Next we demonstrate filtering by date, month, and year. The vrt and ee_ob are always filtered together

• by date

modis_tidy   |> 
  filter(date>="2021-06-01")

• by year

modis_tidy   |> 
  filter(year%in% 2010:2011)

• by month

modis_tidy   |> 
  filter(month%in% c(7,8))

Putting a dplyr-like chain together:

In this next example we pipe together multiple functions (select, filter, group_by, summarise) to

1. select the NDVI band from the ImageCollection
2. filter the imageCollection to a desired date range
3. group the filtered ImageCollection by month
4. summarizing each pixel by year and month.

The result will be an ImageCollection with the one Image per month (12 images) where each pixel in each image represents the average NDVI value for that month calculated using monthly data from 2000 2015.

modis_tidy |> 
  select("NDVI") |> 
  filter(year %in% 2000:2015) |> 
  group_by(month) |> 
  summarise(stat= "mean")

You can easily group_by more than 1 property to calculate different summary stats. Below we

1. filter to only data from 2021-2022
2. group by year, month and calculate the median NDVI pixel value

As we are using the MODIS 16-day composite we summarising approximately 2 images per month to create median composite image fo reach month in the specified years. The vrt holds a list-col containing all the dates summarised per new composite image.

modis_tidy |> 
  select("NDVI") |> 
  filter(year %in% 2021:2022) |> 
  group_by(year,month) |> 
  summarise(stat= "median")

To improve interoperability with rgee we have included the as_ee function to return the tidyee object back to rgee classes when necessary

modis_ic <- modis_tidy |> as_ee()

r-tidy-remote-sensing/tidyrgee documentation built on April 9, 2023, 4:53 p.m.