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

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

```{r, include = FALSE}
library(dplyr)
library(gt)
library(glue)
library(stringr)

knitr::opts_chunk$set(echo = FALSE)

litap_style <- function(gt) {
  gt %>%
    cols_label("param" = "LITAP Parameters",
               "desc" = "Description",
               "landmapr" = "LandMapR Name") %>%
    cols_move_to_end("desc") %>%
    text_transform(locations = cells_body(columns = "param"),
                   fn = function(x) paste0("<code>", x, "</code>")) %>%
    tab_style(location = cells_column_labels(), style = cell_text(weight = "bold")) %>%
    cols_align(align = "left", columns = "desc") %>%
    sub_missing(columns = "landmapr", missing_text = "--") %>%
    opt_footnote_marks(marks = "standard")
}

check_missing <- function(f, all, type) {
  if(length(names(f)[!names(f) %in% all$param]) > 0) {
    stop(type, " - Missing parameters: ", 
         paste0(names(f)[!names(f) %in% all$param], collapse = "; "), 
         call. = FALSE)
  }
}

all <- tibble()

```



Functions in LITAP output a lot of variables, many of which are based on the original LandMapR<sup>*</sup> program, but including new ones as well. This resource is meant to explain what the various parameters mean, which files they can be found in, and whether they were included in the original LandMapR program (and under what name).

<sup>*</sup> Interpretations of LandMapR variables are derived from the
[LandMapR C++ User Manual, October 2003](https://www.researchgate.net/publication/301726747_LandMapR_Software_Toolkit-_C_Version_2003_User's_Manual).
If you want a better understanding of these variables and their calculations it
is **highly** recommended that you explore the manual and the references
therein.

<!-- LandmapR/Original EXTRA/Documentation/Users_Manual/LandMapR_C++_User_Manual.pdf -->

## Generic variables

These variables are common to many files in LITAP and so for the sake of brevity, will be defined here.


### Generic DEM file variables {#generic-dem}

These variables correspond to dem files, meaning there is a value for each cell 
in the dem file. 

```{r generic, message = FALSE}
p <- tribble(
  ~param, ~desc, ~landmapr,
  "seqno",      "Cell number identifying a particular cell in the DEM", "SeqNo",
  "x",          "The horizontal (longitudinal) measure of position in the units of the original dem (or metres, if not supplied)", "--",
  "y",          "The vertical (latitudinal) measure of position in the units of the original dem (or metres, if not supplied)", "--",
  "row",        "Row number",  "Row",
  "col",        "Column number", "Col",
  "elev",       "Elevation in metres", "Elev",
  "ddir",       "Direction of water flow (1 = SW, 2 = S, 3 = SE, 4 = W, 5 = No flow, 6 = E, 7 = NW, 8 = N, 9 = NE)", "Ddir",
  "drec",       "The cell number (`seqno`) of the cell this focal cell flows into", "Drec",
  "upslope",    "The number of cells which flow into and/or through the focal cell", "UpSlope",
  "upslope_m",  "The total area of cells which flow into and/or through the focal cell in metres", "--",   "uced",          "Upslope cumulative elevation drop (UCED)", "--",
  "edge_map",      "Whether or not the focal cell is on the edge of the map", "--",
  "ridge",          "Whether or not the focal cell touches the cell belonging to a different local watershed", "--"
  )

gen <- p
all <- bind_rows(all, p)

p %>%
  gt() %>%
  litap_style() %>%
  fmt_markdown(column = "desc")
```


## `flow_mapper()` variables

The following describes variables output by `flow_mapper()` to various files in the `flow` folder, e.g., `dem_fill.csv` or `dem_inverted.rds` depending on the 
file format chosen.


### `flow/dem_fill`
Variables in `flow/dem_fill` (corresponds to FlowMapR's `XXXdem.dbf`).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

```{r flow_dem}

f <- readRDS(system.file("extdata", "testELEV", "flow", "dem_fill.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param, ~desc, ~landmapr,
  "vol2fl",        "Volume (m\u00B3) to first flood. How much water would be present in the depression at the point when the focal cell would be first inundated.", "Vol2Fl",
  "mm2fl",         "mm to first flood. The amount of rainfall (in mm) required to fall and contribute to flow in order to reach the volume `vol2fl`", "Mm2Fl",
  "parea",         "The surface area (in cell units) of the pond at the point at which the focal cell is first inundated.", "PArea",
  "initial_shed",  "The watershed number identifying intial watersheds defined prior to omitting small or shallow depressions.", NA_character_,
  "local_shed",    "The watershed number identifying local watersheds after small or shallow depressions have been removed. Represents a local, closed depression", "ShedNo (`XXXdem.dbf`)",
  "pond_shed",     "The watershed number identifying pond watersheds for sequential pit filling and the calculation of pond statistics. (Same cells as `fill_shed` but numbers may be different, reflecting a different order of filling)", NA_character_,
  "fill_shed",     "The watershed number identifying fill watersheds which are global catchments including surface flow to the edge of the DEM. Used in calculating of fill statistics (Same cells as `pond_shed` but numbers may be different, reflecting a different order of filling)", "ShedNow (`XXXdem.dbf`)",
  "sgre",          "Slope gradient of rows in a easterly direction (+ = downslope towards east; - =  upslope towards west", NA_character_,
  "sgr",           "Overall slope gradient of rows (absolute `sgre`)",  NA_character_,
  "sgcn",          "Slope gradient of columns in a northerly direction (+ = downslope towards north; - = upslope towards south", NA_character_,
  "sgc",           "Overall slope gradient of columns (absolute `sgcn`)", NA_character_,
  "scr",           "Row slope curvature", NA_character_,
  "scc",           "Column slope curvature",  NA_character_,
  "hill_r_dir",    "Direction the row slope is facing (2 = east facing, 4 = west facing", NA_character_,
  "hill_c_dir",    "Direction the col slope is facing (1 = north facing, 3 = south facing", NA_character_,
  "hill_r_n",      "Number of hillslopes in the focal row. Hillslope number increments when the slope changes from down to up and vice versa.", NA_character_,
  "hill_r_cell",   "Order number of a cell within a row hillslope.", NA_character_,
  "hill_c_n",      "Number of hillslopes in the focal column. Hillslope number increments when the slope changes from down to up and vice versa.", NA_character_,
  "hill_c_cell",   "Order number of a cell within a column hillslope.", NA_character_
  )

all <- bind_rows(all, p)

check_missing(f, all, "dem_fill")

p %>%
  gt() %>%
  litap_style() %>%
  fmt_markdown(columns = "desc")
```



### `flow/dem_inverted`
Variables in `flow/dem_inverted` (corresponds to FlowMapR's `XXXidem.dbf`)

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

**Note**: We don't calculate Vol2Fl, MM2Fl or PArea because in the original LandMapR
they weren't calculated specifically for the inverted DEM, 
but were identical to those in the non-inverted DEM.

```{r flow_idem}
f <- readRDS(system.file("extdata", "testELEV", "flow", "dem_inverted.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param, ~desc, ~landmapr,
  "inv_initial_shed", "The watershed number identifying intial watersheds defined prior to omitting small or shallow depressions, calculated after inverting the DEM", "ShedNo",
  "inv_local_shed", "The inverted watershed number identifying local watersheds calculated after inverting the DEM.", "Shednow"
)

all <- bind_rows(all, p)

check_missing(f, all, "dem_inverted")

p %>%
  gt() %>%
  litap_style()
```


### `flow/stats_XXX` {#generic-stats}

These variables correspond to `flow/stats` files, which are non-dem summary files
for `flow_mapper()`.

#### Stats files

```{r flow_stats}
tibble(param = c("stats_pit", "stats_pond", "stats_fill", "stats_inverted"),
       landmapr = c("XXXpit", "XXXpond", "XXXfill", "XXXipit"),
       desc = c("Information on final pits", 
                "Information on pond pits, including all ways in which 
  local pits can over-spill and connect.",
  "Information on fill pits, including mostly likely sequence in which local pits would connect. This has similar information to `stats_pond` but the *order* is different (and important)",
  "Same as `stats_pit` except that it is calculated for the inverted dem, so these represent peaks, rather than pits.")) %>%
  gt() %>%
  litap_style() %>%
  fmt_markdown(columns = "desc")
```

#### Stats variables

These files have all the same variables but differ in their order (e.g., pond vs. fill) 
and their values depending on whether the shed was inverted or not. 

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

```{r, message = FALSE}
f <- readRDS(system.file("extdata", "testELEV", "flow", "stats_pond.rds", package = "LITAP"))
f <- readRDS(system.file("extdata", "testELEV", "flow", "stats_fill.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param, ~desc, ~landmapr,
  "shedno",   "The watershed number identifying pond watersheds for sequential pit filling.", "ShedNo",
  "edge_pit", "Whether or not the focal watershed touched the edge of the DEM", "Edge",
  "final",    "Whether or not this pit is a 'final' pit which spills over beyond the edge of the dem", "Final",
  "end_pit",  "The final pit this watershed will eventually contribute to", "EndPit",
  "shed_area","Total number of cells in the focal watershed cachment", "ShedArea",
  "pit_row",  "Row number of the pit centre", "PitRow", 
  "pit_col",  "Column number of the pit centre", "PitCol",
  "pit_seqno","Cell number of the pit centre", "PitRec",
  "pit_elev", "Cell elevation of the pit centre", "PitElev",
  "pour_elev","Elevation of the pour point (lowest cell that can overspill into an adjacent watersched/cachment). Elevation recorded is the higher of the cell in the current watershed (`in_elev`) and the adjacent cell in a neighbouring watershed (`out_elev`)",   "PourElev", 
  "pre_vol",  "Total volume (in m * cells\u00B2; you can multiply by grid*2 to get m\u00B3) of the pit pouring into this one (always zero for local pits)",  "PreVol",
  "pit_vol",  "Total volume (in cm * cells\u00B2; you can multiply by grid*2 to get m\u00B3) of the pit including all pits combined into this one", "PitVol",
  "varatio",  "Proxy for the amount of rainfall in mm required to fill a pit completely; Calculated as a volume to area ratio", "Varitio",
  "pit_area", "Number of cells in a pit (you can multiply by grid*2 to get area in m\u00B2)", "PitArea",
  "drains_to","Adjacent watershed that this one is most likely to overspill into",  "DrainsTo",
  "next_pit", "Alternative adjacent watershed that this one would drain to if `drains_to` is already full", "NextPit",
  "becomes",  "New watershed number when this watershed is combined with another", "Becomes",
  "in_row",   "Row number of the cell in the current watershed at the pour point", "InRow",
  "in_col",   "Column number of the cell in the current watershed at the pour point", "InCol",
  "in_seqno", "Cell number of the cell in the current watershed at the pour point", "InRec",
  "in_elev",  "Elevation of the cell in the current watershed at the pour point", "InElev",
  "out_row",  "Row number of the cell in the adjacent watershed at the pour point", "OutRow",
  "out_col",  "Column number of the cell in the adjacent watershed at the pour point", "OutCol",
  "out_seqno","Cell number of the cell in the adjacent watershed at the pour point", "OutRec",
  "out_elev", "Elevation of the cell in the adjacent watershed at the pour point", "OutElev"
  )

all <- bind_rows(all, p)

check_missing(f, all, "stats_fill")

p %>%
  gt() %>%
  litap_style() %>%
  fmt_markdown(columns = "desc")
```




```{r}

p_flow <- pull(all, param) %>%
  unique() 

p1_flow <- c(LITAP:::cols_order$flow,
             LITAP:::cols_order_stats$flow)

if(!all(p_flow %in% p1_flow) | !all(p1_flow %in% p_flow)) {
  
  message("Extra var in tables")
  p_flow[!p_flow %in% p1_flow]
  
  # Missing in lists
  message("Missing var in lists of vars")
  p1_flow[!p1_flow %in% p_flow]
  
  stop("Not all parameters explained", call. = FALSE)
}

```

## `form_mapper()` variables

The following describes variables output by `form_mapper()` to various files in the `form` folder, e.g., `dem_form.csv` or `dem_length.rds` depending on the 
file format chosen.

### `form/dem_form`
Variables in `form/dem_form` (corresponds to FlowMapR's XXXform.dbf).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

```{r}
all <- gen[1:9,]

f <- readRDS(system.file("extdata", "testELEV", "form", "dem_form.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param,      ~desc, ~landmapr,
  "slope_pct", "Slope gradient (%)",            "Slope",
  "slope_deg", "Slope gradient (\u00B0)",      NA_character_,
  "aspect",    "Aspect",                        "Aspect",
  "new_asp",   glue("New Aspect: Aspect rotated 45\u00B0 counter-clockwise. ",
                    "Results in true NE having an aspect of 90\u00B0 as ",
                    "opposed to 45\u00B0."),   "New_asp <small>(FormMapR option 'b' or 'c')</small>",
  "prof",      "Profile",                       "Prof",
  "plan",      "Plan curvature",                "Plan",
  "qarea1",    "Diffuse upslope area (units = cells)", "Qarea <small>(FormMapR option 'a')</small>",
  "qarea2",    "Diffuse upslope area (units = m\u00B2)", "Qarea <small>(FormMapR option 'b' or 'c')</small>",
  "qweti1",    "Wetness Index (derived from qarea measured in cells)", "Qweti <small>(FormMapR option 'a')</small>",
  "qweti2",    "Wetness Index (derived from qarea measured in m\u00B2)", "Qweti <small>(FormMapR option 'b' or 'c')</small>",
  "lnqarea1",  "Natural log of diffuse upslope area (derived from qarea measured in cells)", NA_character_,
  "lnqarea2",  "Natural log of diffuse upslope area (derived from qarea measured in m\u00B2)", "Lnqarea <small>(FormMapR option 'b' or 'c')</small>"
  )

all <- bind_rows(all, p)

check_missing(f, all, "dem_form")

p %>%
  gt() %>%
  litap_style() %>%
  tab_footnote(footnote = "Calculated using equations by Eyton (1991)",
               locations = cells_body(columns = "desc", 
                                      param %in% c("slope_pct", "slope_deg", 
                                                   "aspect", "new_asp", "prof",
                                                   "plan"))) %>%
  tab_footnote(footnote = "Calculated using the multiple descent flow accumulation algorithm by Quinn et al. (1991)",
               locations = cells_body(columns = "desc", 
                                      param %in% c("qarea1", "qarea2", 
                                                   "qweti1", "qweti2"))) %>%
  fmt_markdown(columns = "landmapr")
```




### `form/dem_length`
Variables in `form/dem_length` (corresponds to a combination of FlowMapR's `XXXlen.dbf` and `XXXrelz.dbf` files).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

These variables reflect information on the relative position of the focal cell 
(`seqno`) and the **first** of each feature type the focal cell's flow path would 
cross. 

The features explored are streams/channels (`st`), crests/divides (`cr`), 
pits (`pit`) and peaks (`peak`). 

**Note:** Variables prefaced by `st`, `n2`, `cr`, `pit`, and `peak` were only
calculated in the original FormMapR when option c (compute full set of all 
possible derivatives) was selected.

```{r}

f <- readRDS(system.file("extdata", "testELEV", "form", "dem_length.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param,       ~landmapr,    ~desc,
  "st_row",     "St_row",     "Row of the first connected stream/channel",
  "st_col",     "St_col",     "Column of the first connected stream/channel",
  "st_elev",    "St_elev",    "Elevation of the first connected stream/channel",
  "z2st",       "Z2st",       "Vertical elevation difference from stream/channel",
  "n2st",       "N2st",       "Number of flow cells to stream/channel",
  "cr_row",     "Cr_row",     "Row of the first connected crest/divide",
  "cr_col",     "Cr_col",     "Column of the first connected crest/divide",
  "cr_elev",    "Cr_elev",    "Elevation of the first connected crest/divide",
  "z2cr",       "Z2cr",       "Vertical elevation difference from crest/divide",
  "n2cr",       "N2cr",       "Number of flow cells to crest/divide",
  "pit_row",    "Pit_row",    "Row of the first connected pit",
  "pit_col",    "Pit_col",    "Column of the first connected pit",
  "pit_elev",   "Pit_elev",   "Elevation of the first connected pit",
  "z2pit",      "Z2pit",      "Vertical elevation difference from pit",
  "n2pit",      NA_character_,"Number of flow cells to pit",
  "peak_row",   "Pk_row",     "Row of the first connected peak",
  "peak_col",   "Pk_col",     "Column of the first connected peak",
  "peak_elev",  "Pk_elev",    "Elevation of the first connected peak",
  "z2peak",     "Z2peak",     "Vertical elevation difference from peak",
  "n2peak",     "N2peak",     "Number of flow cells to peak",
  "z2top",      "Z2top",      "Vertical elevation difference from highest cell in watershed",
  "zpit2peak",  "Zpit2peak",  "Total elevation change from pit to peak for this flow path",
  "zcr2st",     "Zcr2st",     glue("Total elevation change from crest/divide ",
                                   "to channel/stream for this flow path"),
  "zcr2pit",    "Zcr2pit",    glue("Total elevation change from crest/divide ",
                                   "to pit for this flow path"),
  "ztop2pit",   "Ztop2pit",   glue("Total elevation change between the highest ",
                                   "cell and the pit cell in the watershed"),
  "ncr2st",     "Ncr2st",     glue("Number of flow cells between crest/divide ",
                                   "and channel/stream for this flow path"),
  "pmin2max",   "Pmin2max",   glue("Estimated % vertical distance above the ",
                                   "lowest cell in the DEM relative to total ",
                                   "elevation difference between the lowest ",
                                   "and highest cells in the entire DEM."),
  "pctz2st",    "Pctz2st",    glue("Estimated % vertical distance above ",
                                   "stream/channel relative to total elevation ",
                                   "difference between crest/divide and ",
                                   "stream/channel (`zcr2st`) for this flow path."),
  "pctz2pit",   "Pctz2pit",   glue("Estimated % vertical distance above pit ",
                                   "relative to total elevation difference ",
                                   "between pit and peak (`zpit2peak`) for ",
                                   "this flow path."),
  "pctz2top",   "Pctz2top",   glue("Estimated % vertical distance above ",
                                   "lowest cell in the watershed relative to ",
                                   "total elevation difference between ",
                                   "lowest and highest cells in the watershed."),
  "pctn2st",    "Pctn2st",    glue("% flow cells above stream/channel relative ",
                                   "to total number of flow cells between ",
                                   "crest/divide and stream/channel for ",
                                   "this flow path"),
  "l2pit",      "L2pit",      "Horizontal, straight-line distance to pit (m)",
  "l2peak",     "L2peak",     "Horizontal, straight-line distance to peak (m)",
  "lpit2peak",  "Lpit2peak",  glue("Horizontal, straight-line distance from ",
                                   "pit to peak (m)"),
  "ppit2peakl", "Ppit2peakl", glue("Relative slope position (%) as distance to ",
                                   "pit (`l2pit`) by total distance between ",
                                   "pit and peak (`lpit2peak`)."),
  "l2str",      "L2str",      glue("Horizontal, straight-line distance to ",
                                   "stream/channel (m)"),
  "l2div",      "L2div",      glue("Horizontal, straight-line distance to ",
                                   "crest/divide (m)"),
  "lstr2div",   "Lstr2div",   glue("Horizontal, straight-line distance from ",
                                   "stream/channel to crest/divide (m)"),
  "pstr2divl",  "Pstr2divl",  glue("Relative slope position (%) as distance to ",
                                  "stream/channel (`l2str`) by total distance ",
                                  "between stream/channel and crest/divide ",
                                  "(`lstr2div`)")
  )

all <- bind_rows(all, p)

check_missing(f, all, "dem_form")

base_vars <- c("z2st", "z2cr", "z2pit", "z2peak", "z2top", "zcr2st", "zpit2peak",
               "ztop2pit", "pctz2st", "pctz2pit", "pctz2top", "pmin2max")
len_vars <- p$param[str_detect(p$param, "^l|pstr2divl|ppit2peakl")]
rel_full_vars <- p$param[!p$param %in% c(base_vars, len_vars, "n2pit")]

p %>%
  gt() %>%
  litap_style() %>%
  tab_footnote(footnote = "From XXXrelz.dbf", 
               location = cells_body(columns = "landmapr", 
                                     rows = param %in% base_vars)) %>%
  tab_footnote(footnote = glue("From XXXrelz.dbf when selecting option c ",
                               "(compute all possible terrain derivatives)"),
               location = cells_body(columns = "landmapr", 
                                     rows = param %in% rel_full_vars)) %>%
  tab_footnote(footnote = glue("From XXXlen.dbf, created when selecting ",
                               "option c (compute all possible terrain ",
                               "derivatives)"), 
               location = cells_body(columns = "landmapr", 
                                     rows = param %in% len_vars)) %>%
  fmt_markdown(column = "desc")
                                    
```


```{r}

p_form <- pull(all, param) %>%
  unique() 

p1_form <- c(LITAP:::cols_order$form,
             LITAP:::cols_order_stats$form)
  

if(!all(p_form %in% p1_form) | !all(p1_form %in% p_form)) {
  
  message("Extra var in tables:",
          glue_collapse(p_form[!p_form %in% p1_form], 
                        sep = ", ", last = ", and "))
  
  # Missing in lists
  message("Missing var in lists of vars:",
          glue_collapse(p1_form[!p1_form %in% p_form], 
                        sep = ", ", last = ", and "))
          
  
  stop("Not all parameters explained", call. = FALSE)
}

```


## `facet_mapper()` variables

The following describes variables output by `facet_mapper()` to various files in the `facet` folder, e.g., `dem_fuza.csv` or `dem_fuzc.rds` depending on the 
file format chosen.

### `facet/dem_fuza`
Variables in `facet/dem_fuza` (corresponds to FlowMapR's `XXXfuza.dbf`).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

**Note**: Only fuzzy landform attributes values defined in the ARULE file will
be in the `dem_fuza` file. Here we show the general attributes which have been
calculated as the *probability/likelihood* of relatively having that particular
attribute. For example, `convex_d` is the probability of being relatively convex
in the down slope direction.

```{r}
f <- readRDS(system.file("extdata", "testELEV", "facet", "dem_fuza.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param,       ~landmapr,    ~desc,
  "zone",       "ZONE",       glue("EXPERIMENTAL: Different zones may have ",
                                   "different classifications in the original ",
                                   "BC-PEM DSS proceedure."),
  "convex_d",   "CONVEX_D",   "Convex in down slope direction",
  "concave_d",  "CONCAVE_D",  "Concave in down slope direction",
  "planar_d",   "PLANAR_D",   "Planar in down slope direction",
  "convex_a",   "CONVEX_A",   "Convex across the slope",
  "concave_a",  "CONCAVE_A",  "Concave across the slope",
  "planar_a",   "PLANAR_A",   "Planar across the slope",
  "high_wi",    "HIGH_WI",    "High wetness index",
  "low_wi",     "LOW_WI",     "Low wetness index",
  "near_level", "NEAR_LEVEL", "Near level slope gradient",
  "rel_steep",  "REL_STEEP",  "Relatively steep slope gradient",
  "near_div",   "NEAR_DIV",   "Near a local divide", 
  "near_half",  "NEAR_HALF",  "Near mid-point between divide and channel",
  "near_chan",  "NEAR_CHAN",  "Near a local channel",
  "near_peak",  "NEAR_PEAK",  "Near a local peak",
  "near_mid",   "NEAR_MID",   "Near mid-point between peak and pit",
  "near_pit",   "NEAR_PIT",   "Near a local pit",
  "hi_above",   "HI_ABOVE",   "Relatively high above pit cell",
  "planar_2x",  "PLANAR_2X",  "Planar in profile and plan (Average of `planar_d` and `planar_a`)"
  )

all <- bind_rows(all, p)

check_missing(f, all, "dem_fuza")

p %>%
  gt() %>%
  litap_style() %>%
  tab_footnote(footnote = "As in MacMillian et al. (2000)", 
               location = cells_body()) %>%
  opt_footnote_marks(marks = c("", "")) %>%
  fmt_markdown(columns = "desc")
                                    
```



### `facet/dem_fuzc`
Variables in `form/dem_fuzc` (corresponds to FlowMapR's `XXXfuzc.dbf`).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

**Note**: Only landform element (facet) values defined in the CRULE file will
be in the `dem_fuzc` file. Here we show some common elements included in the
CRULE files included in the original LandMapR and `LITAP`. Be aware, however,
that these can be custom created and could therefore represent something else
entirely. These values represent the *probability/likelihood* of the cell being 
that particular landform element. For example, `lcr` is the probability of being
a "Level crest".


```{r}
f <- readRDS(system.file("extdata", "testELEV", "facet", "dem_fuzc.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param,       ~landmapr,    ~desc,
  "lcr", "LCR", "Level crest",
  "dsh", "DSH", "Divergent shoulder",
  "ude", "UDE", "Upper depression",
  "bsl", "BSL", "Back slope",
  "dbs", "DBS", "Divergent back slope",
  "cbs", "CBS", "Convergent back slope",
  "ter", "TER", "Terrace",
  "sad", "SAD", "Saddle",
  "mde", "MDE", "Mid-slope depression",
  "fsl", "FSL", "Foot slope",
  "tsl", "TSL", "Toe slope", 
  "fan", "FAN", "Fan",
  "lsm", "LSM", "Lower-slope mound",
  "lls", "LLS", "Level lower slope",
  "dep", "DEP", "Lower depression",
  "cst", "--", "Crest",
  "ups", "--", "Upper slope",
  "mid", "--", "Mid slope",
  "low", "--", "Lower slope",
  "dep", "--", "Depression",
  
  "max_facet",      "max_facet",   glue("Number identifying the landform ",
                                        "element/facet which has the max value ",
                                        "for this cell (most likely facet to ",
                                        "occur)"),
  "max_value",      "--",          glue("The highest computed likelihood value of ",
                                        "the maximum facet"),
  "max_2nd_facet",  "next_facet",  glue("Number identifying the landform",
                                        "element/facet which has the second ",
                                        "highest likelihood value for this cell ",
                                        "(second most likely facet to occur)"),
  "max_2nd_value",      "--",      "The value of the second highest facet",
  "max_facet_name",     "--",      "3-letter code of the facet with the highest likelihood",
  "max_2nd_facet_name", "--",      "3-letter code of the facet with the second highest likelihood"
  )

all <- bind_rows(all, p)

check_missing(f, all, "dem_fuzc")

p %>%
  gt() %>%
  litap_style() %>%
  tab_footnote(footnote = glue("As described in MacMillian et al. (2000) ",
                               "and MacMillian (2003)"), 
               location = cells_body(columns = "desc", 
                                     rows = 1:15)) |>
  tab_footnote(footnote = "As described in Sheng et al. (2011)",
               location = cells_body(columns = "desc",
                                     rows = 16:20))
                                    
```


```{r}

p_facet <- filter(all, !param %in% 
                    c(LITAP:::cols_order$flow[-c(1:6)], 
                      LITAP:::cols_order$form[-c(1:6)])) %>%
  pull(param) %>%
  unique() 

crule <- system.file("extdata", "crule.dbf", package = "LITAP") %>%
  foreign::read.dbf() %>%
  bind_rows(system.file("extdata", "c7rule.dbf", package = "LITAP") %>%
              foreign::read.dbf()) %>%
  select(F_NAME, FUZATTR) %>%
  mutate(across(everything(), tolower)) %>%
  unlist() %>%
  unique() %>%
  setNames(NULL)

p1_facet <- c(LITAP:::cols_order$facet,
              crule)

if(!all(p_facet %in% p1_facet) | !all(p1_facet %in% p_facet)) {
  
  message("Extra var in tables:",
          glue_collapse(p_facet[!p_facet %in% p1_facet], 
                        sep = ", ", last = ", and "))
  
  # Missing in lists
  message("Missing var in lists of vars:",
          glue_collapse(p1_facet[!p1_facet %in% p_facet], 
                        sep = ", ", last = ", and "))
          
  
  stop("Not all parameters explained", call. = FALSE)
}

```

## `wepp_mapper()` variables

The following describes variables output by `wepp_mapper()` to various files in the `wepp` folder, e.g., `dem_wepp.csv` or `dem_wepp.rds` depending on the 
file format chosen.

### `wepp/dem_wepp`
Variables in `wepp/dem_wepp` (corresponds to FlowMapR's `XXXwepp.dbf`).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

**Note:** that the use of "top", "left", and "right" isn't quite consistent. 
"Top" refers to coming in from the top to the cell (direction of flow is downwards).
Whereas "right" and "left" refer to the direction of flow (towards the right, coming
in to the cell from the left and vice versa). We leave this as is to be consistent
with FlowMapR but may change this in future.

```{r}
f <- readRDS(system.file("extdata", "testELEV", "wepp", "dem_wepp.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param,       ~landmapr,    ~desc,
  "seedtype",   "SEEDTYPE",   glue::glue(
    "1 - Channel start ",
      "(where the upslope value is greater than the `upslope_threshold` argument<br>",
    "2 - Channel junction (where two channels meet)<br>",
    "3 - Cell upslope of a junction which is *not* the main branch (end point of a segment)<br>",
    "4 - Split cell ",
      "(where a channel is split to the maximum `chan_length` value; end point of a segment)<br>", 
    "5 - Pit cell (end point of a segment)<br>",
    "6 - Channel end (end point of a segment)<br>",
    "7 - Cell upslope of a junction identifying the main branch ",
      "(has the largest upslope area; endpoint of a segment)<br>",
    "8 - Cell immediate down stream from either a depression (pit) or a split-type seed cell [start of new channel segment]"),
  "shed_no",    "SHED_NO",   "The ID of the channel segment which a cell eventually flows into",
  "shed_side",  "SHED_SIDE",  "The side from which this cell eventually flows into the channel. channel cell from the top (1) of the channel (downwards), from the left (towards the right; 2), or from the right (towards the left; 3) of the channel.",
  "hill_no",    "HILL_HO",   "The ID of a hillside based on where the cells flow into a channel",
  "chan_no",    "CHAN_NO",   "The ID of a channel",
  "chan_side",  "CHAN_SIDE",  "A non-channel cell which drains into a channel cell from the top (1) of the channel (downwards), from the left (towards the right; 2), or from the right (towards the left; 3) of the channel.",
  "segment_no", "SEGMENT_NO",   "ID of an individual channel segment",
  "l2st",       "L2ST",    "Line-of-sight distance from a cell to the cell where it flows into the channel",
  )

all <- bind_rows(all, p)

check_missing(f, all, "dem_wepp")

p %>%
  gt() %>%
  litap_style() %>%
  fmt_markdown(columns = "desc")
                                    
```



### `wepp/struct`
Variables in `wepp/struct` (corresponds to FlowMapR's `XXXstruc.dbf`).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

**Note:** that the use of "top", "left", and "right" isn't quite consistent. 
"Top" refers to coming in from the top to the cell (direction of flow is downwards).
Whereas "right" and "left" refer to the direction of flow (towards the right, coming
in to the cell from the left and vice versa). We leave this as is to be consistent
with FlowMapR but may change this in future.

```{r}
f <- readRDS(system.file("extdata", "testELEV", "wepp", "struct.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param,       ~landmapr,    ~desc,
  "element_no",   "Element_no",   "ID of the channel or impoundment element",
  "ele_type",    "Ele_type",   "Channel type (2) or impoundment type (3)",
  "left_hill",  "Left_hill",  "The ID of hill slope which drains in",
  "right_hill", "Right_hill", "The ID of hill slope which drains in",
  "top_hill", "Top_hill", "The ID of hill slope which drains in",
  "left_chan", "Left_chan", "The ID of the channel segment which drains in",
  "right_chan", "Right_chan", "The ID of the channel segment which drains in",
  "top_chan", "Top_chan", "The ID of the channel segment which drains in",
  "left_imp", "Left_imp", "The ID of the impoundment which drains in",
  "right_imp", "Right_imp", "The ID of the impoundment which drains in",
  "top_imp", "Top_imp", "The ID of the impoundment which drains in",
  "comments", "Comment", "Description of the element"
  )

all <- bind_rows(all, p)

check_missing(f, all, "struct")

p %>%
  gt() %>%
  litap_style() %>%
  fmt_markdown(columns = "desc")
                                    
```


### `wepp/segs`
Variables in `wepp/segs` (corresponds to FlowMapR's `XXXsegs.dbf`).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

**Note:** that the use of "top", "left", and "right" isn't quite consistent. 
"Top" refers to coming in from the top to the cell (direction of flow is downwards).
Whereas "right" and "left" refer to the direction of flow (towards the right, coming
in to the cell from the left and vice versa). We leave this as is to be consistent
with FlowMapR but may change this in future.

```{r}
f <- readRDS(system.file("extdata", "testELEV", "wepp", "segs.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param,         ~landmapr,      ~desc,
  "initial_id",   "Initial_id",   "Original ID for a segment before sorting",
  "down_seg",     "Down_seg",     "Downslope channel segment ID this segment drains into",
  "sort_order",   "Sort_order",   "Topological order of sorting channel segments",
  "final_id",     "Final_id",     "Final ID of a segment",
  "drain_seqno",  "Drain_seqno",  "The number of the first cell where this segment drains",
  "start_seqno",  "Start_seqno",  "Number of the first cell in this segment",
  "start_row",    "Start_row",    "Row of the first cell in this segment",
  "start_col",    "Start_col",    "Column of the first cell in this segment",
  "start_type",   "Start_type",   "Seed type of this start of the segment (see `seedtype` above under `wepp/dem_wepp`)",
  "start_elev",   "Start_elev",   "Elevation of the first cell in this segment",
  "start_ddir",   "Start_ddir",   "Direction of water flow of the first cell in this segment",
  "end_seqno",    "End_seqno",    "Number of the last cell in this segment",
  "end_row",      "End_row",      "Row of the last cell in this segment",
  "end_col",      "End_col",      "Column of the last cell in this segment",
  "end_type",     "End_type",     "Seed type of this end of the segment (see `seedtype` above under `wepp/dem_wepp`)",
  "end_elev",     "End_elev",     "Elevation of the last cell in this segment",
  "impound",      "Impound",      "Whether this segment is an impoundment",
  "center_seg",   "Center_seg",   "ID of the segment drainign in from the top",
  "center_seqno", "Center_seqno", "Cell of the segment draining in from the top",
  "right_seg",    "Right_seg",    "ID of the segment drainign in right",
  "right_seqno",  "Right_seqno",  "Cell of the segment draining in right",
  "left_seg",     "Left_seg",     "ID of the segment drainign in left",
  "left_seqno",   "Left_seqno",   "Cell of the segment draining in left",
  "len_cells",    "Len_cells",    "Length of the segment in cells",
  "len_meters",   "Len_meters",   "Length of the segment in meters",
  "flow2crow",    "Flow2crow",    "Empy",
  "chan_shape",   "Chan_shape",   "Empy",
  "width_m",      "Width_m",      "Empy"
  )

all <- bind_rows(all, p)

check_missing(f, all, "segs")

p %>%
  gt() %>%
  litap_style() %>%
  fmt_markdown(columns = "desc")
                                    
```

### `wepp/prof`
Variables in `wepp/prof` (corresponds to FlowMapR's `XXXprof.dbf`).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

This is an intermediate file and isn't documented by LandMapR.

### `wepp/hill`
Variables in `wepp/hill` (corresponds to FlowMapR's `XXXhill.dbf`).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

**Note:** that the use of "top", "left", and "right" isn't quite consistent. 
"Top" refers to coming in from the top to the cell (direction of flow is downwards).
Whereas "right" and "left" refer to the direction of flow (towards the right, coming
in to the cell from the left and vice versa). We leave this as is to be consistent
with FlowMapR but may change this in future.

```{r}
f <- readRDS(system.file("extdata", "testELEV", "wepp", "hill.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param,         ~landmapr,      ~desc,
  "hill_width", "Hill_width", "Length of the WEPP channel that this hillslope drains to for left and rigth hill slopes",
  "hill_area", "Hill_area", "The area of the hill slope",
  "max_len", "Max_len", "Maximum distance to the channel",
  "wepp_len", "Wepp_len", "`hill_area` / `hill_width`",
  "num_points", "Num_points", "Number of points along the profile at which slope and aspect were calculated",
  "profile", "Profile", "Profile: Sample of mean values for slope gradient and aspect at different relative distances along the feature"
  )

all <- bind_rows(all, p)

check_missing(f, all, "hill")

p %>%
  gt() %>%
  litap_style() %>%
  fmt_markdown(columns = "desc")
                                    
```


### `wepp/chan`
Variables in `wepp/chan` (corresponds to FlowMapR's `XXXchan.dbf`).

This list only includes variables not already described above in the [Generic DEMs](#generic-dem).

This is similar to the `wepp/hill` but with the channels, rather than hillslopes.

```{r}
f <- readRDS(system.file("extdata", "testELEV", "wepp", "chan.rds", package = "LITAP"))
#names(f)[!names(f) %in% c(all$param)]

p <- tribble(
  ~param,         ~landmapr,      ~desc,
  "chan_len", "Chan_len", "The area of the channel (length * cell width)",
  "mean_slope_pct", "Mean_slope", "The mean of the slope gradient across all cells in the channel",
  "gen_slope_pct", "Gen_slope", "The general mean of the slope, as the absolute vertical drop divided by the length (area) of the channel."
  )

all <- bind_rows(all, p)

check_missing(f, all, "hill")

p %>%
  gt() %>%
  litap_style() %>%
  fmt_markdown(columns = "desc")
                                    
```

## Extra Data files (`all_XXX`, etc.)

There are several extra data files created at the end of `facet_mapper()`
which are not part of the original FlowMapR runs, but are adapted from an 
Access workflow developed by Li, Sheng. 

Variables in `all_XXX.xlsx` correspond to Li, Sheng's `XXX_AllData.txt` and
are collected from variables in the other LITAP outputs.

**Note**: We don't calculate the `lk_XXX` variables in the original `XXX_ALLData.txt`
files because they correspond to columns already included in the data. 
For example `lk_st_row` corresponse to `st_row`, etc. For variables like `lk_st_x`
which were not originally included, they are now represented by `st_x`.


## References

Eyton, J. R. 1991. Rate-of-change maps. Cartography and Geographic Information Systems. 18: 87-103

Macmillan, R.A. (2003). LandMapR Software Toolkit- C++ Version (2003): User’s Manual. Available: <https://www.researchgate.net/publication/301726747_LandMapR_Software_Toolkit-_C_Version_2003_User's_Manual/>

MacMillan, R.A., Pettapiece, W.W., Nolan, S.C., & Goddard, T.W. 2000. A generic procedure for automatically segmenting landforms into landform elements using DEMs, heuristic rules and fuzzy logic– Fuzzy sets and Systems 113: 81–109.

Quinn, P., K. Beven, P. Chevallier and O. Planchon. 1991. The prediction of hillslope flow paths for distributed hydrological modelling using digital terrain models. Hydrological Processes. 5: 59-79

Sheng Li, David A. Lobb, Brian G. McConkey, R. A. MacMillan, Alan Moulin,
and Walter R. Fraser. 2011. Extracting topographic characteristics of landforms
typical of Canadian agricultural landscapes for agri-environmental modeling.
I. Methodology. Canadian Journal of Soil Science 91(2), 251-266.
<https://doi.org/10.4141/CJSS10080>.