The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.
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$modelThe 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.
| 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 |
The options vector is a named character vector. Two named variables are used:
transmissivity_profile which defines the transmissivity function used
for the hillslope HRUschannel_solver which defines the channel solution to be usedThe 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.
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 InfThe individual columns are documented in Table 2. Not all the parameters are relevant for each option. See the Hillslope HRU vignette for details.
| 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) |
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 1Many of the columns are not needed and are passed through from the original data. The columns required are documented in Table 3.
| 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 can be specified on the channel HRUs as outlined in Table 4. Gauges are taken to be at the outlet of the channel length.
| 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 1The point_inflow data frame allows the specification for point inflow which are added to the inflow at the head of the channel length.
| 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)The diffuse_inflow data frame allows the specification of diffuse inputs to the channel. These are presumed to occur uniformly along the channel length.
| 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)The flow_direction data frame describes the connections between the HRUs.
| 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.1481338The 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.
| 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 1The 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.
| 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 1These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.