---
title: "Getting Started with mapping flow"
author: "Steffi LaZerte"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with mapping flow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
# rmarkdown::pdf_document
# rmarkdown::html_vignette
knitr::opts_chunk$set(fig.width = 15, fig.height = 10, eval = TRUE)
file.copy(system.file("extdata", "testELEV.dbf", package = "LITAP"), ".", 
          overwrite = TRUE)
```

<style>
.figure {
  max-width: 100%;
  margin: auto;
}
.table {
  width: auto;
  margin: auto;
}
</style>

## Basic run

First load the LITAP package:
  
```{r}
library(LITAP)
```


Here we will use the "testELEV.dbf" included in the package. You can copy it to your working directory with:

```{r, eval = FALSE}
file.copy(system.file("extdata", "testELEV.dbf", package = "LITAP"), ".")
```

The only required parameters are the location of the dem file (`file`) and the number of rows and the number of columns (`nrow` and `ncol`) in the dem file.

```{r}
flow_mapper(file = "testELEV.dbf", nrow = 90, ncol = 90, grid = 5)
```

## Pit removal parameters

The maximum size of initial watersheds which will be removed in the first step can also be specified:

- `max_area` represents the maximum pit area (area of a watershed below it's pour point) of a watershed to be removed in the initial step
- `max_depth` represents the maximum depth of a pit (difference between the elevation of the pour point and the elevation of the pit centre) of a watershed to be removed in the initial step

```{r}
flow_mapper(file = "testELEV.dbf", nrow = 90, ncol = 90, grid = 5,
            max_area = 5, max_depth = 0.2)
```

## Output folders

A LITAP run saves all output from `flow_mapper()` into folder `flow`.  

- `flow` folder contains .csv or .rds files of the output (depending on the output format specified), similar to that produced by the LandMapR program but designed for ease of use in R.

You can specify where these output folders/files should be saved with `out_folder`. Otherwise the folders will be created in the folder of the original Elev.dbf file, which may not be desirable.

```{r}
flow_mapper(file = "testELEV.dbf", nrow = 90, ncol = 90, grid = 5, 
            out_folder = "./LITAP runs/")
```

Ideally, it's best to create an RStudio project, put the original Elev.dbf file in this project and work from there. Note that folder locations are relative to working directory of the R session.


To clean up any old files before conducting a new run, use `clean = TRUE`. __Careful, this will remove all backup files from previous runs making it impossible to resume a run!__

```{r}
flow_mapper(file = "testELEV.dbf", nrow = 90, ncol = 90, grid = 5,
            out_folder = "./LITAP runs/", clean = TRUE)
```

## Different input file types

You can use a variety of input file types, provided they fit the format specifications defined in `load_file()` (`?load_file` for more details). Among others, the following file types are accepted:

```{r, eval = FALSE}
flow_mapper(file = "testELEV.grd") # Grid files
flow_mapper(file = "testELEV.csv") # CSV files
flow_mapper(file = "testELEV.asc") # Ascii Grid files
flow_mapper(file = "testELEV.flt") # Floating point raster files
flow_mapper(file = "testELEV")     # ArcGis Gridfile folder (contains .hdr files)
```


## Subset of input dem

To conduct a run on only a subset of the dem you can specify row and column limits (`rlim` and `clim` respectively):

```{r}
flow_mapper(file = "testELEV.dbf", nrow = 90, ncol = 90, grid = 5,
            rlim = c(50,80), clim = c(50,80))
```

## Output messages

To include detailed output, use `verbose = TRUE`:

```{r}
flow_mapper(file = "testELEV.dbf", nrow = 90, ncol = 90, grid = 5, verbose = TRUE)
```

To prevent all output, use `quiet = TRUE`:

```{r}
flow_mapper(file = "testELEV.dbf", nrow = 90, ncol = 90, grid = 5, quiet = TRUE)
```

## Resuming a run
Each run of LITAP goes through numerous steps. If there's a problem, a run can be resumed at step by specifying the corresponding variable.

For example, to resume with calculating pond statistics and continue to the end of the run:

```{r, eval = FALSE}
flow_mapper(file = "testELEV.dbf", nrow = 90, ncol = 90, grid = 5,
            resume = "pond")
```

Note that if a run finishes, you won't be able to resume that run from a previous step, as intermediate files are removed.
If you want this ability, use the argument `debug = TRUE`.

## Steps

The variable in brackets defines the argument to use for continuing and ending a run.

1. __Calculating Directions__ (`directions`)
Calculating the flow direction of each cell into a neighbouring cell 

2. __Calculating Watersheds__ (`watersheds`)
From the flow directions, combine cells into initial watersheds

3. __Initial Pit Removal__ (`local`)
Remove pits which are smaller than the maximum area and depth (and which are not edge pits). These pits are removed into neighbouring pits.

4. __Calculating Pond Shed Statistics Second Pit Removal)__ (`pond`)
Calculate how pits would overflow into each other

5. __Calculating Fill Shed Statistics (Third Pit Removal)__ (`fill`)

6. __Calculating Directions on Inverted DEM__ (`idirections`)
Reverse the elevations of the original DEM file. This will make all troughs into peaks, etc. Then calculate the flow direction of each cell into a neighbouring cell. Because the DEM is inverted, this will track upslope flow

7. __Calculating Inverted Watersheds__ (`iwatersheds`)
From the flow directions, combine cells into initial watersheds

8. __Initial Inverted Pit Removal__ (`ilocal`)
Remove pits which are smaller than the maximum area and depth (and which are not edge pits). These pits are removed into neighbouring pits. Calculate watershed statistics on these resulting local pits. Because the DEM is inverted, this will highlight peaks and flow down from these peaks.


```{r, include = FALSE}
unlink("./testELEV.dbf")
unlink("./testELEV/", recursive = TRUE)
unlink("./LITAP runs/", recursive = TRUE)
```