The Model Object

The purpose of this vignette is to document the structure of a Dynamic TOPMODEL model ‘object’; that is the structure of the model that can be generated in the dynatopGIS package and is used in calls to the dynatop function in the current package. Currently the model is stored as an R variable of the list class.

This should be read alongside the “Getting Started” vignette which demonstrates the manipulation and use of a model object.

The model structure will be documented with reference to the model in the test catchment data supplied with the package. This can be loaded with

library(dynatop)
data("Swindale")
model <- Swindale$model

The top level of the model contains the following elements:

names(model)
#>  [1] "options"        "map"            "channel"        "hillslope"     
#>  [5] "flow_direction" "gauge"          "point_inflow"   "diffuse_inflow"
#>  [9] "precip_input"   "pet_input"

These are outlined in Table 1 and described in more detail in the sections below.

Table 1: Description of top-level model components
Name Class Description
options character vector Options defining the model
hillslope data.frame Description of the hill slope HRU units
channel data.frame Description of the channel HRU units
gauge data.frame Description of the gauge locations on the channel network
point_inflow data.frame Description of the point inflows to the channel network
diffuse_inflow data.frame Description of the diffuse inflows to the channel network
flow_direction data.frame Description of the flow linkages between HRUs
precip_input data.frame Description of the precipitation input to the HRUs
pet_input data.frame Description of the PET input to the HRUs
map list Location of files for creating plots of the HRUs

Options

The options vector is a named character vector. Two named variables are used:

The columns present in the hillslope and channel data.frames will depend upon the value taken by these options. See the hillslope and channel vignettes for further details.

Hillslope HRU table

Each row of the hillslope table describes a single hillslope HRU. In this example it looks like:

head(model$hillslope)
#>   id      area   atb_bar      s_bar min_dst width s_sf s_rz s_uz s_sz
#> 1 20  1451.820  9.121463 0.28916356       1    40   NA   NA   NA   NA
#> 2 21  5911.932  9.598746 0.36701868       1   160   NA   NA   NA   NA
#> 3 22 16356.278 10.264301 0.26385821       1   440   NA   NA   NA   NA
#> 4 23 23625.880 10.824251 0.18010123       1   640   NA   NA   NA   NA
#> 5 24 48632.930 11.497418 0.15906415       1  1320   NA   NA   NA   NA
#> 6 25 75373.071 12.106720 0.09886103       1  2040   NA   NA   NA   NA
#>   cls_atb_20_band cls_atb_20 cls_band opt r_sfmax c_sf s_rzmax  t_d ln_t0 c_sz
#> 1               1          1        1 exp     Inf  0.1    0.05 7200    -2   NA
#> 2               2          2        1 exp     Inf  0.1    0.05 7200    -2   NA
#> 3               3          3        1 exp     Inf  0.1    0.05 7200    -2   NA
#> 4               4          4        1 exp     Inf  0.1    0.05 7200    -2   NA
#> 5               5          5        1 exp     Inf  0.1    0.05 7200    -2   NA
#> 6               8          6        1 exp     Inf  0.1    0.05 7200    -2   NA
#>      m  D m_2 omega s_rz0 r_uz_sz0 s_raf t_raf
#> 1 0.04 NA  NA    NA  0.75    1e-06     0   Inf
#> 2 0.04 NA  NA    NA  0.75    1e-06     0   Inf
#> 3 0.04 NA  NA    NA  0.75    1e-06     0   Inf
#> 4 0.04 NA  NA    NA  0.75    1e-06     0   Inf
#> 5 0.04 NA  NA    NA  0.75    1e-06     0   Inf
#> 6 0.04 NA  NA    NA  0.75    1e-06     0   Inf

The individual columns are documented in Table 2. Not all the parameters are relevant for each option. See the Hillslope HRU vignette for details.

Table 2: Description of hillslope data frame columns
Name Class Unit Description
id integer - Unique identifying number of the HRU. These combined with the HRU numbers in the channel table should be unique and take values 1,2,3…
area numeric m\(^2\) Surface area of the HRU
atb_bar numeric ?? Topographic index, log if the upslope area divided by tangent of gradient
s_bar numeric - Average gradient
min_dst numeric -[m] Minimum distance from HRU to a channel from the distance metric used in the model generation
width numeric m Contour length of downslope end of HRU
s_sf numeric m Surface Zone storage volume per unit area (state)
s_rz numeric m Root Zone storage volume per unit area (state)
s_uz numeric m Unsaturated Zone storage volume per unit area (state)
s_sz numeric m Saturated Zone storage deficit per unit area (state)
cls_* integer - Classification of HRU in each of the classes used in its definition. The extra part of the name matches the class name given in dynatopGIS
opt character - Option controlling the type of Hillslope HRU. Currently defines the transmissivity profile.
r_sfmax numeric m/s Maximum flow rate from surface to root zone (parameter)
c_sf numeric m/s Celerity of the surface excess storage (parameter)
s_rzmax numeric m Maximum root zone depth (parameter)
t_d numeric s/m Unsaturated zone time constant given per \(m\) of saturated storage deficit (parameter)
ln_t0 numeric m/s Log of the soil saturated conductivity (parameter)
m numeric - Exponential transmissivity decay parameter (parameter)
m_2 numeric - Second Exponential transmissivity decay parameter (parameter)
omega numeric 0-1 Weighting between the two transmissivity parameters (parameter)
c_sz numeric m/s Constant saturated zone celerity (parameter)
s_rz0 numeric 0-1 Initial root zone depth expressed as fraction of maximum depth (parameter)
r_uz_sz0 numeric m/s Initial recharge to the saturated zone per unit area (parameter)

Channel HRU table

Each row of the channel HRU table describes a single channel HRU. In this example it looks like:

head(model$channel)
#>                  name1                           identifier
#> 0        Hawthorn Gill 16D0AC09-E0B6-4727-83B8-567E8DE9C533
#> 1 Little Mosedale Beck 643017BB-01BC-4738-898F-1C62B84164BF
#> 2        Mosedale Beck D2C2703E-A32F-4D88-A022-4E27EA52FC5C
#> 3                 <NA> 991D9896-CA0C-492F-A6EE-8BA3972DDA3C
#> 4                 <NA> CC8639D7-00D2-4C26-9252-350E5A748D51
#> 5                 <NA> ED03FEDD-0F4B-40C7-86E8-6F0EA8BAC182
#>                              startNode                              endNode
#> 0 730F01D2-0F4F-4E27-AF55-B1782F0F844B 72B1A40B-E106-42A9-A261-4B7720037ADB
#> 1 9B06188C-F4C7-436C-8108-3956D5FFD5CD A19E0D3A-2FA1-4E6D-AEA4-472F91ABC2AC
#> 2 B03DB3BD-0E33-4E10-A935-997832752609 D649B60C-E631-47FA-971E-CA388DBDDE63
#> 3 D968F174-FB80-404A-A4A7-2862CC722482 1FDBFCFF-799C-41CF-A2CB-8A56368BD438
#> 4 1FDBFCFF-799C-41CF-A2CB-8A56368BD438 7C251581-3764-4DEE-8031-EC98FABC1F87
#> 5 D3A1AEA9-93A6-4ACF-9A11-363F9517723F 673269DF-9E48-4EA0-B439-3D565A023DD2
#>          form         flow fictitious length name2 sinkdepth Shape_Leng width
#> 0 inlandRiver in direction      false    431  <NA>        -1  431.30438     2
#> 1 inlandRiver in direction      false    513  <NA>        -1  513.12806     2
#> 2 inlandRiver in direction      false    740  <NA>        -1  739.76378     2
#> 3 inlandRiver in direction      false    573  <NA>        -1  573.48312     2
#> 4 inlandRiver in direction      false     29  <NA>        -1   29.18951     2
#> 5 inlandRiver in direction      false    413  <NA>        -1  413.14877     2
#>                             channel_id id area v_ch
#> 0 16D0AC09-E0B6-4727-83B8-567E8DE9C533  2   24    1
#> 1 643017BB-01BC-4738-898F-1C62B84164BF 17  255    1
#> 2 D2C2703E-A32F-4D88-A022-4E27EA52FC5C 11  242    1
#> 3 991D9896-CA0C-492F-A6EE-8BA3972DDA3C  7  126    1
#> 4 CC8639D7-00D2-4C26-9252-350E5A748D51  6    6    1
#> 5 ED03FEDD-0F4B-40C7-86E8-6F0EA8BAC182 12  168    1

Many of the columns are not needed and are passed through from the original data. The columns required are documented in Table 3.

Table 3: Description of channel data frame columns
Name Class Unit Description
id integer - Unique identifying number of the channel HRU. These, combined with the id from the hillslope table should for consecutive integers increasing from 1.
area numeric m\(^2\) Surface area of the HRU in m\(^2\)
length numeric m Length of the channel in metres
v_ch numeric m/s Channel velocity parameter

Gauge locations

Gauge locations can be specified on the channel HRUs as outlined in Table 4. Gauges are taken to be at the outlet of the channel length.

Table 4: Description of gauge data frame columns
Name Class Unit Description
name character - Unique name to identify the gauge. Used to name the output series
id integer - The id of the channel HRU on which the gauge is sited

In this case there is a single gauge at the outlet:

model$gauge
#>        name id
#> 1 channel_1  1

Point Inflows

The point_inflow data frame allows the specification for point inflow which are added to the inflow at the head of the channel length.

Table 5: Description of point_inflow data frame columns
Name Class Unit Description
name character - Name of the input series to use.
id integer - The id of the channel HRU to which the inflow is added

In the current catchment there are no inflows so the table is left blank:

model$point_inflow
#> [1] name id  
#> <0 rows> (or 0-length row.names)

Diffuse Inflows

The diffuse_inflow data frame allows the specification of diffuse inputs to the channel. These are presumed to occur uniformly along the channel length.

Table 6: Description of diffuse_inflow data frame columns
Name Class Unit Description
name character - Name of the input series to use.
id integer - The id of the channel HRU to which the inflow is added

In the current catchment there are no inflows so the table is left blank:

model$diffuse_inflow
#> [1] name id  
#> <0 rows> (or 0-length row.names)

Flow direction

The flow_direction data frame describes the connections between the HRUs.

Table 7: Description of flow_direction data frame columns
Name Class Unit Description
from integer - id of the HRU which the flow comes from
to integer - id of the HRU to which the flow is going
frc numeric 0-1 Fraction of the flow which goes from the from id to the to id

The start of the data frame in the current example is:

head(model$flow_direction)
#>        from   to       frc
#> 18502  1853 1850 0.3033095
#> 185110 1853 1851 0.4704486
#> 1852   1853 1852 0.2262419
#> 18492  1852 1849 0.3781666
#> 18501  1852 1850 0.4736997
#> 1851   1852 1851 0.1481338

Precipitation input

The precip_input data frame describes the precipitation series to use for each HRU. Each row contains a HRU id, the series to use and the fraction of the HRU to which this series should be applied. From this an average precipitation for each HRU is derived.

Table 8: Description of precip_input data frame columns
Name Class Unit Description
id integer - The id of the channel HRU to which the input is applied
name character - Name of the input series to use.
frc numeric 0-1 The fraction of the HRU area for which the input series is valid

In the current example there is a single precipitation series being used:

head(model$precip_input)
#>       name id frc
#> 1 Rainfall  2   1
#> 2 Rainfall 17   1
#> 3 Rainfall 11   1
#> 4 Rainfall  7   1
#> 5 Rainfall  6   1
#> 6 Rainfall 12   1

PET input

The pet_input data frame describes the potential evapotranspiration series to use for each HRU. Each row contains a HRU id, the series to use and the fraction of the HRU to which this series should be applied. From this an average PET value for each HRU is derived.

Table 9: Description of pet_input data frame columns
Name Class Unit Description
id integer - The id of the channel HRU to which the input is applied
name character - Name of the input series to use.
frc numeric 0-1 The fraction of the HRU area for which the input series is valid

In the current example there is a single PET series being used:

head(model$pet_input)
#>   name id frc
#> 1  PET  2   1
#> 2  PET 17   1
#> 3  PET 11   1
#> 4  PET  7   1
#> 5  PET  6   1
#> 6  PET 12   1