dynatopGIS {dynatopGIS} | R Documentation |
R6 Class for processing a catchment to make a Dynamic TOPMODEL
Description
This package contains the code for setting up a dynamic TOPMODEL implementation
Methods
Public methods
Method new()
Initialise a project, or reopen an existing project
Usage
dynatopGIS$new(meta_file, check = TRUE, verbose = TRUE)
Arguments
meta_file
filename and path of the meta data file
check
logical, should checks be performed [TRUE]
verbose
printing of checking output [TRUE]
Details
This loads the meta data file found at meta_path
, or creates it with a warning if no file is present. It check
is TRUE
then the meta data file contents are checked with the level of returned information being controlled by verbose
.
Returns
A new 'dynatopGIS' object
Method get_meta()
Get project meta data
Usage
dynatopGIS$get_meta()
Method get_working_directory()
Get current working directory
Usage
dynatopGIS$get_working_directory()
Details
Newly generated layers are added to the working directory. By default this is the directory containing the meta date file.
Method set_working_directory()
Set current working directory
Usage
dynatopGIS$set_working_directory(file_path, create = TRUE)
Arguments
file_path
the path to the new directory to create
create
should the directory be created if it doesn't exist
Details
Newly generated layers are added to the working directory. By default this is the directory containing the meta date file.
Method add_dem()
Import a dem to the 'dynatopGIS' object
Usage
dynatopGIS$add_dem(dem, fill_na = TRUE, verbose = FALSE)
Arguments
dem
a
raster
layer object or the path to file containing one which is the DEMfill_na
should NA values in dem be filled. See details
verbose
Should additional progress information be printed
Details
If not a raster
the DEM is read in using the terra package. If fill_na
is TRUE
all NA values other then those that link to the edge of the dem are filled so they can be identified as sinks.
Returns
suitable for chaining
Method add_channel()
Import channel data to the 'dynatopGIS' object
Usage
dynatopGIS$add_channel( channel, property_names = c(length = "length", startNode = "startNode", endNode = "endNode", width = "width"), default_width = 2 )
Arguments
channel
a SpatialLinesDataFrame, SpatialPolygonsDataFrame or file path containing the channel information
property_names
named vector of columns of the spatial data frame to use for channel properties - see details
default_width
default width of a channel if not specified in property_names. Defaults to 2 metres.
Details
Takes the input channel converts it a SpatialPolygonDataFrame with properties length, startNode and endNode. The variable names in the sp_object data frame which corresponding to these properties can be specified in the property_names
vector. In the channel is a SpatialLinesDataFrame (or read in as one) an additional property width is used to buffer the lines and create channel polygons. If required the width property is created using the default value. Note that any columns called length, startNode, endNode and width are overwritten. Any column called id is copied to a column original_id then overwritten.
Returns
suitable for chaining
Method add_layer()
Add a layer of geographical information
Usage
dynatopGIS$add_layer(layer_name, file_path)
Arguments
layer_name
name to give to the layer
file_path
the location of the file containing the new layer
Details
The file given is read by the terra
package and checked against the project meta data. Only layer names not already in use (or reserved) are allowed. If successful the meta data for the project are altered to reflect the new layer name and file location.
Returns
suitable for chaining
Method get_layer()
Get a layer of geographical information or a list of layer names
Usage
dynatopGIS$get_layer(layer_name = character(0))
Arguments
layer_name
name of the layer give to the layer
Returns
a 'raster' layer of the requested information if layer_name is given else a vector of layer names
Method 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
Method 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 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>).
Method compute_areas()
Computes area maps and presence of channel in dem pixels
Usage
dynatopGIS$compute_areas()
Details
The algorithm calculates the land and channel area for each DEM pixel assigning a channel_id to each pixel with a channel area.
Method compute_properties()
Computes statistics e.g. gradient, log(upslope area / gradient) for raster cells
Usage
dynatopGIS$compute_properties(min_grad = 1e-04, verbose = FALSE)
Arguments
min_grad
gradient that can be assigned to a pixel if it can't be computed
verbose
print out additional diagnostic information
Details
The algorithm passed through the cells in decreasing height. Min grad is applied to all cells. It is also used for missing gradients in pixels which are partially channel but have no upslope neighbours.
Method compute_flow_lengths()
Computes flow length for each pixel to the channel
Usage
dynatopGIS$compute_flow_lengths(verbose = FALSE)
Arguments
verbose
print out additional diagnostic information
Details
The algorithm passed through the cells in increasing height. For measures of flow length to the channel are computed. The shortest length (minimum length to channel through any flow path), the dominant length (the length taking the flow direction with the highest fraction for each pixel on the path) and expected flow length (flow length based on sum of downslope flow lengths based on fraction of flow to each cell) and band (strict sequence to ensure that all contributing cell have a higher band value). By definition cells in the channel that have no land area have a length (or band) of NA.
Method classify()
Create a catchment classification based cutting an existing layer into classes
Usage
dynatopGIS$classify(layer_name, base_layer, cuts)
Arguments
layer_name
name of the new layer to create
base_layer
name of the layer to be cut into classes
cuts
values on which to cut into classes. These should be numeric and define either the number of bands (single value) or breaks between band (multiple values).
Details
This applies the given cuts to the supplied landscape layer to produce areal groupings of the catchment. Cuts are implement using terra::cut
with include.lowest = TRUE
. Note that is specifying a vector of cuts values outside the limits will be set to NA.
Method combine_classes()
Combine any number of classifications based on unique combinations and burns
Usage
dynatopGIS$combine_classes(layer_name, pairs, burns = NULL)
Arguments
layer_name
name of the new layer to create
pairs
a vector of layer names to combine into new classes through unique combinations. Names should correspond to raster layers in the project directory.
burns
a vector of layer names which are to be burnt on
Details
This applies the given cuts to the supplied landscape layers to produce areal groupings of the catchment. Burns are added directly in the order they are given. Cuts are implement using terra::cut
with include.lowest = TRUE
. Note that is specifying a vector of cuts values outside the limits will be set to NA.
Method create_model()
Compute a Dynamic TOPMODEL
Usage
dynatopGIS$create_model( layer_name, class_layer, dist_layer, transmissivity = c("exp", "bexp", "cnst", "dexp"), channel_solver = c("histogram"), dist_delta = 0, rain_layer = NULL, rain_label = character(0), pet_layer = NULL, pet_label = character(0), verbose = FALSE )
Arguments
layer_name
name for the new model and layers
class_layer
the layer defining the topographic classes
dist_layer
the layer defining the distances to the channel
transmissivity
transmissivity profile to use
channel_solver
channel solver to use
dist_delta
used in computing flow linkages see details
rain_layer
the layer defining the rainfall inputs
rain_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 define the HRUs. Flow between HRUs is based on the distance to a channel. For each HRU the shortest distance to a channel is computed. Flow from a HRU can only go to a HRU with a lower shortest distance to the channel. Flow from a HRU can occur from any raster cell within the HRU whose distance to the channel is within dist_delta of the shortest distance within the HRU.
Setting the transmissivity and channel_solver options ensure the model is set up with the correct parameters present.
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 weights used to compute an averaged input value for each HRU are computed, otherwise an input table for the models generated with the value "missing" used in place of the series name.
Method 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
Method get_class_method()
get the cuts and burns used to classify
Usage
dynatopGIS$get_class_method(layer_name)
Arguments
layer_name
the name of layer whose classification method is returned
Returns
a list with two elements, cuts and burns
Method 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 temport directory for output
demo_dir <- tempfile("dygis")
dir.create(demo_dir)
## initialise processing
ctch <- dynatopGIS$new(file.path(demo_dir,"meta.json"))
## add digital elevation and channel data
dem_file <- system.file("extdata", "SwindaleDTM40m.tif", package="dynatopGIS", mustWork = TRUE)
dem <- terra::rast(dem_file)
ctch$add_dem(dem)
channel_file <- system.file("extdata", "SwindaleRiverNetwork.shp",
package="dynatopGIS", mustWork = TRUE)
sp_lines <- terra::vect(channel_file)
property_names <- c(channel_id="identifier",endNode="endNode",startNode="startNode",length="length")
ctch$add_channel(sp_lines,property_names)
## compute properties
ctch$compute_areas()
ctch$sink_fill() ## fill sinks in the catchment
ctch$compute_properties() # like topograpihc index and contour length
ctch$compute_flow_lengths()
## classify and create a model
ctch$classify("atb_20","atb",cuts=20) # classify using the topographic index
ctch$get_class_method("atb_20") ## see the details of the classification
ctch$combine_classes("atb_20_band",c("atb_20","band")) ## combine classes
ctch$create_model("new_model","atb_20_band","band") ## create a model
list.files(demo_dir,pattern="new_model*") ## look at the output files for the model
## tidy up
unlink(demo_dir)