R6 Class for processing a catchment to make a dynatop TOPMODEL

Methods

Public methods

dynatopGIS$new()
dynatopGIS$add_catchment()
dynatopGIS$add_channel()
dynatopGIS$add_layer()
dynatopGIS$get_layer()
dynatopGIS$plot_layer()
dynatopGIS$sink_fill()
dynatopGIS$order()
dynatopGIS$combine_layers()
dynatopGIS$create_model()
dynatopGIS$get_version()
dynatopGIS$clone()

`dynatopGIS$new()`

Initialise a project, or reopen an existing project

Usage

dynatopGIS$new(projectDir)

Arguments

projectDir: is the directroy of project data

Details

If the directory exists the existing tif files are loaded as the project.

Returns

A new `dynatopGIS` object

`dynatopGIS$add_catchment()`

Add a catchment outline and dem to the `dynatopGIS` project

Usage

dynatopGIS$add_catchment(catchment, dem, fill_na = -9999)

Arguments

catchment: a SpatVect object or the path to file containing one which contains the catchment outline
dem: a SpatRast object or the path to file containing one which is the DEM
fill_na: value used to replace missing dem vales within the catchment

Details

If the inputs are not spatial objects they are read in using the terra package. The resolution and projection of the project is taken from the provided dem. All NA values in the dem within the catchment are replaced by the fill_na values so they can be identified as sinks.

Returns

invisible(self)

`dynatopGIS$add_channel()`

Import channel data to the `dynatopGIS` object

Usage

dynatopGIS$add_channel(channel, water_bodies = NULL, verbose = FALSE)

Arguments

channel: a SpatVect object of lines or file path that can be loaded as one containing the channel information
water_bodies: a SpatVect object of polygons or file path that can be loaded as one containing the channel information
verbose: Should additional progress information be printed

Details

Takes the representation of the channel network as a SpatVect with properties name, startNode, endNode, slope, depth and width. This is rasterised. The polygons in water_bodies are then burnt in. it is presumed that each polygon has only one outlet.

Returns

suitable for chaining

`dynatopGIS$add_layer()`

Add a layer of geographical information

Usage

dynatopGIS$add_layer(layer, layer_name = names(layer))

Arguments

layer: the raster layer to add (see details)
layer_name: name to give to the layer

Details

The layer should either be a raster layer or a file that can be read into a SpatRast by the terra package. The projection, resolution and extent are checked against the existing project data. Only layer names not already in use (or reserved) are allowed. If successful the layer is added to the project.

Returns

suitable for chaining

`dynatopGIS$get_layer()`

Get a layer of geographical information or a list of layer names

Usage

dynatopGIS$get_layer(layer_name = NULL)

Arguments

layer_name: name of the layer give to the layer or NULL to return list of layers

Returns

a SpatRaster containing the requested layer or a vector of layer names

`dynatopGIS$plot_layer()`

Plot a layer

Usage

dynatopGIS$plot_layer(layer_name, add_channel = TRUE)

Arguments

layer_name: the name of layer to plot
add_channel: should the channel be added to the plot

Returns

a plot

`dynatopGIS$sink_fill()`

The sink filling algorithm of Planchona and Darboux (2001)

Usage

dynatopGIS$sink_fill(
  min_grad = 1e-04,
  max_it = 1e+06,
  verbose = FALSE,
  hot_start = FALSE
)

Arguments

min_grad: Minimum gradient between cell centres
max_it: maximum number of replacement cycles
verbose: print out additional diagnostic information
hot_start: start from filled_dem if it exists

Details

The algorithm implemented is based on that described in Planchona and Darboux, "A fast, simple and versatile algorithm to fill the depressions in digital elevation models" Catena 46 (2001). A pdf can be found at (<https://horizon.documentation.ird.fr/exl-doc/pleins_textes/pleins_textes_7/sous_copyright/010031925.pdf>).

The flow_type can be either MFD algorithm in TODO

`dynatopGIS$order()`

Computes the order (banding) to evaluate cells in

Usage

dynatopGIS$order(verbose = FALSE)

Arguments

verbose: print out additional diagnostic information

Details

The algorithm passed through the cells to compute the band starting at the river outlets hru numbers are assigned in approxamtly band order

`dynatopGIS$combine_layers()`

Combine any number of layers into a unique classification

Usage

dynatopGIS$combine_layers(class_name, layers)

Arguments

class_name: name of the new layer to create
layers: a vector of layer names to combine into new classes through unique combinations. Names should correspond to raster layers in the project directory.

Details

This combines the layers into unique classess and stores a raster of outcomes along with a json file of the classifications

`dynatopGIS$create_model()`

Create a Dynamic TOPMODEL

Usage

dynatopGIS$create_model(
  model_name,
  class_layer = NULL,
  precip_layer = NULL,
  precip_label = "precip",
  pet_layer = NULL,
  pet_label = "pet",
  verbose = FALSE
)

Arguments

model_name: base of the name for the new model files
class_layer: the layer defining the landscape classes
precip_layer: the layer defining the rainfall inputs
precip_label: Prepended to rain_layer values to give rainfall series name
pet_layer: the layer defining the pet inputs
pet_label: Prepended to pet_layer values to give pet series name
verbose: print more details of progress

Details

The class_layer is used to assign classes to the HRUs. Flow between HRUs are based on the ordering of the catchment (see the order method) with low from a HRU can only go to a HRU with a lower band. The rain_layer (pet_layer) can contain the numeric id values of different rainfall (pet) series. If the value of rain_layer (pet_layer) is not NULL the value for the precipitation and PET inputs for each HRU are taken as e.g. paste0(precip_label,precip) otherwise the value of e.g. precip_label is used. The model_name can contain the path to the files.

Returns

Two files model_name.gpkg which contains the spatial description of the model and model_name_param.json an example parameter file for the model.

`dynatopGIS$get_version()`

get the version number

Usage

dynatopGIS$get_version()

Details

the version number indicates the version of the algorithms within the object

Returns

a numeric version number

`dynatopGIS$clone()`

The objects of this class are cloneable with this method.

Usage

dynatopGIS$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

## The vignettes contains more examples of the method calls.

## create temporary directory for output
demo_dir <- tempfile("dygis")
dir.create(demo_dir)

## locate the dem, channel and catchment outline files
chnFile <- system.file("extdata", "gis", "SwindaleRiverNetwork.gpkg",
                       package="dynatop", mustWork = TRUE)
demFile <- system.file("extdata", "gis", "SwindaleDTM.tif",
                       package="dynatop", mustWork = TRUE)
ctchFile <- system.file("extdata", "gis", "SwindaleBoundary.gpkg",
                        package="dynatop", mustWork = TRUE)

## Preprocess channel data
chn <- terra::vect(chnFile)
chn$slope <- 1e-3
chn$class <- 1
chn$width <- 1
chn$depth <- 0.1
chn <- convert_channel(chn,
                       property_names=c(uid = "identifier",
                                        startNode = "startNode",
                                        endNode = "endNode",
                                        slope = "slope",
                                        class = "class",
                                        width="width",
                                        depth="depth"))
chn <- simplify_channel(chn)

## create a project
dy <- dynatopGIS$new(demo_dir)
## add dem and catchment data
dy$add_catchment(ctchFile, demFile)
## add the channel
dy$add_channel(chn)
## fill the sinks
dy$sink_fill()
## compute the order
dy$order()
## add a new layer
tmp <- dy$get_layer("filled_dem")
tmp <- terra::classify(tmp,5)
names(tmp) <- "alt_band"
dy$add_layer(tmp)
## classify the layer
dy$combine_layers("class_alt_band","alt_band")
## build a model
# \donttest{
dy$create_model(file.path(demo_dir,"new_model"),"class_alt_band") ## create a model
list.files(demo_dir,pattern="new_model*") ## look at the output files for the model
#> [1] "new_model.gpkg"       "new_model_param.json"
# }
## tidy up
unlink(demo_dir)