Create an Optimal Channel Network on a general contour — create_general_contour

Function that performs the OCN search algorithm on a general contour and creates OCN at the flow direction (FD) level.

Usage

create_general_contour_OCN(flowDirStart, expEnergy = 0.5,
  cellsize = 1, xllcorner = 0.5 * cellsize, yllcorner = 0.5 *
  cellsize, nIter = NULL, nUpdates = 50,
  initialNoCoolingPhase = 0, coolingRate = 1,
  showIntermediatePlots = FALSE, thrADraw = NULL, 
  easyDraw = NULL, saveEnergy = FALSE, saveExitFlag = FALSE,
  displayUpdates = 1)

Arguments

flowDirStart

Matrix with custom initial flow directions. Cells outside the catchment must have value equal to NaN. Cells within the catchment have natural numbers between 0 and 8. Key is as follows:

0: Outlet
1: +1 column
2: -1 row, +1 column
3: -1 row
4: -1 row, -1 column
5: -1 column
6: +1 row, -1 column
7: +1 row
8: +1 row, +1 column

Note that flowDirStart must have at least one outlet, that is one cell with value 0. The position of outlet(s) will not be altered by the OCN search algorithm.

expEnergy

Exponent of the functional sum(A^expEnergy) that is minimized during the OCN search algorithm.

cellsize

Size of a pixel in planar units.

xllcorner

Longitudinal (column-wise) coordinate of the lower-left pixel of flowDirStart.

yllcorner

Latitudinal (row-wise) coordinate of the lower-left pixel of flowDirStart.

nIter

Number of iterations for the OCN search algorithm. Default is 40 times the number of non-NaN pixels of flowDirStart.

nUpdates

Number of updates given during the OCN search process (only effective if any(displayUpdates,showIntermediatePlots)=TRUE.).

initialNoCoolingPhase, coolingRate

Parameters of the function used to describe the temperature of the simulated annealing algorithm. See details.

showIntermediatePlots

If TRUE, the OCN plot is updated nUpdates times during the OCN search process. Note that, for large lattices, showIntermediatePlots = TRUE might slow down the search process considerably (especially when easyDraw = FALSE).

thrADraw

Threshold drainage area value used to display the network (only effective when showIntermediatePlots = TRUE). Default value is 0.002*cellsize^2*nNodes, where nNodes is the number of non-NaN pixels of flowDirStart.

easyDraw

Logical. If TRUE, the whole network is displayed (when showIntermediatePlots = TRUE), and pixels with drainage area lower than thrADraw are displayed in light gray. If FALSE, only pixels with drainage area greater or equal to thrADraw are displayed. Default is FALSE if dimX*dimY <= 40000, and TRUE otherwise. Note that setting easyDraw = FALSE for large networks might slow down the process considerably.

saveEnergy

If TRUE, energy is saved (see Value for its definition).

saveExitFlag

If TRUE, exitFlag is saved (see Value for its definition).

displayUpdates

State if updates are printed on the console while the OCN search algorithm runs.

0: No update is given.
1: An estimate of duration is given (only if dimX*dimY > 1000, otherwise no update is given).
2: Progress updates are given. The number of these is controlled by nUpdates

Value

A river object as in create_OCN, to which the reader is referred for detailed documentation. However, note that in this case dimX and dimY are equal to the number of columns and rows of flowDirStart, respectively, while nNodes is the number of non-NaN pixels in flowDirStart. Hence, nNodes is generally lower than dimX*dimY. The additionally exported vector FD$toDEM identifies the indices of the pixels of the landscape/flow direction matrix that belong to the catchment (i.e., they are not NaN).

Examples

OCN1 <- create_general_contour_OCN(flowDir, nIter=0) # initial flow directions
OCN2 <- create_general_contour_OCN(flowDir) # perform OCN algorithm
draw_simple_OCN(OCN1)

draw_simple_OCN(OCN2)