Getting Started with mapping flow

Basic run

First load the LITAP package:

library(LITAP)

## LITAP v0.7.0
## LITAP is still in development; Help us by submitting bugs/feature requests: 
## http://github.com/FRDC-SHL/LITAP/issues

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

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.

flow_mapper(file = "testELEV.dbf", nrow = 90, ncol = 90, grid = 5)

## CALCULATING DIRECTIONS

## CALCULATING WATERSHEDS

## REMOVING INITIAL PITS

## CALCULATING POND (GLOBAL) WATERSHEDS

## CALCULATING FILL PATTERNS

## INVERTING DEM

## CALCULATING INVERTED DIRECTIONS

## CALCULATING INVERTED WATERSHEDS

## REMOVING INVERTED PITS

## CREATING REPORT

## Run took: 0.31 min

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

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

## CALCULATING DIRECTIONS

## CALCULATING WATERSHEDS

## REMOVING INITIAL PITS

## CALCULATING POND (GLOBAL) WATERSHEDS

## CALCULATING FILL PATTERNS

## INVERTING DEM

## CALCULATING INVERTED DIRECTIONS

## CALCULATING INVERTED WATERSHEDS

## REMOVING INVERTED PITS

## CREATING REPORT

## Run took: 0.25 min

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.

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

## CALCULATING DIRECTIONS

## CALCULATING WATERSHEDS

## REMOVING INITIAL PITS

## CALCULATING POND (GLOBAL) WATERSHEDS

## CALCULATING FILL PATTERNS

## INVERTING DEM

## CALCULATING INVERTED DIRECTIONS

## CALCULATING INVERTED WATERSHEDS

## REMOVING INVERTED PITS

## CREATING REPORT

## Run took: 0.24 min

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!

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

## CALCULATING DIRECTIONS

## CALCULATING WATERSHEDS

## REMOVING INITIAL PITS

## CALCULATING POND (GLOBAL) WATERSHEDS

## CALCULATING FILL PATTERNS

## INVERTING DEM

## CALCULATING INVERTED DIRECTIONS

## CALCULATING INVERTED WATERSHEDS

## REMOVING INVERTED PITS

## CREATING REPORT

## Run took: 0.24 min

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:

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):

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

## CALCULATING DIRECTIONS

## CALCULATING WATERSHEDS

## REMOVING INITIAL PITS

## CALCULATING POND (GLOBAL) WATERSHEDS

## CALCULATING FILL PATTERNS

## INVERTING DEM

## CALCULATING INVERTED DIRECTIONS

## CALCULATING INVERTED WATERSHEDS

## REMOVING INVERTED PITS

## CREATING REPORT

## Run took: 0.07 min

Output messages

To include detailed output, use verbose = TRUE:

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

##   Using supplied 90 rows and 90 columns

##   Adding buffer

##   Formating grid

##   No x/y in file, creating x/y from cols/rows/grid

## CALCULATING DIRECTIONS

##      - Fixing flat plateaus round 1...

## CALCULATING WATERSHEDS

##   Getting upslope flow and cumulative elevation differences

##     Assessing pour points REMOVING INITIAL PITS
##     Assessing pour points     Combining watersheds 6 and 3
##     Assessing pour points     Combining watersheds 1 and 4
##     Assessing pour points     Combining watersheds 4 and 8
##     Assessing pour points 
## 
##     Calculating upslope cumulative elevation drop
##     Assessing pour points CALCULATING POND (GLOBAL) WATERSHEDS
##     Assessing pour points   Current pit: 8
##     Pit 1: 8
##     Pit 2: 9
##     Lowest pit: 8
##   Watersheds 8 and 9 are FINAL sheds
##   Current pit: 10
##     Pit 1: 10
##     Pit 2: 2
##     Lowest pit: 10
##   Watersheds 10 and 2 are FINAL sheds
##   Current pit: 7
##     Pit 1: 7
##     Pit 2: 9
##     Pit 2 already FINAL pit
##     Lowest pit: 7
##   Watersheds 7 and 9 are FINAL sheds
##   Current pit: 3
##     Pit 1: 3
##     Pit 2: 8
##     Pit 2 already FINAL pit
##     Lowest pit: 3
##   Combining sheds 3 and 8 into new shed 11
##     Assessing pour points   Current pit: 11
##     Pit 1: 11
##     Pit 2: 9
##     Pit 2 already FINAL pit
##     Lowest pit: 11
##   Watersheds 11 and 9 are FINAL sheds
##   Current pit: 5
##     Pit 1: 5
##     Pit 2: 11
##     Pit 2 already FINAL pit
##     Lowest pit: 5
##   Watersheds 5 and 11 are FINAL sheds
## 
## 
## CALCULATING FILL PATTERNS
##     Assessing pour points   Combining sheds 3 and 8 to new shed 11
##     Assessing pour points 
## 
##     Calculating new elevation differences
## INVERTING DEM
## CALCULATING INVERTED DIRECTIONS
##      - Fixing flat plateaus round 1...
##      - Fixing flat plateaus round 2...
##      - Fixing flat plateaus round 3...
##      - Fixing flat plateaus round 4...
## CALCULATING INVERTED WATERSHEDS
##   Getting upslope flow and cumulative elevation differences
##     Assessing pour points REMOVING INVERTED PITS
##     Assessing pour points     Combining watersheds 1 and 3
##     Assessing pour points     Combining watersheds 8 and 2
##     Assessing pour points     Combining watersheds 6 and 4
##     Assessing pour points     Combining watersheds 3 and 4
##     Assessing pour points 
## 
##     Calculating upslope cumulative elevation drop
##     Assessing pour points CREATING REPORT
## Run took: 0.24 min

To prevent all output, use quiet = TRUE:

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:

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.

Calculating Directions (directions) Calculating the flow direction of each cell into a neighbouring cell
Calculating Watersheds (watersheds) From the flow directions, combine cells into initial watersheds
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.
Calculating Pond Shed Statistics Second Pit Removal) (pond) Calculate how pits would overflow into each other
Calculating Fill Shed Statistics (Third Pit Removal) (fill)
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
Calculating Inverted Watersheds (iwatersheds) From the flow directions, combine cells into initial watersheds
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.