search

JesJehle / earthEngineGrabR

Simplify the acquisition of remote sensing data
https://jesjehle.github.io/earthEngineGrabR/
53 stars 5 forks source link

readme

earthEngineGrabR

[![Coverage status](https://codecov.io/gh/JesJehle/earthEngineGrabR/branch/master/graph/badge.svg)](https://codecov.io/github/JesJehle/earthEngineGrabR?branch=master)

!!!Change in the Package due to the shut down of the Fusion Table service!!!

On December 3, Google, unfortunately, shot down the Fusion Table service, which was used by the earthEngineGrabR to upload vector data from R to GEE. Since, there is no free alternative service, a major change in package workflow was required. I used the issue to further simplify the package.

The changes are:

Although these changes are more tedious for the application, they allow a simplified and hopefully more stable installation and usage. I tried to reduce the package to its core functionalities - grab data from google earth engine in a user-defined aggregation process.

The new earthEngineGrabR Workflow

Search for data

Use Earth Engine's Data Catalog to browse and find datasets you want to grab using the earthEngineGrabR. Once you have found a dataset, use the snippet section to obtain the dataset ID and whether the dataset is an image or a collection of images. The snippet section consists of one line of code (don't open the link) and shows how Earth Engine loads the dataset. If it is an image, the ee.Image(dataset-ID) constructor is used. if it is a collection the ee.ImageCollection(dataset-id) constructor is used instead.

Upload

Use the Asset Manager of the EE code editor to manually upload your target area. After a successful upload copy the Asset ID, which is simply the asset path on EE

Grab data

ee_grab() requests data from Earth Engine to your local machine. ee_grab() takes three arguments, data, targetAreaAssetPath and download_path. data takes a either a ee_data_image() or a ee_data_collection() functions, which define the requested data to ee_grab(). If the requested data is an image use ee_data_image(), if it's a collection use ee_data_collection(). targetAreaAssetPath takes the Asset ID of the uploaded target area, which defines the spatial target in which the data sould be aggregated. download_path specifies a path on your maschine where the requested data from EE is downloaded.

The Google Earth Engine (GEE) is a cloud computing platform, which offers a multi-petabyte catalog of satellite images and manipulated geospatial data products. It also provides extensive computational resources — available for scientists and developers.

The earthEngineGrabR is an interface between R and the GEE, which simplifies the acquisition of remote sensing data. The R package extracts data from the Earth Engine Data Catalog in a user-defined target area and a user-defined aggregation process. All extractions and manipulations of the data are entirely outsourced to EE. As such, the package makes the massive public data catalog available to R-users with minimal technical and computational effort.

Usage

The example shows how to grab the yearly precipitation sum from the CHIRPS Daily dataset for a shapefile of spatial polygons, in this case, some ecosystems in Africa. To extract data from the EE Data Catalog the earthEngineGrabR uses ee_grab(). The ee_grab() function grabs data from the CHIRPS Daily dataset according to the target area defined by the feature geometries of the territories shapefile and an aggregation process defined by ee_data_collection().

First, upload the territories to EE by using the Asset Manager of the EE code editor. The path to the territories can be found by running system.file("data/territories.shp", package = "earthEngineGrabR") in R. Next, request the dataset with the earthEngineGrabR

library(earthEngineGrabR)
library(sf)

ee_grab(data = ee_data_collection(datasetID = "UCSB-CHG/CHIRPS/DAILY",
 spatialReducer = "mean",
 temporalReducer = "sum", 
 timeStart = "2016-01-01",
 timeEnd = "2016-12-31", 
 resolution = 200
 ),
 targetAreaAssetPath = "users/JesJehle/territories", # Use your username instead
 download_path = getwd()
 )

# read in the downloaded data with your favorit geo library 
chirps_data <- st_read('territories.geojson')
chirps_data

Simple feature collection with 53 features and 3 fields
geometry type: MULTIPOLYGON
dimension: XY
bbox: xmin: -13.71389 ymin: -25.52952 xmax: 43.10118 ymax: 16.63924
epsg (SRID): 4326
proj4string: +proj=longlat +datum=WGS84 +no_defs
First 10 features:
 id area_sqkm precipitation_s.mean_t.sum_2016.01.01_to_2016.12.31 geometry
1 40 32356 500.2795 MULTIPOLYGON (((37.76223 0....
2 29 42612 914.9900 MULTIPOLYGON (((36.58819 -1...
3 12 47000 1321.1984 MULTIPOLYGON (((37.10833 -7...
4 9 19624 572.1886 MULTIPOLYGON (((31.87845 -2...

The example calculates the yearly precipitation sum for 2016 and aggregates the spatial mean in the polygons of the target area. The calculations are performed on a resolution of 200 meters per pixel.

After a short processing time of approximately 1 -2 minutes, ee_grab() returns the data.

Requirements

The earthEngineGrabR R package has a few dependencies and requirements, which need to be satisfied before the installation can run successfully:

Required accounts

Required dependencies

Install the development version of the earthEngineGrabR:

library(devtools)
install_github("JesJehle/earthEngineGrabR")
library(earthEngineGrabR)

Installation

The package has additional Python dependencies and connects to several API’s, which each require an individual, user-specific, authentication procedure.

To simplify the installation and authentication process, the earthEngineGrabR includes a function ee_grab_install() that installs Python dependencies and guides the user through the different authentications.

Before using the earthEngineGrabR for the first time, run ee_grab_install() (you only have to do this once)

ee_grab_install()

Authentication

The earthEngineGrabR connects to 3 Google API's:

Changelog

20-01-24

2019-12-09

2019-09-05