Understanding output variables

Functions in LITAP output a lot of variables, many of which are based on the original LandMapR* 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).

* Interpretations of LandMapR variables are derived from the LandMapR C++ User Manual, October 2003. 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.

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

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

LITAP Parameters LandMapR Name Description
seqno SeqNo Cell number identifying a particular cell in the DEM
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 Row number
col Col Column number
elev Elev Elevation in metres
ddir Ddir Direction of water flow (1 = SW, 2 = S, 3 = SE, 4 = W, 5 = No flow, 6 = E, 7 = NW, 8 = N, 9 = NE)
drec Drec The cell number (seqno) of the cell this focal cell flows into
upslope UpSlope The number of cells which flow into and/or through the focal cell
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

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.

LITAP Parameters LandMapR Name Description
vol2fl Vol2Fl Volume (m³) to first flood. How much water would be present in the depression at the point when the focal cell would be first inundated.
mm2fl 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
parea PArea The surface area (in cell units) of the pond at the point at which the focal cell is first inundated.
initial_shed – The watershed number identifying intial watersheds defined prior to omitting small or shallow depressions.
local_shed ShedNo (`XXXdem.dbf`) The watershed number identifying local watersheds after small or shallow depressions have been removed. Represents a local, closed depression
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)
fill_shed ShedNow (`XXXdem.dbf`) 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)
sgre – Slope gradient of rows in a easterly direction (+ = downslope towards east; - = upslope towards west
sgr – Overall slope gradient of rows (absolute sgre)
sgcn – Slope gradient of columns in a northerly direction (+ = downslope towards north; - = upslope towards south
sgc – Overall slope gradient of columns (absolute sgcn)
scr – Row slope curvature
scc – Column slope curvature
hill_r_dir – Direction the row slope is facing (2 = east facing, 4 = west facing
hill_c_dir – Direction the col slope is facing (1 = north facing, 3 = south facing
hill_r_n – Number of hillslopes in the focal row. Hillslope number increments when the slope changes from down to up and vice versa.
hill_r_cell – Order number of a cell within a row hillslope.
hill_c_n – Number of hillslopes in the focal column. Hillslope number increments when the slope changes from down to up and vice versa.
hill_c_cell – Order number of a cell within a column hillslope.

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.

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.

LITAP Parameters LandMapR Name Description
inv_initial_shed ShedNo The watershed number identifying intial watersheds defined prior to omitting small or shallow depressions, calculated after inverting the DEM
inv_local_shed Shednow The inverted watershed number identifying local watersheds calculated after inverting the DEM.

flow/stats_XXX

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

Stats files

LITAP Parameters LandMapR Name Description
stats_pit XXXpit Information on final pits
stats_pond XXXpond Information on pond pits, including all ways in which local pits can over-spill and connect.
stats_fill XXXfill 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)
stats_inverted XXXipit Same as stats_pit except that it is calculated for the inverted dem, so these represent peaks, rather than pits.

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.

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

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.

LITAP Parameters LandMapR Name Description
slope_pct Slope Slope gradient (%)*
slope_deg – Slope gradient (°)*
aspect Aspect Aspect*
new_asp New_asp (FormMapR option ‘b’ or ‘c’) New Aspect: Aspect rotated 45° counter-clockwise. Results in true NE having an aspect of 90° as opposed to 45°.*
prof Prof Profile*
plan Plan Plan curvature*
qarea1 Qarea (FormMapR option ‘a’) Diffuse upslope area (units = cells)†
qarea2 Qarea (FormMapR option ‘b’ or ‘c’) Diffuse upslope area (units = m²)†
qweti1 Qweti (FormMapR option ‘a’) Wetness Index (derived from qarea measured in cells)†
qweti2 Qweti (FormMapR option ‘b’ or ‘c’) Wetness Index (derived from qarea measured in m²)†
lnqarea1 – Natural log of diffuse upslope area (derived from qarea measured in cells)
lnqarea2 Lnqarea (FormMapR option ‘b’ or ‘c’) Natural log of diffuse upslope area (derived from qarea measured in m²)
* Calculated using equations by Eyton (1991)
† Calculated using the multiple descent flow accumulation algorithm by Quinn et al. (1991)

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.

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.

LITAP Parameters LandMapR Name Description
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 – 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† Total elevation change from crest/divide to channel/stream for this flow path
zcr2pit Zcr2pit* Total elevation change from crest/divide to pit for this flow path
ztop2pit Ztop2pit† Total elevation change between the highest cell and the pit cell in the watershed
ncr2st Ncr2st* Number of flow cells between crest/divide and channel/stream for this flow path
pmin2max Pmin2max† 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† Estimated % vertical distance above stream/channel relative to total elevation difference between crest/divide and stream/channel (zcr2st) for this flow path.
pctz2pit Pctz2pit† Estimated % vertical distance above pit relative to total elevation difference between pit and peak (zpit2peak) for this flow path.
pctz2top Pctz2top† Estimated % vertical distance above lowest cell in the watershed relative to total elevation difference between lowest and highest cells in the watershed.
pctn2st Pctn2st* % 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‡ Horizontal, straight-line distance from pit to peak (m)
ppit2peakl Ppit2peakl‡ Relative slope position (%) as distance to pit (l2pit) by total distance between pit and peak (lpit2peak).
l2str L2str‡ Horizontal, straight-line distance to stream/channel (m)
l2div L2div‡ Horizontal, straight-line distance to crest/divide (m)
lstr2div Lstr2div‡ Horizontal, straight-line distance from stream/channel to crest/divide (m)
pstr2divl Pstr2divl‡ Relative slope position (%) as distance to stream/channel (l2str) by total distance between stream/channel and crest/divide (lstr2div)
* From XXXrelz.dbf when selecting option c (compute all possible terrain derivatives)
† From XXXrelz.dbf
‡ From XXXlen.dbf, created when selecting option c (compute all possible terrain derivatives)

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.

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.

LITAP Parameters LandMapR Name Description
zone ZONE 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)
As in MacMillian et al. (2000)

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.

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”.

LITAP Parameters LandMapR Name Description
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 Number identifying the landform element/facet which has the max value for this cell (most likely facet to occur)
max_value -- The highest computed likelihood value of the maximum facet
max_2nd_facet next_facet Number identifying the landformelement/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
* As described in MacMillian et al. (2000) and MacMillian (2003)
† As described in Sheng et al. (2011)

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.

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.

LITAP Parameters LandMapR Name Description
seedtype SEEDTYPE 1 - Channel start (where the upslope value is greater than the upslope_threshold argument
2 - Channel junction (where two channels meet)
3 - Cell upslope of a junction which is not the main branch (end point of a segment)
4 - Split cell (where a channel is split to the maximum chan_length value; end point of a segment)
5 - Pit cell (end point of a segment)
6 - Channel end (end point of a segment)
7 - Cell upslope of a junction identifying the main branch (has the largest upslope area; endpoint of a segment)
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

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.

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.

LITAP Parameters LandMapR Name Description
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

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.

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.

LITAP Parameters LandMapR Name Description
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

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.

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.

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.

LITAP Parameters LandMapR Name Description
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

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.

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

LITAP Parameters LandMapR Name Description
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.

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.