db_check: Check and modify parameter database for consistency
In tpilz/lumpR: Landscape Unit Mapping Program for R
db_check R Documentation
Check and modify parameter database for consistency
Description
Function includes several options to check and correct the parameter database for completeness
and consistency.
Usage
db_check(dbname, check = c("check_fix_fractions", "filter_small_areas",
"tc_slope", "special_areas", "remove_water_svc", "compute_rocky_frac",
"remove_impervious_svc", "proxy_frgw_delay", "delete_obsolete",
"completeness", "subbasin_order"), option = list(area_thresh = 0.01,
treat_slope = c(3, 0.01, 0.1), update_frac_impervious = F, overwrite = F,
tbls_preserve = NULL), fix = F, verbose = TRUE)
Arguments
dbname
Name of the data source (DSN) registered as ODBC-source.
check
Character vector specifying what shall be checked. See Details.
option
A list of options for certain checks. See Details
for the different options and their meaning.
fix
logical. If FALSE (the default) a report of the
selected checks will be created. The database will not be modified. If TRUE,
changes to the database according to the selected checks will be made.
WARNING: fix = TRUE may irrevocably modify your database. If in doubt, make a backup before.
verbose
logical. Should detailed information during execution be
printed? When TRUE (the default), output of writing updated values
into database can be rather long so you might want to direct output into an
external log file. Always set to TRUE if fix = FALSE.
Details
The following checks / modifications are currently included and can be specified via argument checks.
Execute checks in pre-defined order as some steps build upon each other and
lead to erroneous results when interchanged. However, some steps might be
unnecessary for your purpose and can be left out.
check_fix_fractions
Check/fix that the fractions of all sub-entities sum to 1.
filter_small_areas
Tiny areas as result of landscape disaggregation considered irrelevant during model
application will be removed and the areal fractions updated accordingly. The model
will run faster by removing unnecessary computational burden. Namely, this affects LUs
within subbasins, TCs within LUs and SVCs within TCs.
If the fraction to be removed is greater than 10 % of the total area of the next higher
spatial level's class, datasets will be kept. In this case you might try a smaller value for area_thresh'.
Option: 'area_thresh'
A threshold defining the minimum areal fraction of a certain spatial disaggregation
unit within the next higher spatial level (e.g. LUs within subbasins). Default: 0.01.
tc_slope
In WASA (and other models probably as well) slopes equal to or less than zero are
not allowed. This check helps to identify such TCs and provides the following option
to solve the issue:
Option: 'treat_slope'
A numeric vector with two or three elements:
The first being one of {1,2,3}:
1: Remove TCs with slope <= 0 from 'r_lu_contains_tc' whereas areal fraction within
the LU must be smaller than a defined threshold (second value of the vector).
2: Where slope is 0, change it to small positive value specified as second
value of the vector (interpreted as slope in %).
3: A combination of the two former choices whereas option 1 is applied before
option 2, the second value of the vector defining the areal threshold and the
third giving the slope replacement value. This is the default setting with
threshold = 0.01 and slope = 0.1 %.
special_areas
(This check is unnecessary if you specified watermask) and imperviousmask in the workflow before)
Define certain Soil-Vegetation Components as special areas via column 'special_area'
in table 'soil_veg_components' inferred from table 'vegetation' and/or 'soils'. This columns is
necessary for remove_water_svc and compute_rocky_frac to work.
Currently values '0' for an ordinary SVC, '1' for water areas, and '2' for
impervious surfaces are supported.
Option: 'special_area'
A data.frame with 3 named vectors:
'reference_tbl': character giving the name(s) of the database table(s)
containing the special area(s) to be mapped to SVCs. Tables 'vegetation' and
'soils' are supported.
'ref_id': integer giving the 'pid' of the special area within the specified
reference table.
'special_id': integer giving the flag of column 'special_area' in table
'soil_veg_components'. Currently recognised in further processing are '0' for
ordinary SVCs, '1' for water areas, and '2' for impervious surfaces.
For instance, if within table 'vegetation' you have classes with pid 3 and 4
indicating water surfaces and in 'soils' pid 10 is an impervious surface
specify the following: special_area = data.frame(reference_tbl=
c("vegetation", "vegetation", "soils"), ref_id=c(3,4,10), special_id=c(1,1,2)).
remove_water_svc
Remove SVCs marked as water from table 'r_tc_contains_svc', i.e. those SVCs where
in table 'soil_veg_components' column 'special_area' is equal to 1. Areal fractions
will be updated (normalized to 1). Requires column 'special_area' to be set correctly
(e.g. by running option 'special_area' before)
compute_rocky_frac
Compute rocky fractions, i.e. fractions of impervious surfaces, for TCs (table
'terrain_components', column 'frac_rocky') from impervious SVCs (column 'special_area'
in 'soil_veg_components' equal to 2) and topmost soil horizons (in table horizons'
column 'position' equal to 1 and 'coarse_frag' equal to 1). These undergo special
treatment in the WASA model. SVCs with soil profile containing 100% coarse
fragments in topmost horizon will be marked as impervious.
If the column 'frac_rocky' already contains values, the computed values are added to these.
In any case, this step should be followed by 'remove_impervious_svc'.
remove_impervious_svc
Remove SVCs marked as impervious from table 'r_tc_contains_svc', i.e. those SVCs where
in table 'soil_veg_components' column 'special_area' is equal to 2.
Option: 'update_frac_impervious'
Value of type logical:
FALSE (default): Areal fractions will not be updated. I.e., the sum of 'fraction' for a specific
'tc_id' plus 'frac_rocky' of table 'terrain_components' of that specific TC (calculated by
check 'compute_rocky_frac') sums up to unity. This is a requirement of the WASA-SED model.
TRUE: Areal fractions will be updated such that 'fraction' for a specific 'tc_id' sums to unity.
proxy_frgw_delay
Estimate storage coefficient for groundwater delay ('frgw_delay') in days
for each LU based on a proxy and manually specified total mean groundwater delay
in days. The proxy is estimated from average slope length, slope and rocky
fraction according to empirical formulas:
proxy = slopelength * (1 - frac_rocky) / slope. and
frgw_delay = proxy * total_mean_delay / mean(proxy).
Existing values of 'frgw_delay' will be overwritten.
Option: 'total_mean_delay'
Total mean groundwater delay in days estimated a priori for the whole
catchment (e.g. from baseflow analysis). All proxy values are scaled, so their
mean matches this value (see formula above).
delete_obsolete
Check for (and optionally delete) obsolete datasets. I.e. LUs not in any subbasin, TCs
not in any LU, SVCs not in any TC from the contains- and the parent tables,
and datasets in 'rainy_season' with obsolete subbasins (if table 'rainy_season' exists).
Dependencies are respected. Areal fractions will be updated in case obsolete datasets are removed.
Option: 'tbls_preserve'
Vector of type character giving the names of tables where obsolete datasets will NOT be removed.
Default: NULL.
completeness
Check database for completeness. I.e. check if all entities in a higher hierarchy are used and specified in the related tables
of lower hierarchy. Reports only, ignores fix=T and does no changes to the database.
subbasin_order
Compute subbasin order for WASA's routing input file routing.dat. Order will
be derived from column 'drains_to' and written to 'a_stream_order' of table 'subbasins'.
Option: 'overwrite': Overwrite existing vaues.
Note
In case the default value of option 'update_frac_impervious' shall NOT be used,
you should always explicitly specify it, even when check 'remove_impervious_svc' is not applied,
to make sure, 'fraction' of table 'r_tc_contains_svc' is always correctly calculated.
Database will only be touched (if fix = TRUE) after all checks are completed successfully.
If the function stops with an error during checks, the database will be left unchanged.
Author(s)
Tobias Pilz tpilz@uni-potsdam.de, Till Francke francke@uni-potsdam.de
References
lumpR package introduction with literature study and sensitivity analysis:
Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating
landscape discretisation for hillslope-based hydrological models.
Geosci. Model Dev., 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017
Examples
## Not run:
db_check(dbname,
check=c("subbasin_order"),
fix=TRUE,
verbose=T, option=list(overwrite=FALSE))
## End(Not run)
tpilz/lumpR documentation built on Aug. 5, 2023, 1:31 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| db_check | R Documentation |
Check and modify parameter database for consistency
Description
Function includes several options to check and correct the parameter database for completeness and consistency.
Usage
db_check(dbname, check = c("check_fix_fractions", "filter_small_areas",
"tc_slope", "special_areas", "remove_water_svc", "compute_rocky_frac",
"remove_impervious_svc", "proxy_frgw_delay", "delete_obsolete",
"completeness", "subbasin_order"), option = list(area_thresh = 0.01,
treat_slope = c(3, 0.01, 0.1), update_frac_impervious = F, overwrite = F,
tbls_preserve = NULL), fix = F, verbose = TRUE)
Arguments
dbname |
Name of the data source (DSN) registered as ODBC-source. |
check |
Character vector specifying what shall be checked. See |
option |
A list of options for certain checks. See |
fix |
|
verbose |
|
Details
The following checks / modifications are currently included and can be specified via argument checks.
Execute checks in pre-defined order as some steps build upon each other and
lead to erroneous results when interchanged. However, some steps might be
unnecessary for your purpose and can be left out.
check_fix_fractions
Check/fix that the fractions of all sub-entities sum to 1.
filter_small_areas
Tiny areas as result of landscape disaggregation considered irrelevant during model
application will be removed and the areal fractions updated accordingly. The model
will run faster by removing unnecessary computational burden. Namely, this affects LUs
within subbasins, TCs within LUs and SVCs within TCs.
If the fraction to be removed is greater than 10 % of the total area of the next higher
spatial level's class, datasets will be kept. In this case you might try a smaller value for area_thresh'.
Option: 'area_thresh'
A threshold defining the minimum areal fraction of a certain spatial disaggregation
unit within the next higher spatial level (e.g. LUs within subbasins). Default: 0.01.
tc_slope
In WASA (and other models probably as well) slopes equal to or less than zero are
not allowed. This check helps to identify such TCs and provides the following option
to solve the issue:
Option: 'treat_slope'
A numeric vector with two or three elements:
The first being one of {1,2,3}:
1: Remove TCs with slope <= 0 from 'r_lu_contains_tc' whereas areal fraction within
the LU must be smaller than a defined threshold (second value of the vector).
2: Where slope is 0, change it to small positive value specified as second
value of the vector (interpreted as slope in %).
3: A combination of the two former choices whereas option 1 is applied before
option 2, the second value of the vector defining the areal threshold and the
third giving the slope replacement value. This is the default setting with
threshold = 0.01 and slope = 0.1 %.
special_areas
(This check is unnecessary if you specified watermask) and imperviousmask in the workflow before)
Define certain Soil-Vegetation Components as special areas via column 'special_area'
in table 'soil_veg_components' inferred from table 'vegetation' and/or 'soils'. This columns is
necessary for remove_water_svc and compute_rocky_frac to work.
Currently values '0' for an ordinary SVC, '1' for water areas, and '2' for
impervious surfaces are supported.
Option: 'special_area'
A data.frame with 3 named vectors:
'reference_tbl': character giving the name(s) of the database table(s)
containing the special area(s) to be mapped to SVCs. Tables 'vegetation' and
'soils' are supported.
'ref_id': integer giving the 'pid' of the special area within the specified
reference table.
'special_id': integer giving the flag of column 'special_area' in table
'soil_veg_components'. Currently recognised in further processing are '0' for
ordinary SVCs, '1' for water areas, and '2' for impervious surfaces.
For instance, if within table 'vegetation' you have classes with pid 3 and 4
indicating water surfaces and in 'soils' pid 10 is an impervious surface
specify the following: special_area = data.frame(reference_tbl=
c("vegetation", "vegetation", "soils"), ref_id=c(3,4,10), special_id=c(1,1,2)).
remove_water_svc
Remove SVCs marked as water from table 'r_tc_contains_svc', i.e. those SVCs where
in table 'soil_veg_components' column 'special_area' is equal to 1. Areal fractions
will be updated (normalized to 1). Requires column 'special_area' to be set correctly
(e.g. by running option 'special_area' before)
compute_rocky_frac
Compute rocky fractions, i.e. fractions of impervious surfaces, for TCs (table
'terrain_components', column 'frac_rocky') from impervious SVCs (column 'special_area'
in 'soil_veg_components' equal to 2) and topmost soil horizons (in table horizons'
column 'position' equal to 1 and 'coarse_frag' equal to 1). These undergo special
treatment in the WASA model. SVCs with soil profile containing 100% coarse
fragments in topmost horizon will be marked as impervious.
If the column 'frac_rocky' already contains values, the computed values are added to these.
In any case, this step should be followed by 'remove_impervious_svc'.
remove_impervious_svc
Remove SVCs marked as impervious from table 'r_tc_contains_svc', i.e. those SVCs where
in table 'soil_veg_components' column 'special_area' is equal to 2.
Option: 'update_frac_impervious'
Value of type logical:
FALSE (default): Areal fractions will not be updated. I.e., the sum of 'fraction' for a specific
'tc_id' plus 'frac_rocky' of table 'terrain_components' of that specific TC (calculated by
check 'compute_rocky_frac') sums up to unity. This is a requirement of the WASA-SED model.
TRUE: Areal fractions will be updated such that 'fraction' for a specific 'tc_id' sums to unity.
proxy_frgw_delay
Estimate storage coefficient for groundwater delay ('frgw_delay') in days
for each LU based on a proxy and manually specified total mean groundwater delay
in days. The proxy is estimated from average slope length, slope and rocky
fraction according to empirical formulas:
proxy = slopelength * (1 - frac_rocky) / slope. and
frgw_delay = proxy * total_mean_delay / mean(proxy).
Existing values of 'frgw_delay' will be overwritten.
Option: 'total_mean_delay'
Total mean groundwater delay in days estimated a priori for the whole
catchment (e.g. from baseflow analysis). All proxy values are scaled, so their
mean matches this value (see formula above).
delete_obsolete
Check for (and optionally delete) obsolete datasets. I.e. LUs not in any subbasin, TCs
not in any LU, SVCs not in any TC from the contains- and the parent tables,
and datasets in 'rainy_season' with obsolete subbasins (if table 'rainy_season' exists).
Dependencies are respected. Areal fractions will be updated in case obsolete datasets are removed.
Option: 'tbls_preserve'
Vector of type character giving the names of tables where obsolete datasets will NOT be removed.
Default: NULL.
completeness
Check database for completeness. I.e. check if all entities in a higher hierarchy are used and specified in the related tables
of lower hierarchy. Reports only, ignores fix=T and does no changes to the database.
subbasin_order
Compute subbasin order for WASA's routing input file routing.dat. Order will
be derived from column 'drains_to' and written to 'a_stream_order' of table 'subbasins'.
Option: 'overwrite': Overwrite existing vaues.
Note
In case the default value of option 'update_frac_impervious' shall NOT be used, you should always explicitly specify it, even when check 'remove_impervious_svc' is not applied, to make sure, 'fraction' of table 'r_tc_contains_svc' is always correctly calculated.
Database will only be touched (if fix = TRUE) after all checks are completed successfully.
If the function stops with an error during checks, the database will be left unchanged.
Author(s)
Tobias Pilz tpilz@uni-potsdam.de, Till Francke francke@uni-potsdam.de
References
lumpR package introduction with literature study and sensitivity analysis:
Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating
landscape discretisation for hillslope-based hydrological models.
Geosci. Model Dev., 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017
Examples
## Not run:
db_check(dbname,
check=c("subbasin_order"),
fix=TRUE,
verbose=T, option=list(overwrite=FALSE))
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.