README.Rmd

---
title: 'targets-rgee-extract'
output: 
  github_document:
    toc: true
---


```{r include=FALSE}
knitr::opts_chunk$set(
	fig.path = "man/figures/"
)

library(targets)
library(sf)
```

## Goal

Learning Earth Engine (though I highly recommend it), can be a bit of overhead
if you just need to, for example, sample a land cover product for a 
collection of points. Great packages like `sf` and `terra` exist in the 
R ecosystem for sampling from rasters, but Earth Engine (and its user community) 
offers an incredible resource of data sets (see below) that can be accessed
without downloading any large files to your local machine. 
With that in mind, this project combines `targets` and
`rgee` with a couple simple helper functions, to make simple operations
with Earth Engine easier. We won't cover anywhere near the full potential
of Earth Engine, just things like sampling images or image collections with
different types of features (for now). 

Working with Earth Engine through the Python package (or through `rgee` which
also goes through the Python package via `reticulate`) has one main challenge 
compared to the JavaScript API for Earth Engine: setup. See below for steps that
worked for me. You'll first need to install system dependencies, 
then install some R packages and authenticate with Earth Engine. 
`renv` is used to track required R and Python packages. 

Open an issue, submit a PR, or otherwise get in touch if you have any
thoughts or would like to contribute. Thanks!


## Usage

This repository is a [template repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template), so you can select "Use this template"
to start a new project quickly with the setup and example targets workflow.

![](https://docs.github.com/assets/cb-100333/images/help/repository/use-this-template-button.png)

Then see the [Setup](#setup) section below for installing system and R 
dependencies. 



## Neat data sets

TODO

- https://developers.google.com/earth-engine/datasets/
- https://samapriya.github.io/awesome-gee-community-datasets/


## Outputs
### Sample image with polygons

For example, extract the maximum elevation in each polygon ("elevation"):

```{r}
tar_load(sample_image_with_polys)
head(sample_image_with_polys)
plot(sample_image_with_polys)
```



### Sample image with points

For example, extract the leading tree species at each point ("b1"):

```{r}
tar_load(sample_image_with_points)
head(sample_image_with_points)
plot(sample_image_with_points['b1'])
```



### Sample image collections with polygons

For example, extract the monthly water detection within polygons (2 = water, 1 = land)

```{r}
tar_load(sample_image_collection_with_polygons)
head(sample_image_collection_with_polygons)
plot(sample_image_collection_with_polygons)
```



### Sample image collections with points

For example, Landsat 8 bands at each point: 

```{r}
tar_load(sample_image_collection_with_points)
head(sample_image_collection_with_points)
plot(sample_image_collection_with_points)
```

Note - these are spread wide, where each measure is a new column. That
means they will likely need to be restructured for further processing. 



## Setup

System dependencies:

- gcloud (https://cloud.google.com/sdk/docs/install)
- python >= 3.5
- earthengine python package


First time using this project:

```{r, eval = FALSE}
Sys.setenv(DOWNLOAD_STATIC_LIBV8 = 1)
install.packages('renv')
renv::restore()
rgee::ee_Authenticate()
rgee::ee_Initialize(drive = TRUE)
```



### Dependencies

System dependencies above. 

Details for `rgee` here: https://r-spatial.github.io/rgee/articles/rgee01.html#installation



#### `rgee` 

The "first time" section above should get you set up, but if you are starting from scratch: 


Install:

```{r, eval = FALSE}
library(rgee)
ee_install(py_env = 'rgee')
```


Authenticate:

```{r, eval = FALSE}
ee_Initialize()
```


Check:

```{r, eval = FALSE}
ee_check()
```


Renv + python:

```{r, eval = FALSE}
renv::use_python(reticulate::py_discover_config()$python)
renv::snapshot()
```


## Resources

- `rgee`
	- https://csaybar.github.io/rgee-examples/