---
title: "Running the tool in Interactive Mode: the MODIStsp GUI"
bibliography: MODIStsp.bib
output: 
  github_document: default
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(DT)
```

The easiest way to use `{MODIStsp}` is to use its powerful GUI (Graphical User Interface) 
for selection of processing options, and then run the processing. 

To open the GUI, load the package and launch the `{MODIStsp}` function, with no parameters:
```{r, eval=FALSE, message=FALSE, warning=FALSE, include=TRUE, caption=FALSE}
library(MODIStsp)
MODIStsp()
```
This **opens a GUI** from which processing options can be specified and eventually 
saved (or loaded from a previously saved file). 

The  GUI allows selecting all processing options required for the creation of the 
desired MODIS time series. The GUI uses a dashboard structure, divided in the 
following tabs. The available processing options configurable in each tab are described 
in the following.

____________________________________________________________________________________


# <i class="fa fa-arrow-circle-o-right" aria-hidden="true"></i> __Selecting Processing Parameters__

<br>

## _Product and Layers Tab_


```{r GUIfig, echo=FALSE, fig.align="center", fig.width=10, message=FALSE, warning=FALSE}
  library(png)
  library(grid)
  library(knitr)
  img <- readPNG("GUI_1.PNG")
  grid.raster(img)
```

The top-most tab allow to specify details of the desired MODIS Product and Layers
to be processed:

1. **"Category"** and **"Product"**: selects the MODIS product of interest;
2. **MODIS platform(s)**: selects if only TERRA, only AQUA or Both MODIS platforms 
should be considered for download and creation of the time series;
3. **MODIS layers to be processed**: the user **must** 
select which MODIS original layers and/or derived Quality Indexes (QI) and Spectral
Indexes (SI) layers should be processed: 
    - the left-hand selector allows to select which _original MODIS layers_ 
        should be processed;
    - the central selector allows to select which _Quality Indicators should be extracted_ 
        from the original MODIS Quality Assurance layers;
    - for MODIS products containing surface reflectance data, the right-hand selector 
        allows selecting which additional _Spectral Indexes should be computed_. 

The following commonly used Spectral Indexes are available for computation by default: 

<br>

```{r xtable, echo=FALSE, paged.print=TRUE, results="asis"}
# library(xtable)
tab <- tibble::tribble(
 ~"Acronym"     ,~"Index Name and reference", ~"Index Formula",                     
 "NDVI"         , "Normalized Difference Vegetation Index (Rouse, 1973)"          , "(NIR - RED)/(NIR + RED)",        
 "EVI"          , "Enhanced Vegetation Index (Huete, 2002)"                       , "2.5 * (NIR - RED)/(NIR + 6 * RED - 7.5 * BLUE + 1",
 "SR"           , "Simple Ratio[@Tucker1979]"                                    , "NIR / RED",
 "NDFI"         , "Normalized Difference Flood Index (Boschetti, 2014)"           , "(NIR - SWIR1) / (NIR + SWIR1)", 
 "NDII6 (NDWI6)" , "Normalized Difference Infrared Index - Band 6 (Hunt, 1989)" , "(NIR - SWIR1) / (NIR + SWIR1)",
 "NDII7 (NDWI7)" , "Normalized Difference Infrared Index - Band 7 (Hunt, 1989)" , "(NIR - SWIR2) / (NIR + SWIR2)",
 "SAVI"         , "Soil Adjusted Vegetation Index  (Huete, 1988)"                 , "((NIR - RED) / (NIR + RED + 0.5)) * (1 + 0.5)",
 "NDSI"         , "Normalized Difference Snow Index (Hall, 2002)"                 , "(GREEN - SWIR1) / GREEN + SWIR1)",
 "GNDVI"        , "Green Normalized Difference Vegetation Index (Gitelson, 1998)" ,  "(NIR - GREEN)/(NIR + GREEN)",       
 "RGRI"         , "Red Green Ratio Index (Gamon, 1999)"                          , "RED / GREEN",
 "GRVI"         , "Green-Red ratio Vegetation Index  (Tucker, 1979)"              , "(RED - GREEN) / (RED + GREEN)"       
)

DT::datatable(tab, rownames = FALSE, style = "bootstrap", 
              options = list(dom = 'tip', pageLength = 11))
```

You can however **specify other SIs to be computed without modifying MODIStsp source code** 
by clicking on the _**"Add New Spectral Index"**_ button, which allow providing info related 
to the new desired SI using a simple GUI interface. 

```{r indexfig, echo=FALSE, message=FALSE, fig.width=6, warning=FALSE, fig.align="center"}
  library(png)
  library(grid)
  img <- readPNG('GUI_newind.PNG')
  grid.raster(img)
```

Provided information (e.g., correct band-names, computable formula, etc...) is 
automatically checked upon clicking "Set New Index". On success, the new index 
is added in the list of available ones for all products allowing its computation. 
Clicking "Done!" returns to the main.

__Note:__ all custom defined indexes can be removed by using the `MODIStsp_resetindexes()` 
function.

## _Spatial/Temporal Options Tab_

The middle tab allow specifying details about the temporal and spatial extent of 
the analysis. 

```{r , echo=FALSE, message=FALSE, warning=FALSE, fig.width=10, fig.align="center"}
  library(png)
  library(grid)
  img <- readPNG('GUI_2_tiles.PNG')
  grid.raster(img)
```

### _Temporal Extent_

Specify the starting and ending dates to be considered for the creation of the 
time in the series corresponding fields. 

The **Date Range Type** drop-down menu allows to choose between two options:

1.  **full**: all available images between the starting and ending dates are 
downloaded and processed;

2.  **seasonal**: data is downloaded only for one part of the year, but for 
multiple years. For example, if the starting date is 2005-03-01 and the ending is
2010-06-01, only the images of March, April and May for the years between 2005
and 2010 will be downloaded. This allows to easily process data concerning a 
particular season of interest.

### _Output Projection_

Specify the options to be used for reprojecting and resizing the MODIS images. 

- **"Output Projection"**: select either the Native MODIS projection (Default) 
or specify a user-defined one. To specify a user selected projection, select 
"Change" and then insert a valid "EPSG" code or WKT string in the pop-up window. 
Validity of the new projection string is automatically checked, and error messages issued 
if the check fails.

- **"Output Resolution"**, **"Pixel Size"** and **"Resampling Method"**: specify 
whether output images should inherit their spatial resolution from the original
MODIS files, or be resampled to a user-defined resolution. In the latter case, 
output spatial resolution must be specified in the measure units of the selected
output projection. Resampling method can  be chosen among the ones available for
the "gdalwarp" routine. 
__Note:__ resampling methods different than Nearest Neighbour" and "Mode" (Useful for down-sampling purposes) should used carefully. Other resampling methods (e.g., 
bilinear, cubic) i) cannot be used for resampling of categorical variables such as the QA and QI layers, and ii) using them on continuous variable (e.g., reflectance, VI values) without performing an 
a-priori data cleaning would risk to contaminate the values of high-quality
observations with those of low-quality ones.

### _Spatial Extent_

Allows defining the area of interest for the processing. Four main options are
possible, and can be selected using a dropdown menu. 

1.  **Select Tiles**: specify which MODIS tiles need to be processed either 
by: 

    a. Using the "Start" and "End" horizontal and vertical sliders in the 
    _Required MODIS Tiles_ frame.  
    b. Selecting the __"From Map"__ option in the dropdown and clicking on "change selection". 
    A map will open, allowing interactive selection of the required tiles
    
Note that during processing, data from the different tiles is mosaicked, and a single file 
covering the total area is produced for each acquisition date. For this reason, 
selected tiles must cover a rectangular area. 

2.  **Select Bounding Box**: manually insert the coordinates of the Upper Left and Lower Right corners
    of the area of interest in the __Bounding Box__ frame. _Coordinates of the corners 
    must be provided in the coordinate system of the selected output projection_.

2.  **Load From File**: click the __"Browse"__ button and select a raster or vector 
    spatial file that will be used to compute the required bounding box in output
    projection coordinates.

4.  **Draw on Map**: click the __"Draw Extent"__ button a map will open in a  
    window, allowing interactive selection of the spatial extent using the tools
    on the left.

## _Output Format, Options and Folders Tab_

The last tab allows specifying some options concerning processing, and the output folders. 


```{r , echo=FALSE, message=FALSE, warning=FALSE, fig.width=10, fig.align="center"}
  library(png)
  library(grid)
  img <- readPNG('GUI_3.PNG')
  grid.raster(img)
```

### _Download Method_

Select the method to be used for download. Available choices are: 

1.  **http**: download through http from NASA lpdaac http archive (http://e4ftl01.cr.usgs.gov). 
This requires providing a user name and password, which can be obtained by registering 
an account at the address [https://urs.earthdata.nasa.gov/profile](https://urs.earthdata.nasa.gov/profile);

2.  **offline**: this option allows to process/reprocess HDF files already available 
on the user's PC without downloading from NASA -- useful if the user already has an
archive of HDF images, or to reprocess data already downloaded via `MODIStsp()` to create
time series for an additional layer (_it is fundamental that the HDFs are those 
directly downloaded from NASA servers_; see [here](https://docs.ropensci.org/MODIStsp/articles/faq.html#working-with-already-downloaded-hdf-files) 
for additional details). 

A second dropdown menu allows selecting if using standard http download to access
NASA servers, or using the **aria2c** downloader, which may speed-up the download. This requires however that that the "aria2c" software is installed in your system. To download and install it, see [aria2.github.io](https://aria2.github.io/).

### _Output Options_

Several processing options can be set using check-boxes/dropdowns:

- **Output Files Format**: two of the most commonly formats used in remote
sensing applications are available at the moment: ENVI binary and GeoTiff. If
GeoTiff is selected, the type of file compression can be also specified among
"None", "PACKBITS", "LZW" and "DEFLATE".

- **Save Time Series as**: specify if virtual multitemporal files should be 
created. These virtual files allow access to the entire time series of images as 
a single file without the need of creating large multitemporal raster images.
Available virtual files formats are "R" rasterStacks, ENVI meta-files and GDAL 
"vrt" files. In particular, `R` RasterStacks may be useful in order to easily 
access the preprocessed MODIS data within `R` scripts 
(see also [here](output.html)).

- **Apply Scale/Offset**: specify if scale and offset values of the different 
MODIS layers should be applied. If selected, outputs are appropriately rescaled
on the fly, and saved in the true "measure units" of the selected parameter (e.g., 
spectral indexes are saved as floating point values; Land Surface Temperature is 
saved in degrees Kelvin, etc.). 

- **Modify No Data Values**: specify if NoData values of MODIS layers should be kept
at their original values, or changed to those specified within the `MODIStsp_Products_Opts`
XML file. By selecting "Yes" in the "Change Original NoData values" check-box, 
NoData of outputs are set to the largest integer value possible for the data type 
of the processed layer (e.g., for 8-bit unsigned integer layers, NoData is set 
always to 255, for 16-bit signed  integer layers to 32767, and  for 16-bit unsigned
integer layers to 65535). Information about the new NoData values is stored both 
in the output rasters, and in the XML files associated with them. __Note:__ some 
MODIS layers have multiple NoData (a.k.a. _fill_) values. if _Modify No Data_ is 
set to "Yes", `MODIStsp()` will convert all _fill_ values to a common output NoData
value.

### _Output Folders_

#### _Main MODIStsp Output Folder_

Select the main folder where the pre-processed time series data will be stored. 
All `MODIStsp()` outputs **will be placed in specific sub-folders of this main folder** 
(see [here](output.html) for details on `MODIStsp` naming conventions).

The **"Reprocess"** selector allows to decide if images already 
available should be reprocessed if a new run of `MODIStsp()` is launched with the same 
output folder. If set to "No", `MODIStsp()` skips dates for which output files following
the `{MODIStsp}` naming conventions are already present in the output folder. This
allows to incrementally extend MODIS time series without reprocessing already available
dates. 

#### _Output Folder for storage of original MODIS HDF_

Select the folder where downloaded **original MODIS HDF files** downloaded from 
NASA servers will be stored. 

The **"delete HDF"** selector allows also to decide if the
downloaded images should be deleted from the file system at the end of the 
processing. To avoid accidental file deletion, this is always set to "No" by default, 
and a warning is issued before execution whenever the selection is changed to "Yes".

____________________________________________________________________________________

<br>

# <i class="fa fa-arrow-circle-o-right" aria-hidden="true"></i> __Saving and Loading Processing Options__


```{r , echo=FALSE, message=FALSE, warning=FALSE, fig.width=6, fig.align="center"}
  library(png)
  library(grid)
  img <- readPNG('GUI_bar.PNG')
  grid.raster(img)
```

Specified processing parameters can be saved to a JSON file for later use by clicking
on the _**Save Options**_ button in the sidebar.

Previously saved options can be restored clicking on the _**Load Options**_ button
and navigating to the previously saved JSON file.

____________________________________________________________________________________

<br>

# <i class="fa fa-arrow-circle-o-right" aria-hidden="true"></i> __Starting the processing__

Once you are happy with your choices, click on **Run MODIStsp**. `MODIStsp()` 
will start accessing NASA servers to download and process the MODIS data corresponding 
to your choices.

For each date of the specified time period, `MODIStp()` downloads and preprocesses
all HDF images required to cover the desired spatial extent. Informative messages
concerning the status of the processing are provided on the console, as well as on
a self-updating progress window. 

The processed time series are saved in specific subfolders of the main selected
output folder, as explained in detail [here](output.html).

________________________________________________________________________________
