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

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 identifing 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

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

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`

Generic stats file variables

These variables correspond to flow/stats files, which are non-dem summary files for flow mapper and include:

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.

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.

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

`form/dem_form`

Variables in form/dem_form (corresponds to FlowMapR’s XXXform.dbf)

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

References

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

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

Steffi LaZerte

2021-12-02

Generic variables

Generic DEM file variables

`flow_mapper()` variables

`flow/dem_fill`

`flow/dem_inverted`

`flow/stats_XXX`

`form_mapper()` variables

`form/dem_form`

`form/dem_length`

`facet_mapper()` variables

`facet/dem_fuza`

References

Understanding output variables

Steffi LaZerte

2021-12-02

Generic variables

Generic DEM file variables

flow_mapper() variables

flow/dem_fill

flow/dem_inverted

flow/stats_XXX

form_mapper() variables

form/dem_form

form/dem_length

facet_mapper() variables

facet/dem_fuza

References

`flow_mapper()` variables

`flow/dem_fill`

`flow/dem_inverted`

`flow/stats_XXX`

`form_mapper()` variables

`form/dem_form`

`form/dem_length`

`facet_mapper()` variables

`facet/dem_fuza`