---
title: "Introduction to rgee"
output:
  html_document:
    toc: true
    toc_float:
      collapsed: false
      smooth_scroll: false
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{1. Introduction}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}    
---


## **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**. 


```{r, setup, include=FALSE}
knitr::opts_chunk$set(
  comment = '', fig.width = 6, fig.height = 6
)
```


## **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](https://developers.google.com/earth-engine/datasets).

**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](https://earthengine.google.com/signup/)**. See **[Earth Engine official website](https://earthengine.google.com/)** to obtain more information.

<br>

<center>
  <iframe name="Stack" src="https://www.youtube.com/embed/gKGOeTFHnKY/" style='height: 450px; width: 80%;
  'frameborder="0" scrolling="no" id="iframe">
  </iframe>
</center>

## 5. Why rgee instead of code editor (Javascript)?

A short comparison based on **[Tyler Erickson presentation](https://docs.google.com/presentation/d/1MVVeyCdm-FrMVRPop6wB3iyd85TAlwB-F9ygTQZ8S1w/pub?slide=id.g1e419debf0_1_205/)**.

<center>
<table style="border-collapse:collapse;border-color:#ccc;border-spacing:0;border:none" class="tg"><thead><tr><th style="background-color:#f0f0f0;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;font-weight:bold;overflow:hidden;padding:10px 5px;text-align:center;vertical-align:top;word-break:normal">Code Editor</th><th style="background-color:#f0f0f0;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;font-weight:bold;overflow:hidden;padding:10px 5px;text-align:center;vertical-align:top;word-break:normal">R</th></tr></thead><tbody><tr><td style="background-color:#fff;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;overflow:hidden;padding:10px 5px;text-align:left;vertical-align:top;word-break:normal">Easy to get started</td><td style="background-color:#f9f9f9;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;overflow:hidden;padding:10px 5px;text-align:left;vertical-align:top;word-break:normal">Easy to share code between scripts.</td></tr><tr><td style="background-color:#fff;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;overflow:hidden;padding:10px 5px;text-align:left;vertical-align:top;word-break:normal">Trivial to share scripts</td><td style="background-color:#f9f9f9;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;overflow:hidden;padding:10px 5px;text-align:left;vertical-align:top;word-break:normal">Easier transition to a web application (<span style="font-weight:bold">Shiny</span>).</td></tr><tr><td style="background-color:#fff;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;overflow:hidden;padding:10px 5px;text-align:left;vertical-align:top;word-break:normal">Built in authentication</td><td style="background-color:#f9f9f9;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;overflow:hidden;padding:10px 5px;text-align:left;vertical-align:top;word-break:normal">An I/O API more friendly with R users.</td></tr><tr><td style="background-color:#fff;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;overflow:hidden;padding:10px 5px;text-align:left;vertical-align:top;word-break:normal"><span style="font-weight:bold;color:#FE0000">Limited input/output functionality</span></td><td style="background-color:#f9f9f9;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;overflow:hidden;padding:10px 5px;text-align:left;vertical-align:top;word-break:normal">Many, many plotting options</td></tr><tr><td style="background-color:#fff;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;overflow:hidden;padding:10px 5px;text-align:left;vertical-align:top;word-break:normal"><span style="font-weight:bold;color:#FE0000">Integration with other JS libraries is not possible</span></td><td style="background-color:#f9f9f9;border-color:inherit;border-style:solid;border-width:0px;color:#333;font-family:Arial, sans-serif;font-size:14px;overflow:hidden;padding:10px 5px;text-align:left;vertical-align:top;word-break:normal"><span style="font-weight:bold;color:#FE0000">Some assembly (&amp; maintenance) required!.</span></td></tr></tbody></table>
</center>

## 6. Installation

**rgee** depends on **[reticulate](https://cran.r-project.org/package=reticulate)**, **[R6](https://cran.r-project.org/package=R6)** and **[processx](https://cran.r-project.org/package=processx)**. To install **rgee** run:

Stable version:

```{r eval = FALSE}
install.packages("rgee")
```

Dev version:

```{r eval = FALSE}
remotes::install_github("r-spatial/rgee")
```

**rgee** has two types of dependencies: <span
style="color:#b52b09">**strict dependencies**</span> that must be
present before **rgee** initialization (i.e. **[ee_Initialize()](https://r-spatial.github.io/rgee/reference/ee_Initialize.html)**) and the <span style="color:#857e04"><b>credentials dependencies</b></span> 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:

  * <span style="color:#b52b09"><b> Google account with Earth Engine
    activated </b></span>
    
  * <span style="color:#b52b09"><b> Python >= v3.5 </b></span>

  * <span style="color:#b52b09"><b> EarthEngine Python API (Python package) </b></span>

The activation of an **Earth Engine account** depends on each user, check
the official website of [Google Earth Engine](https://earthengine.google.com/) for more details. If you do not have a Python environment or a version of the EarthEngine Python API, we strongly recommend you run:

```{r eval = FALSE}
library(rgee)
ee_install(py_env = "rgee") # It is just necessary once!
```

This function will perform the following six tasks:

  1. If you do not have a Python environment, it will display an
  interactive  menu to install [Miniconda](https://docs.conda.io/en/latest/miniconda.html)
  (a free minimal installer for conda).
  
  2. Remove the previous Python environment defined with the same name if it exists.
  
  3. Create a new Python environment.

  4. Set the environmental variables EARTHENGINE_PYTHON and EARTHENGINE_ENV. These variables
  will be used to define the reticulate environmental variable [RETICULATE_PYTHON](https://rstudio.github.io/reticulate/articles/versions.html#providing-hints) when 
  rgee is loaded. 
  
  5. Install rgee Python dependencies: [Earth Engine Python API](https://pypi.org/project/earthengine-api/) and
  [numpy](https://pypi.org/project/numpy/).
  
  6. 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**](https://github.com/r-spatial/rgee/tree/help/rstudio/) 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](https://pypi.org/project/earthengine-api/) and [Numpy](https://pypi.org/project/numpy/).

On the other hand, the <span style="color:#857e04"><b>credentials dependencies</b></span>
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:

  -   <span style="color:#857e04">**Google Cloud Storage
      credential**</span>
      
  -   <span style="color:#857e04">**Google Drive credential**</span>

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:

```{r eval = FALSE}
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](https://code.markedmondson.me/googleCloudStorageR/articles/googleCloudStorageR.html) and [link2](https://github.com/r-spatial/rgee/tree/help/gcs/)). In all cases, the user's credentials will be stored in: 

``` {r eval = FALSE}
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!

```{r eval = FALSE}
library(rgee)
ee_Initialize()
srtm <- ee$Image("USGS/SRTMGL1_003")
```

**Define visualization parameters**

```{r}
viz <- list(
  max = 4000,
  min = 0,
  palette = c("#000000","#5AAD5A","#A9AD84","#FFFFFF")
)
```

**Use Map$addLayer to visualize the map interactively**

```{r eval=FALSE}
Map$addLayer(
  eeObject = srtm,
  visParams =  viz,
  name = 'SRTM',
  legend = TRUE
)
```

<center>
<img src="images/r1_01.png" width="90%">
</center>

## 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

``` r
library(rgee)
ee_check()

ee_check_python()
ee_check_credentials()
ee_check_python_packages()
```