├── .Rbuildignore ├── src ├── RainySeason.f └── calc_seasonality.f90 ├── .gitignore ├── example ├── make_wasa_input │ ├── templ │ │ ├── svc.dat │ │ ├── terrain.dat │ │ ├── response.dat │ │ ├── horizon_particles.dat │ │ ├── part_class.dat │ │ ├── svc_in_tc.dat │ │ ├── soil_particles.dat │ │ ├── routing.dat │ │ ├── hymo.dat │ │ ├── soter.dat │ │ ├── rainy_season.dat │ │ ├── soil.dat │ │ ├── vegetation.dat │ │ ├── do.dat │ │ └── soil_vegetation.dat │ ├── sql_lib_odbc.php │ ├── sql_lib_mysql.php │ ├── Make_wasa_input_manual.doc │ ├── README │ ├── check_db_version.php │ └── settings.php └── data_import.sh ├── R ├── zzz.R ├── calc_seasonality.R ├── internals.R ├── rainy_season.R ├── db_extract_subcatch.R ├── db_create.R ├── disc_wrapper.R └── reservoir_outlet.R ├── inst └── database │ ├── update_db_v27.sql │ ├── update_db_v24.sql │ ├── update_db_v22.sql │ ├── update_db_v20.sql │ ├── update_db_v19.sql │ ├── update_db_v25.sql │ ├── update_db_v21.sql │ ├── update_db_v23.sql │ ├── update_db_v26.sql │ ├── update_db_v28.sql │ └── create_db.sql ├── LUMP.Rproj ├── NAMESPACE ├── DESCRIPTION ├── man ├── db_update.Rd ├── db_extract_subcatch.Rd ├── calc_seasonality.Rd ├── db_create.Rd ├── db_prepare_musle.Rd ├── rainy_season.Rd ├── reservoir_outlet.Rd ├── disc_wrapper.Rd ├── prof_class.Rd ├── reservoir_lumped.Rd ├── db_echse_input.Rd ├── reservoir_strategic.Rd ├── area2catena.Rd ├── calc_subbas.Rd ├── lump_grass_prep.Rd ├── db_wasa_input.Rd ├── db_check.Rd └── lump_grass_post.Rd └── README.md /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^.*\.Rproj$ 2 | ^\.Rproj\.user$ 3 | -------------------------------------------------------------------------------- /src/RainySeason.f: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tpilz/lumpR/HEAD/src/RainySeason.f -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .* 2 | *.[oa] 3 | *.mod 4 | *.so 5 | *~ 6 | .Rproj.user 7 | *.Rproj 8 | *.dll 9 | -------------------------------------------------------------------------------- /example/make_wasa_input/templ/svc.dat: -------------------------------------------------------------------------------- 1 | Specifications of soil vegetation components and erosion parameters 2 | -------------------------------------------------------------------------------- /R/zzz.R: -------------------------------------------------------------------------------- 1 | .onLoad <- function(libname, pkgname) { 2 | #rgrass7::use_sp() # make sure sp instead of sf is used 3 | } -------------------------------------------------------------------------------- /example/make_wasa_input/templ/terrain.dat: -------------------------------------------------------------------------------- 1 | Specification of terrain components 2 | TC-ID fraction slope[%] position[-] 3 | -------------------------------------------------------------------------------- /example/make_wasa_input/sql_lib_odbc.php: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tpilz/lumpR/HEAD/example/make_wasa_input/sql_lib_odbc.php -------------------------------------------------------------------------------- /example/make_wasa_input/templ/response.dat: -------------------------------------------------------------------------------- 1 | Specification of routing parameter 2 | Subbasin-ID, lag time [d], retention [d] 3 | -------------------------------------------------------------------------------- /example/make_wasa_input/sql_lib_mysql.php: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tpilz/lumpR/HEAD/example/make_wasa_input/sql_lib_mysql.php -------------------------------------------------------------------------------- /example/make_wasa_input/templ/horizon_particles.dat: -------------------------------------------------------------------------------- 1 | Particle size distribution of horizons 2 | horizon_id class_number fraction[-] 3 | -------------------------------------------------------------------------------- /example/make_wasa_input/templ/part_class.dat: -------------------------------------------------------------------------------- 1 | Particle size classes to be used in sediment modelling 2 | class_number upper_limit[mm] 3 | -------------------------------------------------------------------------------- /example/make_wasa_input/templ/svc_in_tc.dat: -------------------------------------------------------------------------------- 1 | Specification of which SVCs are contained in each TC 2 | TC-ID[-] SVC-ID[-] fraction[-] 3 | -------------------------------------------------------------------------------- /example/make_wasa_input/Make_wasa_input_manual.doc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tpilz/lumpR/HEAD/example/make_wasa_input/Make_wasa_input_manual.doc -------------------------------------------------------------------------------- /example/make_wasa_input/templ/soil_particles.dat: -------------------------------------------------------------------------------- 1 | Particle size distribution of topmost horizons of soils 2 | soil_id part_class_id fraction[-] 3 | -------------------------------------------------------------------------------- /example/make_wasa_input/templ/routing.dat: -------------------------------------------------------------------------------- 1 | Specification of routing order (flow directions) 2 | No., Subasin-ID(upstream), Subasin-ID(downstream) 3 | -------------------------------------------------------------------------------- /example/make_wasa_input/templ/hymo.dat: -------------------------------------------------------------------------------- 1 | Specification of the sub-basins and their total number, type and areal fraction of SOTER units 2 | Subasin-ID[-] Area[km**2] nbr[-] LU-ID[-] areal_fraction_of_LU[-] 3 | -------------------------------------------------------------------------------- /example/make_wasa_input/README: -------------------------------------------------------------------------------- 1 | This directory contains the old php program to generate WASA inut files based on 2 | a parameter database written by Till Francke. See Make_wasa_input_manual.doc for 3 | more information. -------------------------------------------------------------------------------- /example/make_wasa_input/templ/soter.dat: -------------------------------------------------------------------------------- 1 | Specification of landscape units 2 | LU-ID[id] No._of_TC[-] TC1[id] TC2[id] TC3[id] kfsu[mm/d] length[m] meandep[mm] maxdep[mm] riverbed[mm] gwflag[0/1] gw_dist[mm] frgw_delay[day] 3 | -------------------------------------------------------------------------------- /example/make_wasa_input/templ/rainy_season.dat: -------------------------------------------------------------------------------- 1 | Specification of the rainy/growing season (per year) 2 | for the interpolation of temporal distribution of vegetation characteristics (Rootdepth,height,lai,albedo) 3 | Subasin Veg_id Year DOY1 DOY2 DOY3 DOY4 4 | -------------------------------------------------------------------------------- /inst/database/update_db_v27.sql: -------------------------------------------------------------------------------- 1 | ALTER TABLE horizons MODIFY shrinks TINYINT(1) NULL DEFAULT 0; 2 | 3 | INSERT INTO db_version VALUES ( 4 | 27, 5 | 27, 6 | 'corrected default value for column shrinks', 7 | 'horizons', 8 | 'none', 9 | '', 10 | '2018-11-12 11:00:00'); 11 | 12 | -------------------------------------------------------------------------------- /example/make_wasa_input/templ/soil.dat: -------------------------------------------------------------------------------- 1 | Specification of soil parameters 2 | Soil-ID[-] number(horizons)[-] (n_res[Vol-] n_PWP[-] n_FK63[-] n_FK1.8[-] n_nFK[-] n_saturated[-] n_thickness[mm] n_ks[mm/d] n_suction[mm] n_pore-size-index[-] n_bubblepressure[cm] n_coarse_frag[-]*n n_shrinks[0/1]) bedrock[0/1] alluvial[0/1] 3 | -------------------------------------------------------------------------------- /example/make_wasa_input/templ/vegetation.dat: -------------------------------------------------------------------------------- 1 | Specification of vegetation parameters 2 | Veg-ID Stomata_Resistance[s/m] minsuction[hPa] maxsuction[hPa] height1[m] height2[m] height3[m] height4[m] rootdepth1[m] rootdepth2[m] rootdepth3[m] rootdepth4[m] LAI1[-] LAI2[-] LAI3[-] LAI4[-] albedo1[-] albedo2[-] albedo3[-] albedo4[-] 3 | -------------------------------------------------------------------------------- /inst/database/update_db_v24.sql: -------------------------------------------------------------------------------- 1 | 2 | ALTER TABLE subbasins ADD COLUMN chan_len DOUBLE COMMENT 'Subbasin main channel length [m]'; 3 | 4 | INSERT INTO db_version VALUES ( 5 | 24, 6 | 24, 7 | 'Added main channel length parameter for ECHSE engine WASA', 8 | 'none', 9 | 'subbasins', 10 | '', 11 | '2017-02-07 12:00:00'); 12 | -------------------------------------------------------------------------------- /example/make_wasa_input/templ/do.dat: -------------------------------------------------------------------------------- 1 | Parameter specification for the WASA Model (SESAM-Project), generated with make_wasa_input.php 2 | ../input/esera/ 3 | ../output/esera/ 4 | 1980 //tstart (start year of simulation) 5 | 2000 //tstop (end year of simulation) 6 | 1 //mstart (start month of simulation) 7 | 12 //mstop (end month of simulation) 8 | -------------------------------------------------------------------------------- /example/make_wasa_input/templ/soil_vegetation.dat: -------------------------------------------------------------------------------- 1 | Specification of soil-vegetation components (links soter, terrain component, soil and vegetation properties) 2 | For each block: first line Soil IDs, Second line Land use, third line fraction of SVCs in each terrain component 3 | Subasin-ID[id] LU-ID[id] TC-ID[id] fraction_rocky[-] nbrSVC[-] Soil-ID(n_values)[-] Vegetation-ID(n_values)[-] fraction(n_values)[-] 4 | -------------------------------------------------------------------------------- /LUMP.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: Sweave 13 | LaTeX: pdfLaTeX 14 | 15 | BuildType: Package 16 | PackageInstallArgs: --no-multiarch --with-keep.source 17 | PackageCheckArgs: --output=/home/tobias/R/R.checks/ 18 | PackageRoxygenize: rd,collate 19 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2 (4.1.1): do not edit by hand 2 | 3 | export(area2catena) 4 | export(calc_seasonality) 5 | export(calc_subbas) 6 | export(db_echse_input) 7 | export(lump_grass_post) 8 | export(lump_grass_prep) 9 | export(prof_class) 10 | export(rainy_season) 11 | export(reservoir_outlet) 12 | export(reservoir_lumped) 13 | export(reservoir_strategic) 14 | export(db_create) 15 | export(db_fill) 16 | export(db_update) 17 | export(db_check) 18 | export(db_prepare_musle) 19 | export(db_wasa_input) 20 | export(db_extract_subcatch) 21 | export(disc_wrapper) 22 | useDynLib(lumpR) 23 | -------------------------------------------------------------------------------- /example/make_wasa_input/check_db_version.php: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /inst/database/update_db_v22.sql: -------------------------------------------------------------------------------- 1 | 2 | ALTER TABLE vegetation ADD COLUMN intfc DOUBLE COMMENT 'Interception capacity per unit LAI [m]'; 3 | ALTER TABLE vegetation ADD COLUMN crop_makk DOUBLE COMMENT 'Crop-factor for calculation of pot. evapotransp. after Makkink (optional) [-]'; 4 | 5 | ALTER TABLE subbasins ADD COLUMN lat DOUBLE COMMENT 'Latitude of subbasin centroid [decimal degree]'; 6 | 7 | ALTER TABLE horizons ADD COLUMN soil_dens DOUBLE COMMENT 'Bulk density [kg/m3]'; 8 | 9 | INSERT INTO db_version VALUES ( 10 | 22, 11 | 22, 12 | 'Added some parameter values nedded for ECHSE engine WASA', 13 | 'none', 14 | 'vegetation, subbasins, horizons', 15 | '', 16 | '2015-09-14 14:40:00'); 17 | 18 | -------------------------------------------------------------------------------- /inst/database/update_db_v20.sql: -------------------------------------------------------------------------------- 1 | 2 | CREATE TABLE rainy_season ( 3 | pid INT AUTO_INCREMENT NOT NULL COMMENT 'row counter', 4 | subbas_id INT NOT NULL COMMENT 'foreign key to subbas (use -1 as wildcard)', 5 | veg_id INT NOT NULL COMMENT 'foreign key vegetation (use -1 as wildcard)', 6 | yearm INT NOT NULL COMMENT 'year (use -1 as wildcard)', 7 | node1 INT NOT NULL COMMENT '1. node in cycle (as DOY/julian day)', 8 | node2 INT NOT NULL COMMENT '2. node in cycle (as DOY/julian day)', 9 | node3 INT NOT NULL COMMENT '3. node in cycle (as DOY/julian day)', 10 | node4 INT NOT NULL COMMENT '4. node in cycle (as DOY/julian day)', 11 | PRIMARY KEY (pid) 12 | ) ENGINE=InnoDB; 13 | 14 | INSERT INTO db_version VALUES ( 15 | 20, 16 | 20, 17 | 'Added table with information about yearly start, end and transition of rainy season for each subbasin and vegetation type', 18 | 'rainy_season', 19 | 'none', 20 | 'originally already included in db ver 17 but forgot to include into R package LUMP', 21 | '2015-07-14 15:00:00'); 22 | 23 | -------------------------------------------------------------------------------- /inst/database/update_db_v19.sql: -------------------------------------------------------------------------------- 1 | 2 | ALTER TABLE horizons CHANGE descr description NVARCHAR(50); 3 | ALTER TABLE landscape_units CHANGE descr description NVARCHAR(50); 4 | ALTER TABLE particle_classes CHANGE `desc` description NVARCHAR(50); 5 | ALTER TABLE soils CHANGE `desc` description NVARCHAR(50); 6 | ALTER TABLE soil_veg_components CHANGE descr description NVARCHAR(50); 7 | ALTER TABLE subbasins CHANGE `desc` description NVARCHAR(50); 8 | ALTER TABLE terrain_components CHANGE descr description NVARCHAR(50); 9 | ALTER TABLE vegetation CHANGE `desc` description NVARCHAR(50); 10 | ALTER TABLE landscape_units CHANGE length slopelength DOUBLE; 11 | ALTER TABLE horizons CHANGE depth thickness DOUBLE; 12 | 13 | ALTER TABLE db_version CHANGE `date` date_time DATETIME; 14 | 15 | INSERT INTO db_version VALUES ( 16 | 19, 17 | 19, 18 | 'First version within LUMP R-package', 19 | 'none', 20 | 'horizons, landscape_units, particle_classes, soils, soil_veg_components, subbasins, terrain_components, vegetation, db_version', 21 | 'adjusted data type in db_version and column names for the other tables', 22 | '2015-05-11 17:08:00'); 23 | 24 | -------------------------------------------------------------------------------- /inst/database/update_db_v25.sql: -------------------------------------------------------------------------------- 1 | 2 | CREATE TABLE x_seasons ( 3 | pid INT AUTO_INCREMENT NOT NULL COMMENT 'row counter', 4 | parameter NVARCHAR(20) NOT NULL COMMENT 'K: K-factor, C: C-factor, P: P-factor, coarse: coarse-fraction, n : Mannings n', 5 | subbas_id INT NOT NULL COMMENT 'foreign key to subbas (use -1 as wildcard)', 6 | svc_id INT NOT NULL COMMENT 'foreign key to soil_veg_components (use -1 as wildcard)', 7 | yearm INT NOT NULL COMMENT 'year (use -1 as wildcard)', 8 | node1 INT NOT NULL COMMENT '1. node in cycle (as DOY/julian day)', 9 | node2 INT NOT NULL COMMENT '2. node in cycle (as DOY/julian day)', 10 | node3 INT NOT NULL COMMENT '3. node in cycle (as DOY/julian day)', 11 | node4 INT NOT NULL COMMENT '4. node in cycle (as DOY/julian day)', 12 | PRIMARY KEY (pid) 13 | ) ENGINE=InnoDB; 14 | 15 | INSERT INTO db_version VALUES ( 16 | 25, 17 | 25, 18 | 'Added table with information about yearly start, end and transition of rainy season for each subbasin and svc type for specifying additional seasonalities', 19 | 'x_seasons', 20 | 'none', 21 | 'originally already included in db ver 17 but forgot to include into R package LUMP', 22 | '2018-06-27 9:00:00'); 23 | 24 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: lumpR 2 | Type: Package 3 | Title: Landscape Unit Mapping Program for R 4 | Version: 3.2 5 | Date: 2025-12-12 6 | Authors@R: c(person("Tobias", "Pilz", 7 | role=c("aut", "cre", "cph")), 8 | person("Till", "Francke", email="francke@uni-potsdam.de", 9 | role=c("aut", "cph"))) 10 | Description: The package provides functions for a semi-automated approach of 11 | the delineation and description of landscape units and partition into terrain 12 | components. It can be used for the pre-processing of semi-distributed large- 13 | scale hydrological and erosion models using catena-representation (WASA-SED, 14 | CATFLOW), i.e. the LUMP-algorithm. It is closely connected to and uses functionalities of GRASS GIS. 15 | Additional pre-processing tools beyond the scope of the original LUMP are 16 | included. 17 | Depends: 18 | raster, 19 | cluster, 20 | xts, 21 | foreach, 22 | RODBC, 23 | terra, 24 | rgrass (>= 0.4-1), 25 | sf 26 | Suggests: 27 | doMC, 28 | doParallel 29 | License: GPL-3 30 | URL: https://github.com/tpilz/lumpR 31 | BugReports: https://github.com/tpilz/lumpR/issues 32 | NeedsCompilation: yes 33 | Encoding: UTF-8 34 | RoxygenNote: 7.3.3 35 | -------------------------------------------------------------------------------- /inst/database/update_db_v21.sql: -------------------------------------------------------------------------------- 1 | 2 | ALTER TABLE meta_info MODIFY affected_tables NVARCHAR(400); 3 | ALTER TABLE meta_info MODIFY remarks NVARCHAR(400); 4 | 5 | ALTER TABLE db_version MODIFY remarks NVARCHAR(400); 6 | ALTER TABLE db_version MODIFY description NVARCHAR(400); 7 | 8 | ALTER TABLE vegetation MODIFY description NVARCHAR(255); 9 | 10 | ALTER TABLE horizons MODIFY description NVARCHAR(255); 11 | 12 | ALTER TABLE soils MODIFY description NVARCHAR(255); 13 | 14 | ALTER TABLE subbasins MODIFY description NVARCHAR(255); 15 | 16 | ALTER TABLE landscape_units MODIFY description NVARCHAR(255); 17 | 18 | ALTER TABLE terrain_components MODIFY description NVARCHAR(255); 19 | 20 | ALTER TABLE soil_veg_components MODIFY description NVARCHAR(255); 21 | 22 | ALTER TABLE particle_classes MODIFY description NVARCHAR(255); 23 | 24 | INSERT INTO db_version VALUES ( 25 | 21, 26 | 21, 27 | 'Enlarged columns to hold more characters', 28 | 'none', 29 | 'meta_info, db_version, vegetation, horizons, soils, subbasins, landscape_units, terrain_components, soil_veg_components, particle_classes', 30 | 'Error of oversized character strings detected when testing LUMP for MariaDB, SQLite never complained, access max length only 255', 31 | '2015-07-17 15:15:00'); 32 | 33 | -------------------------------------------------------------------------------- /inst/database/update_db_v23.sql: -------------------------------------------------------------------------------- 1 | 2 | ALTER TABLE vegetation ADD COLUMN crop_faoref DOUBLE COMMENT 'Crop-factor for calculation of pot. evapotransp. after FAO reference approach (optional) [-]'; 3 | ALTER TABLE vegetation ADD COLUMN par_stressHum DOUBLE COMMENT 'Parameter to calculate water vapour deficit stomatal conductance stress factor (in WASA hard-coded as 0.03) [1/hPa]'; 4 | ALTER TABLE vegetation ADD COLUMN glo_half DOUBLE COMMENT 'Solar radiation at which stomatal conductance is half of its maximum (in WASA hard-coded as 100) [W/m2]'; 5 | 6 | ALTER TABLE soils ADD COLUMN Phil_s DOUBLE COMMENT 'Infiltration: Philip parameter: Sorptivity, in ECHSE calculated internally if set to NA [ms^(-1/2)]'; 7 | ALTER TABLE soils ADD COLUMN Phil_a DOUBLE COMMENT 'Infiltration: Philip parameter: Second term parameter, in ECHSE calculated internally if set to NA [m/s]'; 8 | ALTER TABLE soils ADD COLUMN Hort_ini DOUBLE COMMENT 'Infiltration: Horton parameter: initial infiltration rate [m/s]'; 9 | ALTER TABLE soils ADD COLUMN Hort_end DOUBLE COMMENT 'Infiltration: Horton parameter: final infiltration rate [m/s]'; 10 | ALTER TABLE soils ADD COLUMN Hort_k DOUBLE COMMENT 'Infiltration: Horton parameter: decay constant [1/s]'; 11 | 12 | ALTER TABLE subbasins ADD COLUMN lon DOUBLE COMMENT 'Longitude of subbasin centroid [decimal degrees]'; 13 | ALTER TABLE subbasins ADD COLUMN elev DOUBLE COMMENT 'Average elevation above sea level of subbasin [m]'; 14 | 15 | INSERT INTO db_version VALUES ( 16 | 23, 17 | 23, 18 | 'Added some more parameter values nedded for ECHSE engine WASA', 19 | 'none', 20 | 'vegetation, soils, subbasins', 21 | '', 22 | '2016-03-24 10:45:00'); 23 | -------------------------------------------------------------------------------- /man/db_update.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/db_update.R 3 | \name{db_update} 4 | \alias{db_update} 5 | \title{Update parameter database} 6 | \usage{ 7 | db_update(dbname, to_ver = Inf, checkOnly = FALSE, keep_tables = NULL) 8 | } 9 | \arguments{ 10 | \item{dbname}{Name of the data source (DSN) registered at ODBC.} 11 | 12 | \item{to_ver}{Version number to update to (default: newest version available).} 13 | 14 | \item{checkOnly}{only print current version number, no updating.} 15 | 16 | \item{keep_tables}{Vector of type \code{character}. Skips the specified tables. Default: NULL.} 17 | } 18 | \description{ 19 | Function updates the parameter database to the specified (or latest version). 20 | } 21 | \details{ 22 | This function currently is only relevant to users who already have a parameter 23 | database from times before LUMP was an R package. In this case make sure you have 24 | version 18 of the database (Do manual updates first, see db_version.txt). 25 | Apply this function to update it to the desired version. 26 | 27 | It is planned to add further functionality to this function when the database 28 | structure is being further developed. 29 | 30 | Up to version 21 is relevant for the WASA model. Versions 22 to 24 contain exclusive 31 | adaptions for ECHSE's WASA engine only! 32 | } 33 | \references{ 34 | lumpR package introduction with literature study and sensitivity analysis:\cr 35 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 36 | landscape discretisation for hillslope-based hydrological models. 37 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 38 | } 39 | \author{ 40 | Tobias Pilz, Till Francke 41 | } 42 | -------------------------------------------------------------------------------- /man/db_extract_subcatch.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/db_extract_subcatch.R 3 | \name{db_extract_subcatch} 4 | \alias{db_extract_subcatch} 5 | \title{Extracts sub-catchment(s) for specific subbasin(s) from a database} 6 | \usage{ 7 | db_extract_subcatch( 8 | dbname = NULL, 9 | sub_extract = NULL, 10 | dbname_new = NULL, 11 | verbose = T 12 | ) 13 | } 14 | \arguments{ 15 | \item{dbname}{Name of the data source (DSN) registered at ODBC. See \code{Details} of 16 | \code{\link[lumpR]{db_create}}.} 17 | 18 | \item{sub_extract}{\code{vector} of type numeric with the 'pid'(s) of table 19 | 'subbasins' in database \code{dbname} for which the associated sub-catchments 20 | shall be extracted.} 21 | 22 | \item{dbname_new}{\code{vector} of type character with the names of the databases 23 | containing the extracted sub-catchments. Database need to be registered for ODBC 24 | (see \code{Details} of \code{\link[lumpR]{db_create}}).} 25 | 26 | \item{verbose}{\code{logical}. Should detailed information during execution be 27 | printed? Default: \code{TRUE}.} 28 | } 29 | \value{ 30 | Function returns nothing. Only the databases are processed. 31 | } 32 | \description{ 33 | This function extracts the sub-catchment(s) for selected subbasin(s) from an 34 | existing and fully pre-processed WASA-SED parameter database. 35 | } 36 | \details{ 37 | The function first copies the original databse. Then the upstream subbasins 38 | of the selected outlet subbasin are identified and the copied database is pruned 39 | accordingly. The latter only affects the tables subbasins, landscape_units, 40 | terrain_components, r_subbas_contains_lu, r_lu_contains_tc and r_tc_contains_svc. 41 | Thus, the other tables may contain redundant information which are contained to 42 | limit the processing time and retain the opportunity to (re-)include information 43 | later on. 44 | } 45 | \author{ 46 | Tobias Pilz 47 | } 48 | -------------------------------------------------------------------------------- /inst/database/update_db_v26.sql: -------------------------------------------------------------------------------- 1 | CREATE TABLE reservoirs_strategic ( 2 | pid INT AUTO_INCREMENT NOT NULL COMMENT 'foreign key to subbas', 3 | res_id INT COMMENT 'external ID (optional)', 4 | name NVARCHAR(20) COMMENT 'reservoir name (optional)', 5 | minlevel double COMMENT 'Initial minimum level [m]', 6 | maxlevel double COMMENT 'Maximum water level [m]', 7 | vol0 double COMMENT 'Initial volume [10^3 m^3]', 8 | storecap double COMMENT 'Initial storage capacity [10^3 m^3]. ', 9 | damflow double COMMENT 'Target release through the intake devices [m^3/s]', 10 | damq_frac double COMMENT 'Maximum fraction of damflow which is released from the reservoir [-]', 11 | withdrawal double COMMENT 'Water withdrawal discharge to supply the water use sectors in the reservoir [m^3/s]. ', 12 | damyear double COMMENT 'Year of construction of the dam', 13 | maxdamarea double COMMENT 'Initial maximum area of the reservoir (ha). ', 14 | damdead double COMMENT 'Initial dead volume of the reservoir [10^3 m^3]', 15 | damalert double COMMENT 'Initial alert volume of the reservoir [10^3 m^3]', 16 | dama double COMMENT 'Parameters of the area-volume relationship (area=dama*Vol^damb) [-]', 17 | damb double COMMENT 'Parameters of the area-volume relationship (area=dama*Vol^damb) [-]', 18 | q_outlet double COMMENT 'Maximum outflow discharge released through the bottom outlets [m^3/s]', 19 | fvol_botm double COMMENT 'Fraction of storage capacity that indicates the minimum storage volume for sediment release through the bottom outlets [-]', 20 | fvol_over double COMMENT 'Flag to simulate the retention of reservoir overflow during spillway operation [0 = without time delay, 1 = with time delay]', 21 | damc double COMMENT 'Parameters of the spillway rating curve (Qout=damc*Hv^damd) [-]', 22 | damd double COMMENT 'Parameters of the spillway rating curve (Qout=damc*Hv^damd) [-]', 23 | elevbottom double COMMENT 'bottom outlet elevation [m]', 24 | PRIMARY KEY (pid) 25 | ) ENGINE=InnoDB; 26 | 27 | INSERT INTO db_version VALUES ( 28 | 26, 29 | 26, 30 | 'Added table for strategic reservoirs', 31 | 'reservoirs_strategic', 32 | 'none', 33 | '', 34 | '2018-07-12 11:00:00'); 35 | 36 | -------------------------------------------------------------------------------- /inst/database/update_db_v28.sql: -------------------------------------------------------------------------------- 1 | CREATE TABLE reservoirs_small_classes ( 2 | pid INT AUTO_INCREMENT NOT NULL COMMENT 'primary key, reservoir class ID', 3 | name NVARCHAR(20) COMMENT 'reservoir class description (optional)', 4 | maxlake0 double COMMENT 'Upper limit of reservoir size class in terms of volume [m^3]', 5 | lake_vol0_factor double COMMENT 'Fraction of storage capacity that indicates the initial water volume in the reservoir size classes [-]', 6 | lake_change double COMMENT 'Factor that indicates yearly variation in the number of reservoirs of the size classes [-]', 7 | alpha_Molle double COMMENT 'Parameters of the area-volume relationship in the reservoir size classes (Area=alpha.k.(Vol/k)alpha/(alpha-1)) [-]. Values of reservoir area and volume are expressed in m² and m³, respectively', 8 | k_Molle double COMMENT 'Parameters of the area-volume relationship in the reservoir size classes (Area=alpha.k.(Vol/k)alpha/(alpha-1)) [-]. Values of reservoir area and volume are expressed in m² and m³, respectively', 9 | damc double COMMENT 'Parameters of the spillway rating curve in the reservoir size classes (Qout=damc.Hv^damd) [-]. Values of water height over the spillway and overflow discharges are expressed in m and m³/s, respectively', 10 | damd double COMMENT 'Parameters of the spillway rating curve in the reservoir size classes (Qout=damc.Hv^damd) [-]. Values of water height over the spillway and overflow discharges are expressed in m and m³/s, respectively', 11 | PRIMARY KEY (pid) 12 | ); 13 | 14 | CREATE TABLE r_subbas_contains_reservoirs_small ( 15 | subbas_id INT NOT NULL COMMENT 'foreign key to subbas', 16 | res_class_id INT NOT NULL COMMENT 'foreign key to reservoirs_small_classes', 17 | n_reservoirs INT NOT NULL COMMENT 'number of reservoirs [-]', 18 | maxlake double COMMENT 'Mean value of initial storage capacity of the hypothetical representative reservoirs of the size classes [m^3]', 19 | UNIQUE (subbas_id, res_class_id) 20 | ); 21 | 22 | ALTER TABLE reservoirs_strategic MODIFY pid INT AUTO_INCREMENT NOT NULL COMMENT 'primary key'; 23 | 24 | INSERT INTO db_version VALUES ( 25 | 28, 26 | 28, 27 | 'Added tables for small reservoirs', 28 | 'reservoirs_small,r_subbas_contains_reservoirs_small', 29 | 'none', 30 | '', 31 | '2018-11-20 11:00:00'); 32 | 33 | -------------------------------------------------------------------------------- /man/calc_seasonality.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calc_seasonality.R 3 | \name{calc_seasonality} 4 | \alias{calc_seasonality} 5 | \title{Calculate time series based on seasonality} 6 | \usage{ 7 | calc_seasonality(rainy_season, seasonality, timezone = "") 8 | } 9 | \arguments{ 10 | \item{rainy_season}{\code{data.frame} giving start and end dates of the rainy season. 11 | Output of function \code{\link[lumpR]{rainy_season}}. See doc for information on 12 | data structure.} 13 | 14 | \item{seasonality}{\code{data.frame} or \code{matrix} giving id value (corresponding 15 | to first column of \code{rainy_season}) and the respective 4 node values of the 16 | target variable: First value: Start day of year (DOY) of rainy season. 2: DOY 17 | when climax of vegetation is reached. 3: End DOY of rainy season (begin of 18 | vegetation degradation). 4: End of main phase of vegetation degradation.} 19 | 20 | \item{timezone}{Timezone the date-time values of the output object shall refer to. 21 | If nothing is specified your system's timezone is used.} 22 | } 23 | \value{ 24 | Object of class \code{\link[xts]{xts}} with daily values of the target 25 | variable. Columns refer to the stations specified in the first column of 26 | the input object \code{rainy_season}. 27 | } 28 | \description{ 29 | Function calculates a daily time series of a (vegetation) variable based on 30 | information about the seasonality of that variable. 31 | } 32 | \references{ 33 | Function uses subroutine in FORTRAN 90 code extracted from the hydrological 34 | model WASA. General model description (information on vegetation seasonality 35 | see chapter 4.3.3): 36 | 37 | Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid 38 | North-East of Brazil. \emph{PIK Report 77}, Potsdam Institute for Climate 39 | Impact Research, Potsdam, Germany. 40 | 41 | lumpR package introduction with literature study and sensitivity analysis:\cr 42 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 43 | landscape discretisation for hillslope-based hydrological models. 44 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 45 | } 46 | \author{ 47 | Tobias Pilz 48 | } 49 | -------------------------------------------------------------------------------- /man/db_create.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/db_create.R 3 | \name{db_create} 4 | \alias{db_create} 5 | \title{Create parameter database} 6 | \usage{ 7 | db_create(dbname, overwrite = NULL, keep_tables = NULL, db_ver = Inf) 8 | } 9 | \arguments{ 10 | \item{dbname}{Name of the data source (DSN) registered at ODBC. See \code{Details}.} 11 | 12 | \item{overwrite}{\code{c(NULL,"drop","empty")}. Delete and re-create (\code{"drop"}) or empty (\code{"empty"}) any tables already existing in db. Default: NULL (keep all existing tables). In any case, tables included in \emph{keep_tables} remain untouched.} 13 | 14 | \item{keep_tables}{Vector of type \code{character}. Preserves the specified tables, if existing. Overrides \emph{overwrite}. Default: NULL.} 15 | 16 | \item{db_ver}{\code{numeric}. If \code{Inf} (default) the database will be updated 17 | to the latest version calling \code{\link[lumpR]{db_update}} internally. Otherwise, the 18 | specified version is created. The earliest possible version is 19.} 19 | } 20 | \description{ 21 | Function creates tables in a pre-defined database to store parameters relevant 22 | for modelling applications with the WASA model. 23 | } 24 | \details{ 25 | This package uses the ODBC interface to connect to a database. Creating the database 26 | requires the following prior steps which are OS dependent: 27 | \itemize{ 28 | \item{Install a \emph{Database Management System} and respective \emph{ODBC-driver} and on your computer. 29 | Currently supported (tested) are: SQLite (v. 3.8.9), MariaDB/MySQL (v. 10.0.17), 30 | MS Access.} 31 | \item{Register an empty database at your ODBC configuration.} 32 | } 33 | Calling \emph{db_create} creates the necessary tables in the database. These are then filled and processed by subsequent function of \emph{lumpR}. 34 | More information can be found at the lumpR package wiki: \url{https://github.com/tpilz/lumpR/wiki} 35 | } 36 | \references{ 37 | lumpR package introduction with literature study and sensitivity analysis:\cr 38 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 39 | landscape discretisation for hillslope-based hydrological models. 40 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 41 | } 42 | \author{ 43 | Tobias Pilz, Till Francke 44 | } 45 | -------------------------------------------------------------------------------- /man/db_prepare_musle.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/db_prepare_musle.R 3 | \name{db_prepare_musle} 4 | \alias{db_prepare_musle} 5 | \title{Prepare various input related to use of sediment module using (M)USLE erosion} 6 | \usage{ 7 | db_prepare_musle( 8 | dbname, 9 | compute_K = FALSE, 10 | copy_from_other_tables = NULL, 11 | setP = NULL, 12 | verbose = TRUE 13 | ) 14 | } 15 | \arguments{ 16 | \item{dbname}{Name of the data source (DSN) registered at ODBC. See \code{Details} of 17 | \code{\link[lumpR]{db_create}}.} 18 | 19 | \item{compute_K}{Compute (M)USLE K-factor (soil erodibility) from properties of topmost soil horizon (i.e. use texture of topmost soil layer), write it to table "soil" (use \code{copy_from_other_tables} to transfer it to table "soil_veg_components"). \code{c(TRUE, FALSE)}} 20 | 21 | \item{copy_from_other_tables}{Copy values to table "soil_veg_components": MUSLE-C and Manning-n from table "vegetation", MUSLE-K from "soils", coarse_frag from "horizons". Array of strings with possible values \code{c("musle-c", "manning-n" ,"musle-k" , "coarse_frac")}} 22 | 23 | \item{setP}{Set entire column of (M)USLE P-factor (protection measures) to a single value (usually 1). Default NULL (do not set).} 24 | 25 | \item{verbose}{\code{logical}. Enable printing of information during execution. Default: \code{TRUE}.} 26 | } 27 | \description{ 28 | Function to compute and write erosion-related parameter values relevant for modelling application with the 29 | WASA-SED hydrological model into an existing database, preferably created with 30 | \code{\link[lumpR]{db_create}}. 31 | } 32 | \details{ 33 | This function uses the texture information of the topmost horizon, converting it to USDA-texture classes and applying the relationships proposed by 34 | after Williams (1995). 35 | } 36 | \references{ 37 | \bold{lumpR paper}\cr 38 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 39 | landscape discretisation for hillslope-based hydrological models. 40 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 41 | 42 | Williams, J. R.(1995): The EPIC Model. In Computer Models of Watershed Hydrology; Singh, V. P., Ed.; Water Resources Publications: Highlands Ranch, CO, USA, 1995; pp 909–1000. 43 | } 44 | \author{ 45 | Till Francke \email{francke@uni-potsdam.de} 46 | } 47 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # lumpR 2 | 3 | Landscape Unit Mapping Program for R 4 | 5 | 6 | ## DESCRIPTION 7 | 8 | This package provides functions for a semi-automated approach of the delineation and description of landscape units and their partitioning into terrain components. It can be used for the pre-processing of semi-distributed large-scale hydrological and erosion models using catena-representation (e.g. [WASA-SED](https://github.com/TillF/WASA-SED), CATFLOW). Additional pre-processing tools beyond the scope of the original LUMP algorithm are included. 9 | 10 | 11 | ## INSTALLATION 12 | 13 | * command line installation: 14 | 15 | ```R 16 | install.packages("devtools") 17 | library(devtools) 18 | Sys.setenv(R_REMOTES_NO_ERRORS_FROM_WARNINGS=TRUE) #tell git_install() to ignore warnings. Otherwise, it gets stuck at each warning 19 | install_github("tPilz/lumpR") 20 | ``` 21 | 22 | * from zip/tar: 23 | * download zip/tar from the [github-repository](https://github.com/tpilz/lumpR/releases) 24 | * install via R-GUI 25 | 26 | 27 | The main branch relies on GRASS 8. For legacy support of GRASS 7 (no further development and support), use branch [https://github.com/tpilz/lumpR/tree/grass7] 28 | 29 | ## DEPENDENCIES 30 | * [R language](https://www.r-project.org/), including extensions r.stream.distance and r.stream.order 31 | * [GRASS GIS](https://grass.osgeo.org/), version 8. 32 | * data base (e.g. sqlite, MariaDB, LibreOffice Base or other DBs with ODBC-driver) 33 | For instruction, see the [wiki](https://github.com/tpilz/lumpR/wiki) . 34 | 35 | ## MORE INFORMATION 36 | 37 | Have a look at our wiki for more detailed information: [>LINK<](https://github.com/tpilz/lumpR/wiki) 38 | 39 | 40 | ## FEEDBACK and BUGS 41 | 42 | Feel free to comment via github issues: [>LINK<](https://github.com/tpilz/lumpR/issues) 43 | 44 | 45 | ## LICENSE 46 | 47 | lumpR is distributed under the GNU General Public License version 3 or later. The license is available in the file `GPL-3` of lumpR's source directory or online: [>LINK<](http://www.gnu.org/licenses/gpl.html) 48 | 49 | ## NOTE 50 | 51 | This package was also known as LUMP and has been renamed by Jan 9th 2017 to distinguish it from the LUMP algorithm published by Francke et al. (2008). 52 | 53 | 54 | ## REFERENCES 55 | 56 | A paper describing lumpR along with an example study was published in GMD: 57 | 58 | Pilz, T., Francke, T., and 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](https://www.geosci-model-dev.net/10/3001/2017/gmd-10-3001-2017.html) 59 | 60 | See also the accompanying github repository: https://github.com/tpilz/lumpr_paper 61 | 62 | 63 | For the original LUMP algorithm see: 64 | 65 | Francke, T., Güntner, A., Mamede, G., Müller, E. N., and Bronstert, A. (2008): Automated catena-based discretization of landscapes for the derivation of hydrological modelling units, Int. J. Geogr. Inf. Sci., 22, 111-132, doi:[10.1080/13658810701300873, 2008.](http://www.tandfonline.com/doi/abs/10.1080/13658810701300873) 66 | -------------------------------------------------------------------------------- /man/rainy_season.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rainy_season.R 3 | \name{rainy_season} 4 | \alias{rainy_season} 5 | \title{Determine start and end date of the rainy season} 6 | \usage{ 7 | rainy_season(prec_ts = NULL, dry_season = NULL, nodata = NA) 8 | } 9 | \arguments{ 10 | \item{prec_ts}{Daily precipitation time series object of class \code{\link[xts]{xts}}. 11 | Data should be a numerical vector or a matrix with one named column per 12 | station a time series is available for.} 13 | 14 | \item{dry_season}{Day of year in the expected centre of dry season. This is the 15 | starting point of the stastical procedure to look for the next rainy season 16 | in the data set. Should be set approximately (+- 1 month) to the centre of 17 | the dry season.} 18 | 19 | \item{nodata}{No-data value in the time series. Default: \code{NA}.} 20 | } 21 | \value{ 22 | \code{data.frame} of rainy season start and end days in input format for 23 | the hydrological model WASA. 24 | 25 | Columns are: station ID (column names of input \code{xts} object), year, start 26 | day of rainy season (negative values refer to the previous year), day of year 27 | the climax of the vegetation season is reached, end day of rainy season, 28 | last day of transition period from rainy to dry season (values greater than 29 | 365/366 refer to the next year). 30 | } 31 | \description{ 32 | Function calculates the yearly start and end dates of the rainy season from 33 | a precipitation time series based on a statistical approach as described by 34 | Gerstengarbe & Werner (1999). 35 | } 36 | \note{ 37 | The first rainy season that can be identified by the function is the one 38 | that starts after the first dry season in the given time series. This means, 39 | for instance, that if the time series starts on Jan 1st 1978 and \code{dry_season} 40 | is set to 243 (conditions for NE Brazil), the first detectable rainy season 41 | is the one starting around Dec 78 to Feb 79. To get also the rainy season 42 | for year 1978 for this example, 365 daily values can be artifically inserted 43 | at the beginning of the time series, representing the hypothetical year 1977. 44 | Just copy the data of 1978. 45 | } 46 | \references{ 47 | lumpR package introduction with literature study and sensitivity analysis:\cr 48 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 49 | landscape discretisation for hillslope-based hydrological models. 50 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 51 | 52 | Function uses the FORTRAN 77 code developed by \emph{Gerstengarbe et al.}. 53 | The algorithm is described in: 54 | 55 | Gerstengarbe & Werner (1999): Estimation of the beginning and end of recurrent 56 | events within a climate regime. \emph{Climate Research}, 11(2), 97-107. 57 | 58 | 59 | Function further used by A. Guentner to simulate vegetation dynamics within 60 | the hydrological model WASA: 61 | 62 | Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid 63 | North-East of Brazil. \emph{PIK Report 77}, Potsdam Institute for Climate 64 | Impact Research, Potsdam, Germany. 65 | } 66 | \author{ 67 | Tobias Pilz 68 | } 69 | -------------------------------------------------------------------------------- /man/reservoir_outlet.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/reservoir_outlet.R 3 | \name{reservoir_outlet} 4 | \alias{reservoir_outlet} 5 | \title{Determine outlet coordinates of reservoirs} 6 | \usage{ 7 | reservoir_outlet( 8 | flowacc = NULL, 9 | dem = NULL, 10 | res_vct = NULL, 11 | outlets_vect = NULL, 12 | keep_temp = FALSE, 13 | overwrite = FALSE, 14 | silent = F 15 | ) 16 | } 17 | \arguments{ 18 | \item{flowacc}{Flow accumulation raster in GRASS location used for determination 19 | of reservoir outlets (= highest accumulation value). Set to \code{NULL} if 20 | it should be calculated based on a DEM. Default: \code{NULL}.} 21 | 22 | \item{dem}{Digital elevation model in GRASS location used for calculation of 23 | flow accumulation if no flow accumulation raster is given. Default: \code{NULL}.} 24 | 25 | \item{res_vct}{Reservoir vector file (polygon) in GRASS location. For each polygon coordinates 26 | of the outlet (cell with highest flow accumulation) are determined. Needs 27 | at least the column \code{res_id} (integer) as reservoir identifier. 28 | If there are no columns \code{elevation} (double) and \code{area} (double) [hectars], they will be added.} 29 | 30 | \item{outlets_vect}{Output: Name of vector file of outlet locations to be exported 31 | to GRASS location. Same fields as \code{res_vct}, fields 32 | \code{res_id}, \code{elevation} and \code{area} may have been added.} 33 | 34 | \item{keep_temp}{\code{logical}. Set to \code{TRUE} if temporary files shall be kept 35 | in the GRASS location, e.g. for debugging or further analyses. Default: \code{FALSE}.} 36 | 37 | \item{overwrite}{\code{logical}. Shall output of previous calls of this function be 38 | deleted? If \code{FALSE} the function returns an error if output already exists. 39 | Default: \code{FALSE}.} 40 | 41 | \item{silent}{\code{logical}. Shall the function be silent (also suppressing warnings 42 | of internally used GRASS functions)? Default: \code{FALSE}.} 43 | } 44 | \value{ 45 | Function returns nothing, but produces \code{outlets_vect}. \bold{WARNING:} Up to version 2.5.0 this function 46 | returned a \code{SpatialPoints} object with the outlet coordinates. 47 | } 48 | \description{ 49 | Takes a flow accumulation raster (or DEM for computation) and reservoir vector 50 | file from a GRASS location and estimates the outlet coordinates of each reservoir 51 | polygon. Can be run before \code{\link[lumpR]{reservoir_strategic}} to produce the required input. May also be used to provide outlet points for subbasin delineation. 52 | } 53 | \note{ 54 | Prepare GRASS location and necessary files in advance and start GRASS 55 | session in R using \code{\link[rgrass]{initGRASS}}. Location should not 56 | contain any maps ending on *_t as these will be removed by calling the 57 | function to remove temporary maps. 58 | 59 | Internal operations require a non-dbf datatabes driver (SQLite, PostgreSQL, MySQL, ODBC, ...). 60 | Automatic switiching to sqlite will be attempted. 61 | 62 | \code{res_vct} must not contain a column \code{cat_new} as this will be the new identifier 63 | column for \code{outlets_vect}. 64 | 65 | Check the results by investigating vector file with outlet points written 66 | to GRASS location. Due to small projection inaccuracies between the DEM / flow 67 | accumulation raster and the reservoir vector file, calculated outlet locations 68 | might more or less deviate from true locations! 69 | 70 | Can be run before \code{\link[lumpR]{reservoir_strategic}}. 71 | } 72 | \author{ 73 | Tobias Pilz 74 | } 75 | -------------------------------------------------------------------------------- /man/disc_wrapper.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/disc_wrapper.R 3 | \name{disc_wrapper} 4 | \alias{disc_wrapper} 5 | \title{Wrapper function performing a complete landscape discretisation} 6 | \usage{ 7 | disc_wrapper( 8 | dem = NULL, 9 | drain_points = NULL, 10 | river = NULL, 11 | flowaccum = NULL, 12 | drainage_dir = NULL, 13 | lcov = NULL, 14 | soil = NULL, 15 | watermask = NULL, 16 | imperviousmask = NULL, 17 | supp_quant = NULL, 18 | supp_qual = NULL, 19 | soil_depth = NULL, 20 | sdr = NULL, 21 | veg_path = NULL, 22 | soil_path = NULL, 23 | odbc_file = "~/.odbc.ini", 24 | dbname = NULL, 25 | db_driver = "SQLITE3", 26 | db_desc = "lumpR database automatically generated with lumpR::disc_wrapper()", 27 | db_server = "localhost", 28 | db_checks = NULL, 29 | db_option = NULL, 30 | subbas = NULL, 31 | stream = NULL, 32 | stream_eha = NULL, 33 | stream_horton = NULL, 34 | points_processed = NULL, 35 | eha = NULL, 36 | flowdir = NULL, 37 | flowacc = NULL, 38 | elevriv = NULL, 39 | distriv = NULL, 40 | svc = NULL, 41 | lu = NULL, 42 | output_dir = getwd(), 43 | svc_file = "svc.dat", 44 | catena_out = "catena.dat", 45 | catena_head_out = "catena_header.dat", 46 | luoutfile = "lu_pars.dat", 47 | tcoutfile = "tc_pars.dat", 48 | lucontainstcoutfile = "lu_tc.dat", 49 | tccontainssvcoutfile = "tc_svc.dat", 50 | terraincomponentsoutfile = "tc_db.dat", 51 | sub_ofile = "sub.dat", 52 | sub_lu = "sub_lu.dat", 53 | lupar_ofile = "lu_db.dat", 54 | recl_lu = "reclass_lu.dat", 55 | thresh_sub = NULL, 56 | eha_thres = NULL, 57 | no_LUs = NULL, 58 | no_TCs = NULL, 59 | disk_swap = FALSE, 60 | drainp_out_id = NULL, 61 | thresh_stream = NULL, 62 | snap_dist = NULL, 63 | rm_spurious = NULL, 64 | prep_things2do = c("eha", "river", "svc"), 65 | groundwater = TRUE, 66 | ridge_thresh = NULL, 67 | min_cell_in_slope = NULL, 68 | min_catena_length = NULL, 69 | max_riv_dist = NULL, 70 | grass_files = FALSE, 71 | plot_catena = TRUE, 72 | plot_profclass = TRUE, 73 | plot_silhouette = TRUE, 74 | keep_temp = FALSE, 75 | overwrite = FALSE, 76 | db_overwrite = NULL, 77 | silent = FALSE, 78 | ncores = 1, 79 | addon_path = NULL 80 | ) 81 | } 82 | \value{ 83 | The function returns nothing. A number of plots, text files, and GRASS data 84 | are produced. 85 | } 86 | \description{ 87 | Wrapper function performing a complete landscape discretisation 88 | } 89 | \details{ 90 | This function is a wrapper function performing a complete landscape 91 | discretisation by calling the functions \code{\link[lumpR]{calc_subbas}}, \code{\link[lumpR]{lump_grass_prep}}, 92 | \code{\link[lumpR]{area2catena}}, \code{\link[lumpR]{prof_class}}, \code{\link[lumpR]{lump_grass_post}}, 93 | \code{\link[lumpR]{lump_grass_prep}}, \code{\link[lumpR]{db_create}}, \code{\link[lumpR]{db_fill}}, 94 | and \code{\link[lumpR]{db_check}}. See function's documentations for information about 95 | the arguments. 96 | } 97 | \note{ 98 | This function was created for automated landscape discretisation, e.g. within a 99 | Monte Carlo analysis. Use only if you are already familiar with the lumpR package 100 | and can be sure that the procedure works for your input data! 101 | } 102 | \references{ 103 | \bold{lumpR paper}\cr 104 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 105 | landscape discretisation for hillslope-based hydrological models. 106 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 107 | } 108 | \author{ 109 | Tobias Pilz 110 | } 111 | -------------------------------------------------------------------------------- /example/data_import.sh: -------------------------------------------------------------------------------- 1 | # command collection for data i/o for preparing GRASS for use with LUMP 2 | # These are just examples! adjust to your needs! 3 | # Most steps can also be performed via the GUI. 4 | 5 | cd e:/till/uni/organisation/iran/2_soil #set working directories, use "/" instead of "\" in Windows! 6 | 7 | #create a new location using GUI (Settings -> GRASS working env -> Create New Location) or using the command below: 8 | #import ESRI-grid into GRASS and create new location (create or use arbitrary location/mapset, run command below, exit location and change to new mapset) 9 | r.in.gdal input=/cygdrive/d/till/ output=dem -e location=mynewlocation 10 | 11 | 12 | #import DEM from GEO-Tiff 13 | r.in.gdal input=C:/Users/francke/ttt.tif output=dem15_filled -o 14 | 15 | 16 | #export DEM for treatment in SAGA 17 | r.out.arc input=DEM15@PERMANENT output=dem15 18 | #run SAGA, "import export/grids", "Esri arcinfo grids"; "Terrain analy", "Preproc" "Planchon/Darboux"; 19 | 20 | #reimport SAGA filled DEM 21 | r.in.gdal input=C:/Users/francke/ttt.tif output=dem15_filled -o 22 | 23 | 24 | #import soil map 25 | v.in.ogr dsn=e:/till/uni/parameterisierung/Esera_vergleich/lump/soils/soils.shp output=soils_vec -r 26 | v.to.rast input=soils_vec layer=1 output=soils_org use=attr column=soil_id rows=4096 27 | r.mapcalc soils_org_t="int(soils_org-46000)" #simplify IDs 28 | g.remove soils_org 29 | g.rename soils_org_t,soils_org 30 | 31 | #alluvial areas 32 | v.in.ogr dsn=e:/till/uni/gis/esera/geology/chebro/aluvial/aluvial_sandsiltclay.shp output=aluvial_vec layer=aluvial_sandsiltclay min_area=0.0001 type=boundary snap=-1 33 | v.to.rast input=aluvial_vec layer=1 output=aluvial use=cat value=1 rows=4096 34 | 35 | 36 | #badlands 37 | v.in.ogr dsn=e:/till/uni/gis/esera/badlands/Badland_Polygons.shp output=badland_vec layer=Badland_Polygons min_area=0.0001 type=boundary snap=-1 38 | v.to.rast input=badland_vec layer=1 output=badland use=val value=1 rows=4096 39 | 40 | #vegetation / landuse 41 | v.in.ogr dsn=e:/till/uni/parameterisierung/Esera_vergleich/lump/landuse/landuse_31n_2.shp output=vegetation_vec min_area=0.0001 type=boundary snap=-1 -r 42 | v.to.rast input=vegetation_vec layer=1 output=vegetation use=attr col=wasa_id rows=4096 43 | 44 | RMASK="RMASK" 45 | r.mapcalc RMASK_t="if(isnull(subbas),null(),1)" 46 | r.grow in=RMASK_t out=RMASK radius=20 #eliminate empty spaces 47 | g.remove RMASK_t 48 | g.copy $RMASK,MASK 49 | 50 | TOBEGROWN=vegetation 51 | g.remove grown >> /dev/null 52 | r.grow in=$TOBEGROWN out=grown radius=20 #eliminate empty spaces 53 | r.mapcalc $TOBEGROWN=$RMASK*grown 54 | 55 | r.mapcalc nodata="$RMASK * isnull($TOBEGROWN)" 56 | r.stats nodata -c #if still 1s in this map, repeat block above 57 | g.remove nodata 58 | 59 | 60 | #overlay maps 61 | r.mapcalc soils_aluv="if(isnull(aluvial),soils_org,soils_org+10000)" #denote alluvial soils 62 | 63 | #superimpose badlands as extra class in soil and landuse 64 | r.mapcalc soils_aluv_t="if(isnull(badland),soils_aluv,50)" #denote badlands 65 | g.remove soils_aluv 66 | g.rename soils_aluv_t,soils_aluv 67 | r.mapcalc vegetation_t="if(isnull(badland),vegetation,50)" #denote badlands 68 | g.remove vegetation 69 | g.rename vegetation_t,vegetation 70 | 71 | #generate SVC-map from landuse and soil data with unique SVC_IDs consisting of [soil_id,5 digits][veg_id, 2 digits] 72 | r.mapcalc svc="soils_aluv*(100)+vegetation" 73 | 74 | #output table with relation svc-id:soil-id_veg-id 75 | r.stats svc,soils_aluv,vegetation -n > scv_key.txt 76 | 77 | g.region zoom=RMASK save=esera_region --overwrite #sets a region corresponding to the extent of the area of interest 78 | 79 | #replace NAs in badland 80 | r.mapcalc badland_="if(isnull(badland),0,1)" 81 | g.remove badland 82 | g.rename badland_,badland 83 | 84 | 85 | #import barasona reservoir 86 | v.in.ogr dsn=e:/till/uni/gis/esera/water/barasona_utm31.shp output=reservoir_vec layer=barasona_utm31 min_area=0.0001 type=boundary snap=-1 87 | v.to.rast input=reservoir_vec layer=1 output=reservoir use=val val=1 rows=4096 88 | d.rast reservoir 89 | 90 | #update river information with extent of reservoir (can also be done after processing river part in lump_2.sh 91 | r.mapcalc river_t="if((river_rast==1) || not(isnull(reservoir)),1,0)" 92 | d.rast river_t 93 | g.remove river_rast 94 | g.rename river_t,river_rast 95 | 96 | 97 | -------------------------------------------------------------------------------- /example/make_wasa_input/settings.php: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /R/calc_seasonality.R: -------------------------------------------------------------------------------- 1 | # lumpR/calc_seasonality.R 2 | # Copyright (C) 2015, 2017 Tobias Pilz 3 | # 4 | # This program is free software: you can redistribute it and/or modify 5 | # it under the terms of the GNU General Public License as published by 6 | # the Free Software Foundation, either version 3 of the License, or 7 | # (at your option) any later version. 8 | # 9 | # This program is distributed in the hope that it will be useful, 10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 | # GNU General Public License for more details. 13 | # 14 | # You should have received a copy of the GNU General Public License 15 | # along with this program. If not, see . 16 | 17 | 18 | #' Calculate time series based on seasonality 19 | #' 20 | #' Function calculates a daily time series of a (vegetation) variable based on 21 | #' information about the seasonality of that variable. 22 | #' 23 | #' @param rainy_season \code{data.frame} giving start and end dates of the rainy season. 24 | #' Output of function \code{\link[lumpR]{rainy_season}}. See doc for information on 25 | #' data structure. 26 | #' 27 | #' @param seasonality \code{data.frame} or \code{matrix} giving id value (corresponding 28 | #' to first column of \code{rainy_season}) and the respective 4 node values of the 29 | #' target variable: First value: Start day of year (DOY) of rainy season. 2: DOY 30 | #' when climax of vegetation is reached. 3: End DOY of rainy season (begin of 31 | #' vegetation degradation). 4: End of main phase of vegetation degradation. 32 | #' 33 | #' @param timezone Timezone the date-time values of the output object shall refer to. 34 | #' If nothing is specified your system's timezone is used. 35 | #' 36 | #' @return Object of class \code{\link[xts]{xts}} with daily values of the target 37 | #' variable. Columns refer to the stations specified in the first column of 38 | #' the input object \code{rainy_season}. 39 | #' 40 | #' @references Function uses subroutine in FORTRAN 90 code extracted from the hydrological 41 | #' model WASA. General model description (information on vegetation seasonality 42 | #' see chapter 4.3.3): 43 | #' 44 | #' Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid 45 | #' North-East of Brazil. \emph{PIK Report 77}, Potsdam Institute for Climate 46 | #' Impact Research, Potsdam, Germany. 47 | #' 48 | #' lumpR package introduction with literature study and sensitivity analysis:\cr 49 | #' Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 50 | #' landscape discretisation for hillslope-based hydrological models. 51 | #' \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 52 | #' 53 | #' @author Tobias Pilz 54 | #' 55 | 56 | calc_seasonality <- function( 57 | # INPUT # 58 | rainy_season, 59 | seasonality, 60 | timezone="" 61 | ) { 62 | 63 | 64 | # prepare input objects (make sure IDs are integer values for Fortran routine) 65 | ids_rainy <- as.character(rainy_season[,1]) 66 | ids_season <- as.character(seasonality[,1]) 67 | if(any(!(ids_rainy %in% ids_season))) 68 | stop("Not all IDs in 'rainy_season' occur in 'seasonality'!") 69 | 70 | id_sub <- 1:length(ids_season) 71 | seasonality[,1] <- id_sub 72 | rainy_season <- as.matrix(rainy_season) 73 | for(i in 1:length(ids_season)) { 74 | rows <- which(as.character(rainy_season[,1]) == ids_season[i]) 75 | rainy_season[rows,1] <- id_sub[i] 76 | } 77 | 78 | #rainy_season as integer matrix 79 | rainy_season_mat <- apply(rainy_season, 2, as.integer) 80 | 81 | # loop over different stations 82 | start_date <- strftime(paste0(head(rainy_season_mat[,2],n=1), "-01-01 00:00:00"), format="%Y-%m-%d %H:%M:%S") 83 | end_date <- strftime(paste0(tail(rainy_season_mat[,2],n=1), "-12-31 00:00:00"), format="%Y-%m-%d %H:%M:%S") 84 | output <- xts(NULL, seq.POSIXt(as.POSIXct(start_date, tz=timezone), as.POSIXct(end_date, tz=timezone), by="day")) 85 | 86 | for (s in 1:nrow(seasonality)) { 87 | 88 | sub_t <- seasonality[s,1] 89 | # get relevant rows in rainy_season 90 | rows <- which(rainy_season_mat[,1] == sub_t) 91 | dat_t <- rainy_season_mat[rows,] 92 | 93 | # loop over years 94 | out_t <- NULL 95 | for (y in unique(rainy_season_mat[,2])) { 96 | 97 | # apply function over all days of year y 98 | if (y %% 4 == 0) { 99 | days <- 366 100 | } else { 101 | days <- 365 102 | } 103 | f_out <- lapply(1:days, function(x,id=sub_t,year=y,rs=dat_t,sn=seasonality[s,c(2:5)],out=as.double(-99.9)) { 104 | .Fortran("calc_seasonality2", 105 | # INPUT # 106 | subbas_id=as.integer(id), year=as.integer(year), julian_day=as.integer(x), 107 | seasonality_in=as.integer(rs), nv=as.integer(length(rs)), 108 | support_values=as.double(sn), 109 | # OUTPUT # 110 | seasonality_out=out, 111 | PACKAGE="lumpR")$seasonality_out 112 | }) 113 | 114 | # merge with output object 115 | out_t <- c(out_t,unlist(f_out)) 116 | } # loop over years 117 | 118 | # merge with output object 119 | output <- merge.xts(output,out_t) 120 | colnames(output)[s] <- paste0("id_", sub_t) 121 | 122 | } # loop over stations 123 | 124 | colnames(output) <- sub("id_", "", colnames(output)) 125 | 126 | # re-substitute IDs 127 | colnames(output)[sort(as.integer(colnames(output)))] <- ids_season 128 | 129 | return(output) 130 | 131 | } # EOF 132 | -------------------------------------------------------------------------------- /R/internals.R: -------------------------------------------------------------------------------- 1 | #internal functions 2 | test_grass = function() #test if connection to GRASS is working properly 3 | { 4 | #test if its working 5 | testGRASS = suppressWarnings(try(execGRASS("g.version", intern = TRUE), silent=TRUE)) #test if GRASS is responding 6 | if (class(testGRASS)=="try-error") stop("GRASS session could not be initialized. Check the output of the initGRASS command for errors.") 7 | 8 | stat = attr(testGRASS, "status") 9 | if (!is.null(stat) && stat != 0) 10 | stop(paste0("Error in connecting to GRASS. Please check name of location and mapset.\n ", testGRASS)) 11 | } 12 | 13 | 14 | check_raster <- function(map, argument_name="", raiseerror=TRUE) { #check existence of raster map 15 | cur_mapset = execGRASS("g.mapset", flags="p", intern=TRUE) #determine name of current mapset 16 | if (!grepl(map, pattern = "@")) 17 | map = paste0(map,"@", cur_mapset) #add mapset name, unless already given. Otherwise, these checks may fall back on PERMANENT yielding true, but read_RAST will fail later 18 | 19 | cmd_out <-suppressWarnings(execGRASS("r.info", map=map, intern = T, ignore.stderr = TRUE)) 20 | 21 | if (!is.null(attr(cmd_out, "status")) && attr(cmd_out, "status")==1) 22 | { 23 | if (raiseerror) 24 | stop(paste0("Raster map '", map, "' not found", ifelse(argument_name=="", ".", paste0(" (argument '", argument_name,"'). If the map is in another mapset, add '@othermapset' to the name.")))) 25 | else 26 | return(FALSE) 27 | } else 28 | { 29 | if (raiseerror) 30 | return() #do nothing 31 | else 32 | return(TRUE) 33 | } 34 | 35 | 36 | } 37 | 38 | 39 | check_vector <- function(map, argument_name="") { #check existence of vector map 40 | cmd_out=suppressWarnings(execGRASS("v.info", map=map, intern = T, ignore.stderr = TRUE)) 41 | 42 | if (!is.null(attr(cmd_out, "status")) && attr(cmd_out, "status")==1) 43 | stop(paste0("Vector map '", map, "' not found", ifelse(argument_name=="", ".", paste0(" (argument '", argument_name,"'). If the map is in another mapset, add '@othermapset' to the name.")))) 44 | } 45 | 46 | read_raster <- function(raster_name) { 47 | #as of GRASS 8.3.1, rgrass0.4-1 read_RAST() on Windows does not seem to work in other than the active mapset 48 | # rGRASS 0.4-2 seems to solve this issue 49 | 50 | # #read raster from GRASS-location 51 | # #if raster exist both in local mapset and PERMANENT, force the reading of the local version, otherwise read_RAST fails 52 | # cur_mapset = execGRASS("g.mapset", flags="p", intern=TRUE) #determine name of current mapset 53 | # # mapset name in R (meta symbols replaced by ".") 54 | # cur_mapset_r = gsub("[-+*/@.?!]", ".", cur_mapset) 55 | # if (!grepl(raster_name, pattern = "@")) #expand raster name because of bug in read_RAST 56 | # { 57 | # raster_name = paste0(raster_name,"@", cur_mapset) #add mapset name, unless already given. Otherwise, strange errors may occur when the same raster exists in PERMANENT 58 | # name_expanded = TRUE #indicate that 59 | # } else name_expanded = FALSE 60 | tmp <- read_RAST(raster_name) 61 | # tmp <- raster(tmp) 62 | # if (name_expanded) #"de-expand" name, if expanded before 63 | # tmp@data@names = sub(x = tmp@data@names, pattern = paste0("\\.", cur_mapset_r), repl="") 64 | return(tmp) 65 | 66 | 67 | 68 | } 69 | 70 | clean_temp_dir <- function(file_name) { 71 | # MS Windows only: clean temporary files that otherwise can obstruct subseqent import/export operations 72 | if(.Platform$OS.type == "windows") { 73 | dir_del <- dirname(execGRASS("g.tempfile", pid=1, intern=TRUE, ignore.stderr=T)) 74 | files_del <- grep(substr(file_name, 1, 8), dir(dir_del), value = T) 75 | if (length(files_del)>0) 76 | file.remove(paste(dir_del, files_del, sep="/"), showWarnings=FALSE) 77 | } 78 | } 79 | 80 | # calculation of reservoir volume / area by empirical relationship of Molle (1989) h[m]; A[m2]; V[m3] 81 | molle_v <- function(alpha, k, A) k* (A/(alpha*k))^(alpha/(alpha-1)) 82 | molle_a <- function(alpha, k, V) (V/k * (alpha * k)^(alpha/(alpha-1)))^((alpha-1)/alpha) #cas 83 | molle_h <- function(alpha, k, A) exp(log(A/alpha/k)/(alpha-1)) 84 | 85 | cleanup = function(cleanup_pattern_ = NULL) { 86 | # restore original error handling routine 87 | olderror = try(get("olderror"), silent = TRUE) 88 | if (class(olderror) != "try-error") #no old error handler found 89 | options(error = olderror) else 90 | options(error = NULL) 91 | 92 | if (!is.null(cleanup_pattern_)) 93 | cleanup_pattern = cleanup_pattern_ else #use supplied argument, if any. Otherwise try to get a global variable 94 | { 95 | cleanup_pattern = try(get("cleanup_pattern"), silent = TRUE) 96 | if (class(cleanup_pattern) == "try-error") #no cleanup pattern defined 97 | #cleanup_pattern = paste0("*_t,",stream,"_*,", ",", points_processed, "_*") 98 | cleanup_pattern = paste0("*_t") 99 | } 100 | 101 | #cleanup function in case of errors or normal termination 102 | # stop sinking 103 | closeAllConnections() 104 | 105 | # restore original warning mode 106 | oldw = try(get("oldw"), silent = TRUE) 107 | if (class(oldw) == "try-error") #no old warning defined 108 | oldw=0 109 | 110 | if(silent) 111 | options(warn = oldw) 112 | 113 | # remove mask if there is any (and ignore error in case there is no mask) 114 | tt = try(execGRASS("r.mask", flags=c("r"), intern = TRUE, ignore.stderr = TRUE), silent = TRUE) 115 | tt <- try(execGRASS("g.region", region="region_org_t", intern = T), silent=TRUE) #restore original region settings, if any 116 | 117 | #delete temporarily created maps 118 | keep_temp = try(get("keep_temp"), silent = TRUE) 119 | if (class(keep_temp) == "try-error") #no keeptemp warning defined 120 | keep_temp=FALSE 121 | 122 | if(keep_temp == FALSE & cleanup_pattern != "") 123 | try(execGRASS("g.remove", type="raster,vector", pattern=cleanup_pattern, flags=c("f", "b"), intern = TRUE, ignore.stderr = TRUE), silent=TRUE) 124 | 125 | #olderror() #release error handling 126 | 127 | } 128 | 129 | 130 | # compareRaster_i = function(rasterlist, ...) 131 | # { 132 | # rasterlist = list(flowaccum_rast, relelev_rast, dist2river_rast, eha_rast, 133 | # qual_rast) 134 | # #check congruence of raster maps in list 135 | # #internal analogon to raster::compareRaster, which no longer seems to work on stacks [correction: seems to wiórk again, function is now obsolete] 136 | # for (rr in rasterlist[-1]) 137 | # { 138 | # if ( 139 | # !all(terra::res(rr) == terra::res(rasterlist[[1]])) 140 | # || 141 | # !(terra::ncell(rr) == terra::ncell(rasterlist[[1]])) 142 | # ) 143 | # return(TRUE) 144 | # #stop("Some raster maps do not match in resolution or extent. Please check.") 145 | # } 146 | # return(TRUE) 147 | # } 148 | -------------------------------------------------------------------------------- /man/prof_class.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/prof_class.R 3 | \name{prof_class} 4 | \alias{prof_class} 5 | \title{Classification of mean catenas} 6 | \usage{ 7 | prof_class( 8 | catena_file = NULL, 9 | catena_head_file = NULL, 10 | svc_column = "svc", 11 | dir_out = "./", 12 | luoutfile = "lu.dat", 13 | tcoutfile = "tc.dat", 14 | lucontainstcoutfile = "lucontainstc.dat", 15 | tccontainssvcoutfile = "r_tc_contains_svc.dat", 16 | terraincomponentsoutfile = "terraincomponents.dat", 17 | recl_lu = "reclass_lu.txt", 18 | saved_clusters = NULL, 19 | seed = 1312, 20 | resolution = NULL, 21 | classify_type = " ", 22 | max_com_length = NULL, 23 | com_length = NULL, 24 | make_plots = F, 25 | eha_subset = NULL, 26 | eha_blacklist = NULL, 27 | overwrite = F, 28 | silent = F, 29 | plot_silhouette = T 30 | ) 31 | } 32 | \arguments{ 33 | \item{catena_file}{Name of file containing mean catena information derived from 34 | \code{\link[lumpR]{area2catena}}.} 35 | 36 | \item{catena_head_file}{Name of file containing meta-information for classification 37 | derived from \code{\link[lumpR]{area2catena}} and adjusted manually (see \code{Notes}).} 38 | 39 | \item{svc_column}{Field name in \code{catena_head_file} that holds the information 40 | of SVCs for generating \code{tccontainssvcoutfile}. Default: 'svc'.} 41 | 42 | \item{dir_out}{Character string specifying output directory (will be created; 43 | nothing will be overwritten).} 44 | 45 | \item{luoutfile}{Output: Name of file containing the average properties of 46 | \emph{Landscape Units}.} 47 | 48 | \item{tcoutfile}{Output: Name of file containing the average properties of 49 | \emph{Terrain Components}.} 50 | 51 | \item{lucontainstcoutfile}{Output: Name of file containing information wich 52 | LU contains which TCs.} 53 | 54 | \item{tccontainssvcoutfile}{Output: Name of file containing information wich 55 | TC contains which SVCs.} 56 | 57 | \item{terraincomponentsoutfile}{Output: Name of file containing general 58 | properties of TCs.} 59 | 60 | \item{recl_lu}{Output: Name of GRASS reclassification file: EHA -> LU.} 61 | 62 | \item{saved_clusters}{Output: Name of R file that can be used to store LU 63 | characteristics for later re-use; set to NULL to omit output (default).} 64 | 65 | \item{seed}{Integer specifying seed for random processes in cluster analysis.} 66 | 67 | \item{resolution}{Integer specifying resolution of profiles/spacing of samples. 68 | Typically the resolution of your GRASS location used for \code{\link[lumpR]{area2catena}}.} 69 | 70 | \item{classify_type}{Type of classification:\cr 71 | ' ': (default) unsupervised classification, no \code{saved_clusters} will be produced\cr 72 | 'save': do unsupervised classification and save cluster centers to \code{saved_clusters} 73 | for future supervised classification\cr 74 | 'load': load cluster centers from existing file and classify according 75 | to these clusters (e.g. supervised classification). CURRENTLY NOT SUPPORTED!} 76 | 77 | \item{max_com_length}{Integer defining the maximum common length of profiles, 78 | i.e. the maximum number of support points representing each catena during the 79 | classification procedure. Too large values consume more memory and computational 80 | effort.} 81 | 82 | \item{com_length}{Integer giving common length of profiles, i.e. the number of 83 | support points representing each catena during the classification procedure. 84 | Too large values consume more memory and computational effort. Overwrites 85 | max_com_length.} 86 | 87 | \item{make_plots}{logical; visualisation of classification results written into 88 | sub-directory \emph{plots_prof_class}. WARNING: Consumes a lot of processing 89 | time and memory. Default: \code{FALSE}.} 90 | 91 | \item{eha_subset}{NULL or integer vector with subset of EHA ids that shall 92 | be processed (for debugging and testing).} 93 | 94 | \item{eha_blacklist}{NULL or integer vector with subset of EHA ids that will 95 | be excluded (use this for manual exclusion of strange profiles).} 96 | 97 | \item{overwrite}{\code{logical}. Shall output of previous calls of this function be 98 | deleted? If \code{FALSE} the function returns an error if output already exists. 99 | Default: \code{FALSE}.} 100 | 101 | \item{silent}{\code{logical}. Shall the function be silent (also suppressing warnings)? 102 | Default: \code{FALSE}.} 103 | 104 | \item{plot_silhouette}{\code{logical}. Shall a silhouette plot (illustrating the clustering 105 | process) be generated? Consumes much memory and processing time and should be disabled, 106 | if a memory error is thrown. Will be \code{FALSE} if \code{make_plots = FALSE}. 107 | Default: \code{TRUE}.} 108 | } 109 | \value{ 110 | Function returns nothing. Output files are written into output directory 111 | as specified in arguments. 112 | } 113 | \description{ 114 | Classifies mean catenas derived from \code{\link[lumpR]{area2catena}} into \emph{Landscape 115 | Units} and \emph{Terrain Components}. 116 | } 117 | \details{ 118 | This function first resamples the catenas derived from \code{\link[lumpR]{area2catena}} 119 | to a common length (\code{com_length} or the median number of support points 120 | of all catenas but not more than \code{max_com_length}). Second, k-means clustering 121 | is employed to group the catenas into representative \emph{Landscape Units} 122 | according to parameters given via \code{catena_head_file} taking into account 123 | hillslope length, shape, and supplemental properties. Third, each group is further 124 | partitioned into a given number of \emph{Terrain Components} in a way that the 125 | variance within each TC is minimized considering slope gradient and supplemental 126 | information. 127 | } 128 | \note{ 129 | Function uses output of \code{\link[lumpR]{area2catena}}. However, no GRASS 130 | session needs to be started in this case. 131 | 132 | After applying \code{recl_lu}, the resulting landscape units raster map in your GRASS 133 | location might show gaps depending on the number of generated landscape units 134 | as each landscape unit refers to the representative EHA. The gaps can be filled 135 | with GRASS function \code{r.grow}. 136 | 137 | In case of \bold{long computation times or memory issues}, try \code{make_plots = FALSE} 138 | and specify an RData file as \code{catena_file} (already in \code{\link[lumpR]{area2catena}}). 139 | } 140 | \references{ 141 | Source code based on \code{SHELL} and \code{MATLAB} scripts of Till Francke. 142 | 143 | lumpR package introduction with literature study and sensitivity analysis:\cr 144 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 145 | landscape discretisation for hillslope-based hydrological models. 146 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 147 | 148 | Theory of LUMP:\cr 149 | Francke, T.; Guentner, A.; Mamede, G.; Mueller, E. N. and Bronstert, A (2008): 150 | Automated catena-based discretization of landscapes for the derivation of 151 | hydrological modelling units. \emph{International Journal of Geographical 152 | Information Science, Informa UK Limited}, 22(2), 111-132, DOI: 10.1080/13658810701300873 153 | } 154 | \author{ 155 | Tobias Pilz, Till Francke 156 | } 157 | -------------------------------------------------------------------------------- /R/rainy_season.R: -------------------------------------------------------------------------------- 1 | # lumpR/rainy_season.R 2 | # Copyright (C) 2015-2017 Tobias Pilz 3 | # 4 | # This program is free software: you can redistribute it and/or modify 5 | # it under the terms of the GNU General Public License as published by 6 | # the Free Software Foundation, either version 3 of the License, or 7 | # (at your option) any later version. 8 | # 9 | # This program is distributed in the hope that it will be useful, 10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 | # GNU General Public License for more details. 13 | # 14 | # You should have received a copy of the GNU General Public License 15 | # along with this program. If not, see . 16 | 17 | 18 | #' Determine start and end date of the rainy season 19 | #' 20 | #' Function calculates the yearly start and end dates of the rainy season from 21 | #' a precipitation time series based on a statistical approach as described by 22 | #' Gerstengarbe & Werner (1999). 23 | #' 24 | #' @param prec_ts Daily precipitation time series object of class \code{\link[xts]{xts}}. 25 | #' Data should be a numerical vector or a matrix with one named column per 26 | #' station a time series is available for. 27 | #' 28 | #' @param dry_season Day of year in the expected centre of dry season. This is the 29 | #' starting point of the stastical procedure to look for the next rainy season 30 | #' in the data set. Should be set approximately (+- 1 month) to the centre of 31 | #' the dry season. 32 | #' @param nodata No-data value in the time series. Default: \code{NA}. 33 | #' 34 | #' @return \code{data.frame} of rainy season start and end days in input format for 35 | #' the hydrological model WASA. 36 | #' 37 | #' Columns are: station ID (column names of input \code{xts} object), year, start 38 | #' day of rainy season (negative values refer to the previous year), day of year 39 | #' the climax of the vegetation season is reached, end day of rainy season, 40 | #' last day of transition period from rainy to dry season (values greater than 41 | #' 365/366 refer to the next year). 42 | #' 43 | #' @note The first rainy season that can be identified by the function is the one 44 | #' that starts after the first dry season in the given time series. This means, 45 | #' for instance, that if the time series starts on Jan 1st 1978 and \code{dry_season} 46 | #' is set to 243 (conditions for NE Brazil), the first detectable rainy season 47 | #' is the one starting around Dec 78 to Feb 79. To get also the rainy season 48 | #' for year 1978 for this example, 365 daily values can be artifically inserted 49 | #' at the beginning of the time series, representing the hypothetical year 1977. 50 | #' Just copy the data of 1978. 51 | #' 52 | #' @references 53 | #' lumpR package introduction with literature study and sensitivity analysis:\cr 54 | #' Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 55 | #' landscape discretisation for hillslope-based hydrological models. 56 | #' \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 57 | #' 58 | #' Function uses the FORTRAN 77 code developed by \emph{Gerstengarbe et al.}. 59 | #' The algorithm is described in: 60 | #' 61 | #' Gerstengarbe & Werner (1999): Estimation of the beginning and end of recurrent 62 | #' events within a climate regime. \emph{Climate Research}, 11(2), 97-107. 63 | #' 64 | #' 65 | #' Function further used by A. Guentner to simulate vegetation dynamics within 66 | #' the hydrological model WASA: 67 | #' 68 | #' Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid 69 | #' North-East of Brazil. \emph{PIK Report 77}, Potsdam Institute for Climate 70 | #' Impact Research, Potsdam, Germany. 71 | #' 72 | #' @author Tobias Pilz 73 | #' 74 | 75 | rainy_season <- function( 76 | ### INPUT ### 77 | prec_ts=NULL, 78 | dry_season=NULL, 79 | nodata=NA 80 | ) { 81 | 82 | # check arguments 83 | if(!any(grepl("xts", class(prec_ts)))) 84 | stop("'prec_ts' needs to be of class 'xts'!") 85 | if(!is.numeric(dry_season)) 86 | stop("'dry_season' has to be given!") 87 | 88 | # check if time series is continuous 89 | if (length(seq(min(index(prec_ts)), max(index(prec_ts)), by="day")) != nrow(prec_ts)) 90 | stop("Time series of precipitation input is not continuous, check the input!") 91 | 92 | # get start date of time series 93 | start_day <- as.integer(format(index(prec_ts)[1], format="%d")) 94 | start_month <- as.integer(format(index(prec_ts)[1], format="%m")) 95 | start_year <- as.integer(format(index(prec_ts)[1], format="%Y")) 96 | 97 | no_years <- length(unique(format(index(prec_ts), format="%Y"))) 98 | no_stat <- ncol(prec_ts) 99 | 100 | # nodata must be -999.9 in fortran function 101 | if (is.na(nodata)) { 102 | prec_ts[which(is.na(prec_ts))] <- -999.9 103 | nodata <- -999.9 104 | } else { 105 | prec_ts <- apply(prec_ts, 2, function(x) replace(x, x==nodata, -999.9)) 106 | nodata <- -999.9 107 | } 108 | 109 | 110 | # loop over stations/columns of data (Fortran function can handle only one time series at a time) 111 | out <- NULL 112 | for (s in 1:no_stat) { 113 | 114 | # get vector of time series 115 | vals <- prec_ts[,s] 116 | 117 | # call external fortran function 118 | season <- .Fortran("rainyseason", 119 | # INPUT # 120 | h=as.double(vals), 121 | day=start_day, month=start_month, year=start_year, 122 | n=as.integer(length(vals)), lw=as.integer(dry_season), 123 | mima=as.integer(1), xe=as.double(nodata), 124 | # OUTPUT# 125 | outyear=as.integer(rep(-999, no_years)), 126 | outbegin=as.integer(rep(-999, no_years)), 127 | outend=as.integer(rep(-999, no_years)), 128 | PACKAGE="lumpR") 129 | 130 | # remove missing year if present 131 | na_t <- which(season$outyear==-999) 132 | season$outyear <- season$outyear[-na_t] 133 | season$outbegin <- season$outbegin[-na_t] 134 | season$outend <- season$outend[-na_t] 135 | 136 | # if outbegin > outend -> value must be 365/366 - outbegin (negative values used in WASA) 137 | greater <- which(season$outbegin > season$outend) 138 | doys <- rep(365, length(season$outyear)) 139 | doys[which((season$outyear %% 4) == 0)] <- 366 140 | season$outbegin[greater] <- -1*(doys[greater] - season$outbegin[greater]) 141 | 142 | # data.frame of fortran output 143 | out_t <- data.frame(sub_id=colnames(prec_ts)[s], 144 | year=season$outyear, 145 | begin_rainy=season$outbegin, 146 | max_veg=season$outbegin +30, 147 | end_rainy=season$outend, 148 | end_trans=season$outend+30) 149 | 150 | # merge with output data.frame 151 | out <- rbind(out,out_t) 152 | 153 | } # loop over stations / columns in time series 154 | 155 | # subbasin ID as integer, not as factor 156 | out$sub_id <- as.integer(as.character(out$sub_id)) 157 | 158 | # re-order and return 159 | out <- out[order(out$year),] 160 | rownames(out) <- NULL 161 | return(out) 162 | 163 | } # EOF 164 | -------------------------------------------------------------------------------- /man/reservoir_lumped.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/reservoir_lumped.R 3 | \name{reservoir_lumped} 4 | \alias{reservoir_lumped} 5 | \title{Generation of WASA parameter files for simulation of lumped reservoirs ("small reservoirs")} 6 | \usage{ 7 | reservoir_lumped( 8 | res_vect = NULL, 9 | subbas = NULL, 10 | res_vect_classified = NULL, 11 | dir_out = "./", 12 | reservoirs_small_classes_file = "reservoirs_small_classes.dat", 13 | r_subbas_contains_reservoirs_small_file = "r_subbas_contains_reservoirs_small.dat", 14 | res_param = data.frame(class = 1:5, f_vol_init = 0.2, class_change = 0, alpha_Molle = 15 | 2.7, damk_Molle = 1500, damc_hrr = c(7, 14, 21, 28, 35), damd_hrr = 1.5), 16 | keep_temp = F, 17 | overwrite = F, 18 | silent = F 19 | ) 20 | } 21 | \arguments{ 22 | \item{res_vect}{Name of reservoir vector map in GRASS location. Can be point 23 | or polygon feature (e.g. reservoir centroids). 24 | If it has the columns 'volume' with information on volume in [m^3] or column 'area' 25 | with information on lake area in [m^2], these will be used for computation. 26 | If none is encountered, 'area' can be generated from the area of the polygons, if present.} 27 | 28 | \item{subbas}{Name of subbasin raster map in GRASS location. Can be created with 29 | \code{\link[lumpR]{calc_subbas}}.} 30 | 31 | \item{res_vect_classified}{Output: Name for the vector reservoir map to be created in GRASS 32 | location. This is a point map based on \code{res_vect} with information of area or volume (whichever is missing), 33 | ID of the subbasin in which the reservoir is located, and the classified size class 34 | appended to the attribute table. If \code{NULL} (default) it will not be created.} 35 | 36 | \item{dir_out}{Character string specifying output directory (will be created if 37 | not available and files will be overwritten if \code{overwrite = TRUE}.} 38 | 39 | \item{reservoirs_small_classes_file}{Parameters for the reservoir size classes. 40 | See \code{\link{db_fill}}.} 41 | 42 | \item{r_subbas_contains_reservoirs_small_file}{Distribution of small reservoirs in subbasins. 43 | See \code{\link{db_fill}}.} 44 | 45 | \item{res_param}{A \code{data.frame} object containing parameters for the reservoir 46 | size classes. The default parameter set is adjusted to semi-arid Brazil. 47 | See \code{Details}.} 48 | 49 | \item{keep_temp}{\code{logical}. Set to \code{TRUE} if temporary files shall be kept 50 | in the GRASS location, e.g. for debugging or further analyses. Default: \code{FALSE}.} 51 | 52 | \item{overwrite}{\code{logical}. Shall output of previous calls of this function be 53 | deleted? If \code{FALSE} the function returns an error if output already exists. 54 | Default: \code{FALSE}.} 55 | 56 | \item{silent}{\code{logical}. Shall the function be silent (also suppressing warnings 57 | of internally used GRASS functions)? Default: \code{FALSE}.} 58 | } 59 | \value{ 60 | The two output files specified in \code{reservoirs_small_classes_file} and \code{r_subbas_contains_reservoirs_small_file}; and 61 | the vector map \code{res_vect_class} in GRASS 62 | } 63 | \description{ 64 | Function generates the WASA parameter files lake.dat and lake_number.dat from 65 | a pre-processed reservoir vector and a subbasin raster file stored in a GRASS 66 | location. 67 | } 68 | \details{ 69 | This function creates WASA input files which are needed to run the model 70 | with option \code{doacudes=.T.} (simulate small unlocated reservoirs). 71 | 72 | The default values for \code{res_param} set were estimated by Molle (1989) for the 73 | \bold{semi-arid NE of Brazil} and need to be adjusted if applied to some other region! 74 | 75 | \bold{lake_file} / \bold{res_param}\cr 76 | Specification of parameters for the reservoir size classes. Note that \code{lake_file} and \code{res_param} have the same order, but different header names! If information 77 | on 'maxlake0' / 'vol_max' is not available, you can specify 'area_max' in \code{res_param}, 78 | i.e. the maximum area of reservoir size classes in \emph{m^2}. This is internally converted to volume 79 | by relationship of Molle (1989) using parameters 'alpha_Molle' and 'damk_Molle'. 80 | If neither is given (default), the values will be estimated from the 20 % and 100 % 81 | percentiles of the value distribution of area or volume in \code{res_vect} by interpolation 82 | between both values using a logarithmic relationship. 83 | 84 | \emph{Reservoir_class-ID / class}\cr 85 | ID of reservoir size class. 86 | 87 | \emph{maxlake0 / vol_max}\cr 88 | Upper limit of reservoir size class in terms of volume in \emph{m^3}. 89 | 90 | \emph{lake_vol0_factor / f_vol_init}\cr 91 | Fraction of storage capacity that indicates the initial water volume in the 92 | reservoir size classes (\emph{dimensionless}). 93 | 94 | \emph{lake_change / class_change}\cr 95 | Factor that indicates yearly variation in the number of reservoirs of the size 96 | classes (\emph{dimensionless}). 97 | 98 | \emph{alpha_Molle, damk_Molle}\cr 99 | Parameters of the area-volume relationship in the reservoir size classes: 100 | Area = alpha_Molle * damk_Molle * (Volume / damk_Molle)^( (alpha_Molle - 1) / alpha_Molle). 101 | Unit of Area: \emph{m^2}, unit of Volume: \emph{m^3}. 102 | 103 | \emph{damc_hrr, damd_hrr}\cr 104 | Parameters of the spillway rating curve in the reservoir size classes: 105 | Overflow = damc_hrr * Height^(damd_hrr). 106 | Unit of Overflow: \emph{m^3/s}, unit of Height (over spillway): \emph{m}. 107 | } 108 | \note{ 109 | Prepare GRASS location and necessary spatial objects in advance and start 110 | GRASS session in R using \code{\link[rgrass]{initGRASS}}. 111 | 112 | Use \code{\link{reservoir_strategic}} to prepare the input for large / strategic reservoirs. 113 | 114 | Points in \code{res_vect} not overlapping with any \code{subbas} will be 115 | silently removed during processing! 116 | 117 | Polygons overlapping over various subbasins will be classified to the subbasin 118 | containing the polygon's centroid. If that occurs frequently, you should 119 | consider running \code{\link[lumpR]{reservoir_outlet}} in advance where 120 | reservoir outlet locations are estimated instead of using the centroid. 121 | } 122 | \references{ 123 | lumpR package introduction with literature study and sensitivity analysis:\cr 124 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 125 | landscape discretisation for hillslope-based hydrological models. 126 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 127 | 128 | WASA model in general:\cr 129 | Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid 130 | North-East of Brazil. \emph{PIK Report 77}, Potsdam Institute for Climate 131 | Impact Research, Potsdam, Germany. 132 | 133 | Reservoir module of the WASA model:\cr 134 | Mamede, G. L. (2008): Reservoir sedimentation in dryland catchments: Modeling 135 | and management. PhD Thesis, University of Potsdam, Germany. 136 | 137 | Reservoir parameter set herein given as standard values:\cr 138 | Molle, F. (1989): Evaporation and infiltration losses in small reservoirs. 139 | \emph{Serie Hydrologia}, 25, SUDENE / ORSTOM, Recife, Brazil, in Portuguese. 140 | } 141 | \author{ 142 | Tobias Pilz, Till Francke 143 | } 144 | -------------------------------------------------------------------------------- /src/calc_seasonality.f90: -------------------------------------------------------------------------------- 1 | ! lumpR/calc_seasonality.f90 2 | ! Copyright (C) 2014 Till Francke 3 | ! Copyright (C) 2015 Tobias Pilz 4 | ! 5 | ! This program is free software: you can redistribute it and/or modify 6 | ! it under the terms of the GNU General Public License as published by 7 | ! the Free Software Foundation, either version 3 of the License, or 8 | ! (at your option) any later version. 9 | ! 10 | ! This program is distributed in the hope that it will be useful, 11 | ! but WITHOUT ANY WARRANTY; without even the implied warranty of 12 | ! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 | ! GNU General Public License for more details. 14 | ! 15 | ! You should have received a copy of the GNU General Public License 16 | ! along with this program. If not, see . 17 | 18 | ! Code derived from WASA model rev. 135 file Hillslope/hymo_h.f90 19 | 20 | 21 | MODULE helpFunction 22 | implicit none 23 | 24 | contains 25 | 26 | function which1(boolarray) result(indexarray1) 27 | !returns index of the FIRST element that is TRUE in the input array 28 | !if there are more, issue warning, if enabled 29 | implicit none 30 | logical,dimension(:),intent(in):: boolarray 31 | integer,dimension(max(1,count(boolarray))):: indexarray 32 | integer:: indexarray1 33 | integer:: i 34 | if (count(boolarray) .eq. 0) then 35 | indexarray(:)= 0 36 | else 37 | indexarray(:)= pack((/(i,i=1,size(boolarray))/),boolarray) 38 | end if 39 | 40 | indexarray1=indexarray(1) 41 | 42 | end function which1 43 | 44 | 45 | END MODULE helpFunction 46 | 47 | 48 | 49 | 50 | 51 | 52 | SUBROUTINE calc_seasonality2(subbas_id, year, julian_day ,seasonality_in, nv, support_values, seasonality_out) 53 | !replaces calc_seasonality 54 | !compute seasonality (value of current parameter for current timestep and subbasin) by interpolation between node_n and node_n+1 55 | 56 | use helpFunction 57 | !use utils_h 58 | implicit none 59 | 60 | 61 | INTEGER, INTENT(IN) :: subbas_id, year, julian_day, nv 62 | INTEGER, DIMENSION(:,:), ALLOCATABLE :: seasonality_array 63 | INTEGER, DIMENSION(nv), INTENT(IN) :: seasonality_in 64 | REAL(8), DIMENSION(4), INTENT(IN) :: support_values !real values for 4 DOYs to be interpolated 65 | 66 | !real, target :: calc_seasonality2(size(support_values,dim=1)) !return value: a single value for each class (e.g. vegetation) 67 | !Error in readhymo: error #6678: When the target is an expression it must deliver a pointer result. E:\till\uni\wasa\wasa_svn_comp\Hillslope\readhymo.f90 1695 68 | 69 | !real, pointer :: calc_seasonality2(size(support_values,dim=1)) !return value: a single value for each class (e.g. vegetation) 70 | !error: ALLOCATABLE or POINTER attribute dictates a deferred-shape-array [CALC_SEASONALITY2] 71 | 72 | real(8) :: seasonality_out !return value: a single value for each class (e.g. vegetation) 73 | 74 | integer :: k, search_year 75 | integer :: d !distance between start node and current day (in days) 76 | integer :: d_nodes !distance between start node and end_node (in days) 77 | real :: node1_value, node2_value !parameter values at nodepoints (start and end-point of interpolation) 78 | integer :: i_node1, i_node2 !indices to relevant nodes in seasonality_array 79 | integer :: doy_node1, doy_node2 !corresponding DOYs 80 | integer :: i_matchrow1, i_matchrow2 !index to matching in seasonality_array 81 | integer :: dy !number of days in the current year (365 or 366 in leap years) 82 | 83 | 84 | !handling of leap years 85 | IF (MOD((year),4) == 0) THEN 86 | dy=366 87 | ELSE 88 | dy=365 89 | ENDIF 90 | 91 | !allocate seasonality_array and create 2D array from input 1D array 92 | allocate(seasonality_array(nv/6,6)) 93 | seasonality_array=reshape(seasonality_in, (/ nv/6, 6 /) ) 94 | 95 | 96 | if (size(seasonality_array)==1) then !no seasonality for this parameter 97 | seasonality_out=support_values(1) !use single value 98 | return 99 | end if 100 | 101 | !seasonality_out(:) = tiny(seasonality_out(1)) !flag for "not set" - initial value for all entities 102 | 103 | !DO irow=1, size(support_values,dim=1) !do loop for all rows (i.e. all vegetation classes) 104 | !find matching row in seasonality array for current entity 105 | 106 | i_node2 = 0 !not set 107 | 108 | i_matchrow1 = & 109 | which1( (seasonality_array(:,1) == subbas_id .OR. seasonality_array(:,1) == -1) .AND. & 110 | (seasonality_array(:,2) == year .OR. seasonality_array(:,2) == -1)) 111 | 112 | if (i_matchrow1 == 0) stop 'Could not find a row in seasonality_array matching subbas_id and year!' !no matching row found 113 | i_matchrow2 = i_matchrow1 !default: other node is also in the same year (row) 114 | 115 | do k=3,6 116 | if (seasonality_array(i_matchrow1, k) > julian_day) exit 117 | end do 118 | 119 | i_node1 = k - 3 120 | 121 | 122 | if (i_node1 == 0) then !current DOY is BEFORE first node, lookup other node in previous year 123 | search_year = -1 !search in the previous year for the other node 124 | elseif (i_node1 == 4) then !current DOY is AFTER last node, lookup other node in next year 125 | search_year = 1 !search in the next year for the other node 126 | else 127 | search_year = 0 !other node is still in the same year 128 | end if 129 | 130 | if (search_year /=0) then !search in the other year for the other node (interpolation over year break) 131 | i_matchrow2 = & 132 | which1( (seasonality_array(:,1) == subbas_id .OR. seasonality_array(:,1) == -1) .AND. & 133 | (seasonality_array(:,2) == year+search_year .OR. seasonality_array(:,2) == -1)) 134 | 135 | end if 136 | 137 | if (i_node2 == 0) i_node2 = MOD(i_node1,4) + 1 !only modify i_node2, if it has not been set before 138 | 139 | 140 | if (i_matchrow2 == 0) then !no matching row found... 141 | if (search_year == 1) then 142 | i_node1 = 4 !extrapolate last value 143 | else 144 | i_node1 = 1 !extrapolate first value 145 | end if 146 | seasonality_out = support_values(i_node1) 147 | return 148 | end if 149 | 150 | if (i_node1 == 0) then !swap node_1 and node_2 (interpolation over year break) 151 | k = i_matchrow2 152 | i_matchrow2 = i_matchrow1 153 | i_matchrow1 = k 154 | i_node1 = 4 155 | end if 156 | 157 | doy_node1 = seasonality_array(i_matchrow1, 2 + i_node1) 158 | doy_node2 = seasonality_array(i_matchrow2, 2 + i_node2) 159 | 160 | if (i_node1 == 4) then 161 | if (doy_node1 > 0) doy_node1 = doy_node1 - dy !force a negative value, as we are looking at the previous year 162 | if (doy_node2 < 0) doy_node2 = doy_node2 + dy !force a positive value, as we are looking at the next year 163 | end if 164 | 165 | d = julian_day - doy_node1 !distance between start node and current day (in days) 166 | if (d >= dy) d = d - dy !if current day is after all nodes 167 | d_nodes = doy_node2 - doy_node1 !distance between start node and end_node (in days) 168 | 169 | if (d < 0 .OR. d_nodes < 0) then !error (presumably in input file) 170 | stop 'Error: Got negative value when calculating distance between start node and current day (or end note)!' 171 | end if 172 | 173 | node1_value = support_values(i_node1) !parameter values at nodepoints (start and end-point of interpolation) 174 | node2_value = support_values(i_node2) 175 | seasonality_out = node1_value+ (node2_value-node1_value) * real(d)/d_nodes !linear interpolation between nodes 176 | !END DO !end loop for all rows (i.e. all vegetation classes 177 | 178 | return 179 | 180 | END SUBROUTINE calc_seasonality2 181 | 182 | 183 | 184 | -------------------------------------------------------------------------------- /man/db_echse_input.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/db_echse_input.R 3 | \name{db_echse_input} 4 | \alias{db_echse_input} 5 | \title{Create ECHSE input files} 6 | \usage{ 7 | db_echse_input( 8 | dbname, 9 | start_year = NULL, 10 | end_year = NULL, 11 | res_hourly = FALSE, 12 | tz = NULL, 13 | proj_dir = "./", 14 | proj_name = "", 15 | overwrite = F, 16 | verbose = TRUE 17 | ) 18 | } 19 | \arguments{ 20 | \item{dbname}{Name of the data source (DSN) registered at ODBC.} 21 | 22 | \item{start_year}{First year of the vegetation parameter time series (typically 23 | equal to the simulation period). Only needed if column 'yearm' in table 'rainy_season' 24 | contains values of -1. Otherwise it can be set to \code{NULL} (default).} 25 | 26 | \item{end_year}{Last year of the vegetation parameter time series (typically 27 | equal to the simulation period). Only needed if column 'yearm' in table 'rainy_season' 28 | contains values of -1. Otherwise it can be set to \code{NULL} (default).} 29 | 30 | \item{res_hourly}{\code{logical}. Do you want to run ECHSE in hourly resolution? 31 | In that case, additional 'vegPar_time_series' files 'utc_add_data.dat' and 'hour_data.dat' 32 | will be created. Argument \code{tz} needs to be given. Default: \code{FALSE}.} 33 | 34 | \item{tz}{Character string with the timezone of your location. Needed to calculate 35 | 'utc_add' if argument \code{res_hourly = TRUE}. Default: \code{NULL}.} 36 | 37 | \item{proj_dir}{Path to your working directory. Output of this function will 38 | be written to this location.} 39 | 40 | \item{proj_name}{Name of your project. In \code{proj_dir} a directory \code{proj_name} 41 | will be created containing the subdirectory 'data' containing 'parameter' and 'initials' with 42 | ECHSE input files.} 43 | 44 | \item{overwrite}{\code{logical}. Should existing files and directories be 45 | overwriten? Default: \code{FALSE}.} 46 | 47 | \item{verbose}{\code{logical}. Should detailed information during execution be 48 | printed? Default: \code{TRUE}.} 49 | } 50 | \value{ 51 | The following subdirectories and files within \code{proj_dir}/\code{proj_name}/data 52 | will be created: 53 | 54 | \bold{catchment} 55 | 56 | \emph{objDecl.dat}\cr 57 | Object declaration table containing all object definitions ,including membership to a specific 58 | object group for the current model setup. 59 | 60 | \emph{objLink.dat}\cr 61 | Table specifying object relations, i.e. which output of a certain object is the input of 62 | another object, and the type of the relation. Hereby, \code{forwardType = true} means that 63 | the source object is simulated before the target object and vice verse if \code{forwardType = false}. 64 | 65 | \bold{parameter} 66 | 67 | \emph{dummy_fun.dat}\cr 68 | Dummy parameter function file used as input if no parameter function is given for a specific 69 | object group. 70 | 71 | \emph{dummy_num.dat}\cr 72 | Dummy parameter file used as input if no parameters are given for a specific object group. 73 | 74 | \emph{paramFun_WASA_tc.dat}\cr 75 | Defines parameter functions for objects of class 'WASA_tc' whereas the specific look-up tables are 76 | given in the linked files, in this case within subdirectory 'parFun_pos2area'. These are 77 | relating the relative position along the hillslope of a certain TC within a LU to the 78 | areal fraction covered. 79 | 80 | \emph{paramNum_*.dat}\cr 81 | Parameter files containing parameter definitions of individual objects of the respective 82 | object group. Values have been derived from the WASA parameter database (ATTENTION: some 83 | parameter names have been changed and unit conversions where necessary!). For description 84 | of parameters see the ECHSE WASA engine documentation. 85 | 86 | \emph{SharedParamNum_*.dat}\cr 87 | Definition of parameter values used by all objects of a specific object group. In this 88 | case, these are largely default values of choice flags and meteorological parameters which 89 | might have to be adapted manually, see ECHSE WASA engine documentation. 90 | 91 | \bold{vegPar_time_series} 92 | 93 | Contains time series files \emph{*_data.dat} of external input/forcing variables related to 94 | vegetation grwoth. The first column is the time stamp in ISO format and the other columns 95 | contain the respective variable value at a certain location. The file \emph{input_ext_locs.dat} 96 | references the external variable to a model object, whereas one object can be referenced 97 | to different locations with specific weight (summing up to one). \bold{ATTENTION:} 98 | \emph{input_ext_locs.dat} has to be extended by separately prepared meteorological input! 99 | 100 | This function creates time series of {juliany day} (or \emph{day of year}) and 101 | different vegetation specific variables (root depth, canopy height, albedo, and leaf 102 | area index). Furthermore, time series of \emph{utc_add} and \emph{hour of day} will 103 | be created if argument \code{res_hourly = TRUE}. Vegetation growth is not explicitly 104 | modelled within the WASA engine but is deduced from four node points of the variable 105 | within a year (see WASA parameter database, table 'vegetation') and start and end of 106 | the growing season for each year estimated from a precipitation time series (see WASA 107 | parameter database table 'rainy_season' filled via lumpR functions \code{\link[lumpR]{rainy_season}} 108 | and \code{\link[lumpR]{calc_seasonality}}) or deviated by other means. 109 | 110 | \bold{initials} 111 | 112 | Initial conditions, i.e. initial values of state variables for all objects (\emph{init_scal.dat} 113 | for scalar and \emph{init_vect.dat} for vectorial state variables). 114 | 115 | Currently, soil moisture is set to a value between permanent wilting point and field capacity. Groundwater 116 | and interception storages are set to zero. 117 | 118 | To avoid crude estimates, you can as well use the state outputs of another simulation. In general, 119 | you should choose an appropriate warm-up period, which is highly catchment dependent(!), and carefully 120 | examine the development of state variables to reduce uncertainties from initial conditions. 121 | } 122 | \description{ 123 | Function takes parameters from a parameter database and generates ASCII files 124 | as input to specific model engines of the ECHSE simulation environment. 125 | } 126 | \details{ 127 | Function creates most of the input files needed for the ECHSE model engine WASA, 128 | except for meteorological forcing which has to be prepared separately considering 129 | ECHSE tools, see \url{https://github.com/echse/echse_tools}. 130 | 131 | More information about ECHSE, including the source code, documentation, specific model 132 | engines, and tools for model setup, can be found at \url{https://github.com/echse/}. For 133 | information on general file structures and how to run and install echse, read the core 134 | manual. The engine manual contains descriptions of the model engines and incorporated processes. 135 | } 136 | \note{ 137 | So far, this function is only capable of creating input files for the ECHSE model engine WASA. 138 | Other ECHSE engines cannot be initialised with this function, although that might be enabled in 139 | the future. 140 | } 141 | \references{ 142 | Theoretical description of the \bold{EC}o-\bold{H}ydrological \bold{S}imulation 143 | \bold{E}nvironment (ECHSE): 144 | 145 | Kneis, D. (2015): A lightweight framework for rapid development of object-based 146 | hydrological model engines. \emph{Environmental Modelling & Software}, 68, 110-121, 147 | doi: 10.1016/j.envsoft.2015.02.009 148 | } 149 | \author{ 150 | Tobias Pilz 151 | } 152 | -------------------------------------------------------------------------------- /man/reservoir_strategic.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/reservoir_strategic.R 3 | \name{reservoir_strategic} 4 | \alias{reservoir_strategic} 5 | \title{Assemble of reservoir parameter file for WASA for import into database with \code{\link[lumpR]{db_fill}()}} 6 | \usage{ 7 | reservoir_strategic( 8 | res_vect = NULL, 9 | subbasin = NULL, 10 | res_file = NULL, 11 | dir_out = "./", 12 | reservoir_file = "reservoir.txt", 13 | overwrite = F, 14 | silent = F 15 | ) 16 | } 17 | \arguments{ 18 | \item{res_vect}{Name of reservoir vector map in GRASS location. Should be point 19 | instead of polygon feature (i.e. reservoir outlet locations; consider function 20 | \code{\link[lumpR]{reservoir_outlet}})! For mandatory columns in attribute table 21 | see Details. In any case, column \code{subbas_id} containing the subbasin 22 | ID derived from \code{subbasin} will be added to the attribute table.} 23 | 24 | \item{subbasin}{Subbasin raster map in GRASS location. Can be created with 25 | \code{\link[lumpR]{calc_subbas}}.} 26 | 27 | \item{res_file}{tab-delimited file containing reservoir properties (fields see details) and key \code{res_id}. 28 | If set to NULL, these attributes must be contained in the attribute table of \code{res_vect}. If they are missing, 29 | they will be set to deafult values (see Details).} 30 | 31 | \item{dir_out}{Character string specifying output directory (will be created if it 32 | does not yet exist). The result file can later be imported to the database with \code{\link[lumpR]{db_fill}()}} 33 | 34 | \item{reservoir_file}{Output: File of parameters for the strategic reservoirs 35 | assigned to subbasins. To be filled into a database using \code{\link[lumpR]{db_fill}()}. 36 | This file is \bold{NOT} directly compatible with WASA-SED!} 37 | 38 | \item{overwrite}{\code{logical}. Shall output of previous calls of this function be 39 | deleted? If \code{FALSE} the function returns an error if output already exists. 40 | Default: \code{FALSE}.} 41 | 42 | \item{silent}{\code{logical}. Shall the function be silent (also suppressing warnings 43 | of internally used GRASS functions)? Default: \code{FALSE}.} 44 | } 45 | \description{ 46 | Function generates the reservoir parameter file from a pre-processed 47 | reservoir vector map and optional supplemental parameter file. 48 | } 49 | \details{ 50 | For each reservoir that should be modelled explicitly within WASA the 51 | following information need to be collected and written into the vector file's 52 | attribute table or \code{res_file}. Column order is not important. Additional 53 | columns can be given but will be ignored: 54 | 55 | \emph{res_id}\cr 56 | Unique numeric reservoir identifier (if \code{res_file} is given, it also needs to be 57 | defined in the vector file's attribute table!). 58 | 59 | \emph{name}\cr 60 | OPTIONAL: name of the reservoir. Will be filled with \code{} if not given. 61 | 62 | \emph{minlevel}\cr 63 | Initial minimum level in the reservoir [m]. Value varies because of sediment 64 | accumulation. Default: 0. 65 | 66 | \emph{maxlevel}\cr 67 | Maximum water level in the reservoir [m]. Default: Estimated using Molle's equation (alpha = 2.7, k = 1500). 68 | 69 | \emph{vol0}\cr 70 | Initial volume of the reservoir [10^3 m^3]. Value varies because of sediment 71 | accumulation. Set to '-999' if information is not available. Default: Estimated using Molle's equation (alpha = 2.7, k = 1500). 72 | 73 | \emph{storecap}\cr 74 | Initial storage capacity of the reservoir [10^3 m^3]. Value varies because of 75 | sediment accumulation. DEfault: \code{vol0} 76 | 77 | \emph{damflow}\cr 78 | Target outflow discharge of the reservoir (90 \% reliability) [m^3/s]. Default: 9.99 79 | 80 | \emph{damq_frac}\cr 81 | Fraction of Q90 released from the reservoir in regular years [-]. Default: 1 82 | 83 | \emph{withdrawal}\cr 84 | Water withdrawal discharge from the reservoir to supply the water use sectors 85 | [m^3/s]. Outflow discharge through the dam is not considered. Default: 0 86 | 87 | \emph{damyear}\cr 88 | Year of construction of the dam (YYYY). Default: 1900 89 | 90 | \emph{maxdamarea}\cr 91 | Initial maximum area of the reservoir [ha]. Value varies because of sediment 92 | accumulation. Default from GIS 93 | 94 | \emph{damdead}\cr 95 | Initial dead volume of the reservoir [10^3 m^3]. Value varies because of 96 | sediment accumulation. Default: 0.01 * storecap 97 | 98 | \emph{damalert}\cr 99 | Initial alert volume of the reservoir [10^3 m^3]. Value varies because of 100 | sediment accumulation. Default: 0.01 * storecap 101 | 102 | \emph{dama, damb}\cr 103 | Parameters of the area-volume relationship in the reservoir: 104 | area = dama * Vol^damb [-]. Values of reservoir area and volume are 105 | expressed in m^2 and m^3, respectively. Attention: These are not the Molle parameters! The correct values can be derived from them as shown in the default. 106 | Default: dama = (1/k * (alpha * k)^(alpha/(alpha-1)))^((alpha-1)/alpha), 107 | damb = (alpha-1)/alpha 108 | 109 | \emph{q_outlet}\cr 110 | Maximum outflow discharge released through the bottom outlets of the 111 | reservoir [m^3/s]. Default: 0.999 112 | 113 | \emph{fvol_botm}\cr 114 | Fraction of storage capacity that indicates the minimum storage volume for 115 | sediment release through the bottom outlets of the reservoir [-]. Default: 0.01 116 | 117 | \emph{fvol_over}\cr 118 | Fraction of storage capacity that indicates the minimum storage volume for 119 | water release through the spillway of the reservoir [-]. Default: 1 120 | 121 | \emph{damc, damd}\cr 122 | Parameters of the spillway rating curve of the reservoir: Qout = damc * Hv^damd 123 | [-]. Values of water height over the spillway and overflow discharges are 124 | expressed in m and m^3/s, respectively. 125 | Default: 1.6 * 30, 1.5 126 | 127 | \emph{elevbottom}\cr 128 | Bottom outlet elevation of the reservoir [m]. Currently ignored in WASA. Default: 99 129 | 130 | The output file \code{reservoir_file} contains the additional column \emph{pid} 131 | which is the corresponding subbasin ID determined from input \code{subbasin}. 132 | } 133 | \note{ 134 | If you applied \code{\link[lumpR]{reservoir_outlet}} using the outlet locations 135 | of strategic reservoirs as drainage points, it might be necessary to use 136 | locations of the function's output \code{points_processed} instead of the 137 | true reservoir outlet locations as otherwise the reservoirs might get assigned to 138 | the wrong subbasins! 139 | } 140 | \references{ 141 | lumpR package introduction with literature study and sensitivity analysis:\cr 142 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 143 | landscape discretisation for hillslope-based hydrological models. 144 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 145 | 146 | WASA model in general:\cr 147 | Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid 148 | North-East of Brazil. \emph{PIK Report 77}, Potsdam Institute for Climate 149 | Impact Research, Potsdam, Germany. 150 | 151 | Reservoir module of the WASA model:\cr 152 | Mamede, G. L. (2008): Reservoir sedimentation in dryland catchments: Modeling 153 | and management. PhD Thesis, University of Potsdam, Germany. 154 | } 155 | \author{ 156 | Tobias Pilz 157 | } 158 | -------------------------------------------------------------------------------- /man/area2catena.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/area2catena.R 3 | \name{area2catena} 4 | \alias{area2catena} 5 | \title{Calculates mean catena from spatial data} 6 | \usage{ 7 | area2catena( 8 | mask = NULL, 9 | flowacc = NULL, 10 | eha = NULL, 11 | distriv = NULL, 12 | elevriv = NULL, 13 | supp_quant = NULL, 14 | supp_qual = NULL, 15 | dir_out = "./", 16 | catena_out = NULL, 17 | catena_head_out = NULL, 18 | ridge_thresh = 1, 19 | min_cell_in_slope = 30, 20 | min_catena_length = 3, 21 | max_riv_dist = 10, 22 | plot_catena = F, 23 | grass_files = F, 24 | ncores = 1, 25 | eha_subset = NULL, 26 | zones = NULL, 27 | overwrite = F, 28 | silent = F, 29 | allow_debug = FALSE 30 | ) 31 | } 32 | \arguments{ 33 | \item{mask}{Raster file to be used as MASK in the GRASS location defining the 34 | area of interest. E.g. \code{basin_out} of \code{\link[lumpR]{calc_subbas}}.} 35 | 36 | \item{flowacc}{Name of flow accumulation raster map in GRASS location. Can 37 | be created with \code{\link[lumpR]{lump_grass_prep}}.} 38 | 39 | \item{eha}{Name of elementary hillslope area raster map in GRASS location. 40 | Can be created with \code{\link[lumpR]{lump_grass_prep}}.} 41 | 42 | \item{distriv}{Name of distance to river raster map in GRASS location. Can 43 | be created with \code{\link[lumpR]{lump_grass_prep}}.} 44 | 45 | \item{elevriv}{Name of relative elevation raster map in GRASS location. Can 46 | be created with \code{\link[lumpR]{lump_grass_prep}}.} 47 | 48 | \item{supp_quant}{Character vector containing names of quantitative 49 | supplemental raster maps in GRASS location; leave empty if you have none.} 50 | 51 | \item{supp_qual}{Character vector containing names of qualitative 52 | supplemental raster maps in GRASS location; leave empty if you have none.} 53 | 54 | \item{dir_out}{Character string specifying output directory (will be created; 55 | nothing will be overwritten).} 56 | 57 | \item{catena_out}{Output: Name of output file containing mean catena information 58 | as input for \code{\link[lumpR]{prof_class}}. To save computation time and 59 | memory in cases of large catchments and/or high resolution, specify a file 60 | name with ending \code{*.RData}. In such a case, a compressed RData file will be 61 | written instead of a text file.} 62 | 63 | \item{catena_head_out}{Output: Name of output header file containing meta-information 64 | as input for \code{\link[lumpR]{prof_class}}; manual adjustment necessary.} 65 | 66 | \item{ridge_thresh}{Integer specifying threshold of flow accumulation, below 67 | which a cell is considered a start of a flowpath (usually 1 for D8 68 | flowaccumulation grids, (DEFAULT), 1.5 for MFD-grids).} 69 | 70 | \item{min_cell_in_slope}{Integer specifying minimum number of cells a hillslope 71 | area must have, all smaller ones are skipped. Default: 30.} 72 | 73 | \item{min_catena_length}{Integer specifying minimum number of sampling points 74 | (cells) a catena should have. If there are less, the catena is not saved. 75 | Default: 3.} 76 | 77 | \item{max_riv_dist}{Integer specifying maximum distance to river [in cells]: 78 | if the closest cell of an EHA is farther than \code{max_riv_dist}, the EHA 79 | is skipped, otherwise all distances within the EHA are redurced by the 80 | distance of the closest cell to river. Default: 10.} 81 | 82 | \item{plot_catena}{logical; produce plots (scatter, mean catena, etc.) for 83 | each area / class (written into sub-directory \emph{plots_area2catena}).} 84 | 85 | \item{grass_files}{logical; produce GRASS reclassification files for qualitative 86 | raster data. If an attribute name starting with 'svc' is found, the respective reclass file is produced anyway.} 87 | 88 | \item{ncores}{Integer specifying number of cores that should be used for computation - allows faster parallel computations (see Details).} 89 | 90 | \item{eha_subset}{NULL or integer vector with subset of EHA ids that shall 91 | be processed (for debugging and testing).} 92 | 93 | \item{zones}{NULL or a map of zones (e.g. the subbasins) that are used to perform the computations successively (instead of all at once) 94 | to avoid memory issues} 95 | 96 | \item{overwrite}{\code{logical}. Shall output of previous calls of this function be 97 | deleted? If \code{FALSE} the function returns an error if output already exists. 98 | Default: \code{FALSE}.} 99 | 100 | \item{silent}{\code{logical}. Shall the function be silent (also suppressing summary 101 | after function execution)? Default: \code{FALSE}.} 102 | 103 | \item{allow_debug}{\code{logical}. Enable debugging by not modifying error handler Default: \code{FALSE}.} 104 | } 105 | \value{ 106 | Function returns nothing. Output files are written into output directory 107 | as specified in arguments. 108 | } 109 | \description{ 110 | Takes raster data from a GRASS location and calculates catena properties. 111 | } 112 | \note{ 113 | Prepare GRASS location and necessary raster files in advance (e.g. using 114 | \code{\link[lumpR]{lump_grass_prep}}) and start GRASS session in R using 115 | \code{\link[rgrass]{initGRASS}}. 116 | 117 | \bold{IMPORTANT:} Herein, when specifying the GRASS input maps, please do 118 | explicitly refer to the mapset if it is different from the mapset given in 119 | initGRASS() (even PERMANENT!), as otherwise internally used read_RAST() command 120 | resulted in errors under Windows. 121 | 122 | In case of \bold{long computation times or memory issues}, try \code{plot_catena = FALSE} 123 | and specify an RData file as \code{catena_out}. Furthermore, make sure your 124 | raster maps are not overly large (i.e. containing lots of NULL values around 125 | the region of interest) and are of type \code{CELL} (i.e. integer) where it makes 126 | sense (check with \code{r.info} in GRASS). 127 | 128 | Parallel option (\code{ncores}>1) may speed-up computations. It requires the packages 129 | \code{doMC} and \code{doParallel}. Set \code{ncores} to a value less than the number of cores 130 | your computer has; larger values will decrease performance. 131 | GUIs such as RStudio may not produce some runtime messages (within parallel 132 | foreach loop). 133 | 134 | File \code{catena_out} contains information about the representative catena 135 | for each hillslope (EHA). For meaning of columns see file \code{catena_head_out}. 136 | It usually contains the catena ID, the catena's profile point IDs, relative 137 | vertical elevation above hillside toe, and supplemental information averaged 138 | over all raster cells associated with a specific catena profile point. For 139 | qualitative data the latter means the areal fraction of a specific attribute 140 | class (sum over all classes of an attribute should be equal to one for a profile 141 | point), for quantitative data it is a numerical value. Averages over raster 142 | cells are weighted by relative flow path densities of the raster cells. For 143 | more details on the algorithm see the reference below. 144 | } 145 | \references{ 146 | Source code based on \code{SHELL} and \code{MATLAB} scripts of Till Francke. 147 | 148 | lumpR package introduction with literature study and sensitivity analysis:\cr 149 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 150 | landscape discretisation for hillslope-based hydrological models. 151 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 152 | 153 | Theory of LUMP:\cr 154 | Francke, T.; Guentner, A.; Mamede, G.; Mueller, E. N. and Bronstert, A (2008): 155 | Automated catena-based discretization of landscapes for the derivation of 156 | hydrological modelling units. \emph{International Journal of Geographical 157 | Information Science, Informa UK Limited}, 22(2), 111-132, DOI: 10.1080/13658810701300873 158 | } 159 | \author{ 160 | Tobias Pilz, Till Francke 161 | } 162 | -------------------------------------------------------------------------------- /R/db_extract_subcatch.R: -------------------------------------------------------------------------------- 1 | # lumpR/db_extract_subcatch.R 2 | # Copyright (C) 2017 Tobias Pilz 3 | # 4 | # This program is free software: you can redistribute it and/or modify 5 | # it under the terms of the GNU General Public License as published by 6 | # the Free Software Foundation, either version 3 of the License, or 7 | # (at your option) any later version. 8 | # 9 | # This program is distributed in the hope that it will be useful, 10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 | # GNU General Public License for more details. 13 | # 14 | # You should have received a copy of the GNU General Public License 15 | # along with this program. If not, see . 16 | 17 | #' Extracts sub-catchment(s) for specific subbasin(s) from a database 18 | #' 19 | #' This function extracts the sub-catchment(s) for selected subbasin(s) from an 20 | #' existing and fully pre-processed WASA-SED parameter database. 21 | #' 22 | #' @param dbname Name of the data source (DSN) registered at ODBC. See \code{Details} of 23 | #' \code{\link[lumpR]{db_create}}. 24 | #' 25 | #' @param sub_extract \code{vector} of type numeric with the 'pid'(s) of table 26 | #' 'subbasins' in database \code{dbname} for which the associated sub-catchments 27 | #' shall be extracted. 28 | #' 29 | #' @param dbname_new \code{vector} of type character with the names of the databases 30 | #' containing the extracted sub-catchments. Database need to be registered for ODBC 31 | #' (see \code{Details} of \code{\link[lumpR]{db_create}}). 32 | #' 33 | #' @param verbose \code{logical}. Should detailed information during execution be 34 | #' printed? Default: \code{TRUE}. 35 | #' 36 | #' @return Function returns nothing. Only the databases are processed. 37 | #' 38 | #' @details The function first copies the original databse. Then the upstream subbasins 39 | #' of the selected outlet subbasin are identified and the copied database is pruned 40 | #' accordingly. The latter only affects the tables subbasins, landscape_units, 41 | #' terrain_components, r_subbas_contains_lu, r_lu_contains_tc and r_tc_contains_svc. 42 | #' Thus, the other tables may contain redundant information which are contained to 43 | #' limit the processing time and retain the opportunity to (re-)include information 44 | #' later on. 45 | #' 46 | #' @author 47 | #' Tobias Pilz 48 | #' 49 | db_extract_subcatch <- function( 50 | dbname = NULL, 51 | sub_extract = NULL, 52 | dbname_new = NULL, 53 | verbose = T 54 | ) { 55 | 56 | if(verbose) message("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%") 57 | if(verbose) message("% START db_check()") 58 | if(verbose) message("%") 59 | 60 | # CHECKS # 61 | if(verbose) message("% Checking Arguments and pre-processing databases ...") 62 | # argument checks 63 | if(is.null(dbname)) 64 | stop("Argument 'dbname' is undefined!") 65 | if(is.null(sub_extract)) 66 | stop("Argument 'sub_extract' is undefined!") 67 | if(!is.vector(sub_extract) & class(sub_extract) != "numeric") 68 | stop("Argument 'sub_extract' is not a vector of class numeric!") 69 | if(is.null(dbname_new)) 70 | stop("Argument 'dbname_new' is undefined!") 71 | if(length(dbname_new) != length(sub_extract)) 72 | stop("Arguments 'dbname_new' and 'sub_extract' need to be vectors of the same length!") 73 | 74 | # connect to ODBC registered database 75 | con <- connect_db(dbname) 76 | 77 | # ensure MySQL/MariaDB uses ANSI quotation (double quotes instead of back ticks) 78 | if(grepl("MariaDB", odbcGetInfo(con)["DBMS_Name"], ignore.case=T)) 79 | sqlQuery(con, "SET sql_mode='ANSI';") 80 | 81 | # check current db version 82 | # get most recent db version from update sql files in source directory 83 | db_dir <- system.file("database/", package="lumpR") 84 | db_up_files <- dir(db_dir, pattern="update_[a-zA-Z0-9_]*.sql") 85 | db_ver_max <- max(as.integer(sub(".sql", "", sub("update_db_v", "", db_up_files)))) 86 | 87 | db_ver <- max(sqlFetch(con, "db_version")$version) 88 | if(db_ver < db_ver_max) { 89 | tryCatch(odbcClose(con), error=function(e){}) 90 | stop(paste0("Database version is prior to version ", db_ver_max, ". Make sure you use the latest database version (consider function db_update())!")) 91 | } 92 | 93 | # create and connect to databases of dbname_new 94 | junk <- lapply(dbname_new, db_create) 95 | con_new <- lapply(dbname_new, connect_db) 96 | 97 | 98 | if(verbose) message("% OK") 99 | 100 | 101 | 102 | # Extract SUBCATCHMENTS # 103 | if(verbose) message("%") 104 | if(verbose) message("% Looping over subcatchments to be extracted ...") 105 | 106 | # function to read database from connection and store contents on disk 107 | store_db <- function(con, table, dir) { 108 | dat <- sqlFetch(con, table) 109 | file_tmp <- paste0(dir, "/", table, ".dat") 110 | write.table(dat, file=file_tmp, row.names=F, quote=F, sep="\t") 111 | return(file_tmp) 112 | } 113 | 114 | # apply function on temporary directory over tables of dbname 115 | tmp_dir <- tempdir() 116 | tabs <- sqlTables(con)[,"TABLE_NAME"] 117 | files_save <- sapply(tabs, function(x) store_db(con, x, tmp_dir), simplify = F) 118 | 119 | # loop over sub_extract 120 | junk <- lapply(1:length(sub_extract), function(x) extract_db(sub_extract[x], dbname_new[x], con_new[[x]], files_save)) 121 | 122 | odbcCloseAll() 123 | if(verbose) message("%") 124 | if(verbose) message("% DONE!") 125 | if(verbose) message("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%") 126 | 127 | } # EOF main 128 | 129 | 130 | # internal function for database extraction 131 | extract_db <- function(sub_extract, dbname_new, con, files_db) { 132 | 133 | # tables that need to appear in new database 134 | # make sure that no temporary/redundant (e.g. manually created) tables from parent database are written 135 | tables2create <- sqlTables(con)[,"TABLE_NAME"] 136 | 137 | # read in data needed herein 138 | dat_sub <- read.table(files_db[["subbasins"]], header=T, sep="\t") 139 | dat_c_lu <- read.table(files_db[["r_subbas_contains_lu"]], header=T, sep="\t") 140 | 141 | # fill in temporarily saved tables into database 142 | files_write <- grep("db_version|meta_info|subbasins|r_subbas_contains_lu", names(files_db), invert = T, value = T) 143 | files_write <- files_write[which(files_write %in% tables2create)] 144 | junk <- lapply(files_write, function(x) writedb(con, files_db[[x]], x, overwrite=T, verbose=F)) 145 | 146 | # extract relevant subbasins (all upstream of sub_extract[i]) 147 | curr_ids <- sub_extract 148 | sub_upstr <- curr_ids 149 | while(length(curr_ids) > 0) { 150 | curr_ids <- dat_sub$pid[which(dat_sub$drains_to %in% curr_ids)] 151 | sub_upstr <- c(sub_upstr, curr_ids) 152 | } 153 | sub_rows <- which(dat_sub$pid %in% sub_upstr) 154 | dat_sub_up <- dat_sub[sub_rows,] 155 | dat_sub_up[which(dat_sub_up$pid == sub_extract), "drains_to"] <- 9999 156 | dat_sub_up$a_stream_order <- NA 157 | 158 | # delete from r_subbas_contains_lu table 159 | rows_rm <- which(!(dat_c_lu$subbas_id %in% dat_sub_up$pid)) 160 | if(length(rows_rm) == 0) { 161 | dat_c_lu_t <- dat_c_lu 162 | } else { 163 | dat_c_lu_t <- dat_c_lu[-rows_rm,] 164 | } 165 | 166 | # write data into database 167 | files_db_t <- paste(tempdir(), c("subbasins_t.dat", "r_subbas_contains_lu_t.dat"), sep="/") 168 | write.table(dat_sub_up, files_db_t[1], sep="\t", quote=F, row.names = F) 169 | write.table(dat_c_lu_t, files_db_t[2], sep="\t", quote=F, row.names = F) 170 | junk <- lapply(c("subbasins", "r_subbas_contains_lu"), function(x) writedb(con, grep(x, files_db_t, value=T), x, overwrite=T, verbose=F)) 171 | 172 | # apply db_check() to crop the other (really relevant) tables and re-calculate subbasin orde 173 | junk <- capture.output(db_check(dbname_new, check = c("delete_obsolete", "subbasin_order"), 174 | option=list(tbls_preserve=c("horizons", "vegetation", "soils", "particle_classes"), 175 | overwrite=T, update_frac_impervious=F), fix = T, verbose = F)) 176 | 177 | # update table meta_info 178 | write_metainfo(con, 179 | "db_extract_subcatch()", 180 | "all", "all", 181 | paste0("Extracted the sub-catchment information in this database from parent database ", dbname, 182 | " (includes all prior entries to meta_info)."), 183 | FALSE) 184 | } # EOF extract_db 185 | -------------------------------------------------------------------------------- /man/calc_subbas.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/calc_subbas.R 3 | \name{calc_subbas} 4 | \alias{calc_subbas} 5 | \title{Calculation of hydrological subbasins using GRASS GIS} 6 | \usage{ 7 | calc_subbas( 8 | dem = NULL, 9 | drain_points = NULL, 10 | river = NULL, 11 | flowaccum = NULL, 12 | drainage_dir = NULL, 13 | disk_swap = FALSE, 14 | basin_out = NULL, 15 | stream = NULL, 16 | points_processed = NULL, 17 | outlet = NULL, 18 | thresh_stream = NULL, 19 | thresh_sub = NULL, 20 | snap_dist = 300, 21 | rm_spurious = 0.01, 22 | keep_temp = FALSE, 23 | overwrite = FALSE, 24 | export_shp = NULL, 25 | silent = FALSE 26 | ) 27 | } 28 | \arguments{ 29 | \item{dem}{Digital Elevation Model in GRASS location used for delineation of 30 | subbasins. Should be larger than the expected catchment, otherwise artefacts 31 | close to boundaries may occur.} 32 | 33 | \item{drain_points}{\code{SpatialPoints} object containing drainage points (i.e. subbasin outlets) in 34 | units of and compliant with the projection of your respective GRASS location. 35 | Can, e.g., be imported from GRASS with 36 | \code{drain_points = read_VECT(vname = "subbas_outlets", layer=1)} \cr 37 | At least the overall basin drainage point has to be given. If \code{drain_points} contains a column 38 | \code{subbas_id} in the attribute table, its values will be used for numbering the subbasins.\cr 39 | IDs of additionally delineated subbasins (if \code{thresh_sub != NULL}) will be appended after the highest ID.} 40 | 41 | \item{river}{(optional) River vector map in GRASS location if available - use only if this vector map is strictly consistent 42 | with the DEM in use. If set to \code{NULL} 43 | (default value), the river network will be calculated by GRASS function \emph{r.watershed}.} 44 | 45 | \item{flowaccum}{(optional) Existing raster map of flow accumulation in GRASS location (saves computation time). Must correspond to a map generated by the GRASS function \code{r.watershed}. 46 | If \code{drainage_dir} or \code{flowaccum} is set to \code{NULL} (default value), both will be calculated with \emph{r.watershed}.} 47 | 48 | \item{drainage_dir}{(optional) Existing raster map of drainage direction in GRASS location(saves computation time). Must correspond to map generated by the GRASS function \code{r.watershed}. 49 | If \code{drainage_dir} or \code{flowaccum} is set to \code{NULL} (default value), both will be calculated with \emph{r.watershed}.} 50 | 51 | \item{disk_swap}{(optional) Only needed if memory requirements exceed available RAM (i.e. for very large DEMs): If set to \code{TRUE}, \code{r.watershed} uses the "-m"-flag (slower, but runs with larger DEMs)} 52 | 53 | \item{basin_out}{Output: Name of subbasins raster map exported into GRASS location.} 54 | 55 | \item{stream}{Output: Prefix of calculated stream segments vector (_vect) and 56 | raster (_rast) maps exported into GRASS location. Only generated if 57 | \code{river} is not set. Default: \code{NULL}.} 58 | 59 | \item{points_processed}{Output: Prefix of intermediate point vector files exported to GRASS location, if \code{keeptemp = TRUE}, which can be used for checking in terms of unexpected behaviour. 60 | For details, see section "Value" below.} 61 | 62 | \item{outlet}{Integer (row number) defining the catchment outlet in \code{drain_points}. 63 | If there are \code{drain_points} outside the watershed delineated for the 64 | outlet point these will be omitted. If \code{NULL} (default) and \code{drain_points} 65 | contains only one point, this will be used as catchment outlet.} 66 | 67 | \item{thresh_stream}{Integer defining threshold for stream calculation. Raster 68 | cells in accumulation map with values greater than thresh_stream are 69 | considered as streams. Needs to be set only if \code{river} is not set. 70 | Default: \code{NULL}.} 71 | 72 | \item{thresh_sub}{Integer defining threshold for (additional) subbasin calculation. Parameter for 73 | GRASS function \emph{r.watershed} defining the minimum size of an exterior 74 | watershed basin in number of grid cells. If \code{NULL} (default), only the 75 | given drainage points are used for subbasin delineation, i.e. no further subbasins created.} 76 | 77 | \item{snap_dist}{maximum distance (in map units) to use when the points in \code{drain_points} are corrected to the nearest stream segment ("snapping"). 78 | Non-snappable drainage points will be excluded with a warning. Default: 300} 79 | 80 | \item{rm_spurious}{\code{numeric}. If greater zero, spurious subbasins will 81 | be removed, i.e. those subbasins being smaller than \code{rm_spurious} times \code{thresh_sub}. 82 | Spurious subbasins are 'interior' watersheds sometimes created by GRASS function 83 | \emph{r.watershed} around stream segments below multiple tributaries. These 84 | very small subbasins produce induce unnecessary computational burden when used within a 85 | hydrological model. If removed, these areas will be merged to the next upstream 86 | subbasins, respectively. If \code{thresh_sub = NULL} (default) \code{rm_spurious} 87 | will be automatically set to \code{0}. Default: 0.01.} 88 | 89 | \item{keep_temp}{\code{logical}. Set to \code{TRUE} if temporary files shall be kept 90 | in the GRASS location, e.g. for debugging or further analyses. Default: \code{FALSE}.} 91 | 92 | \item{overwrite}{\code{logical}. Shall existing GRASS layers of previous calls of this function be 93 | overwritten? If \code{FALSE}, the function returns an error if a layer already exists. 94 | Default: \code{FALSE}.} 95 | 96 | \item{export_shp}{\code{character} . Path for exporting the generated subbasin maps to shp-file. May be used as input to processing chain in SoilDataPrep. Default: NULL} 97 | 98 | \item{silent}{\code{logical}. Shall the function be silent (also suppressing warnings 99 | of internally used GRASS functions)? Default: \code{FALSE}.} 100 | } 101 | \value{ 102 | 103 | } 104 | \description{ 105 | Takes DEM from a GRASS location and a point layer of drainage points and/or areal threshold to calculate 106 | hydrological subbasins using GRASS functions. 107 | } 108 | \details{ 109 | The function delineates subbasins. It can use user-specified outlet points via parameter \code{drain_points}, and/or the area-threshold \code{param thresh_sub}. 110 | The user-specified outlet points are snapped to the nearest river segment (to fix inaccuracies) and will result in mandatory subbasins. 111 | The area-threshold serves for delineation of further subbasins (if necessary), and potential merging of too-small subbasins to their upstream neighbours. 112 | } 113 | \note{ 114 | \bold{Prepare GRASS location} and necessary raster files in advance and start 115 | GRASS session in R using \code{\link[rgrass]{initGRASS}}. The GRASS location 116 | should not contain any maps ending on *_t as these will be considered temporary maps and removed. 117 | 118 | You should select your DEM \bold{sufficiently large}. Otherwise, the resulting 119 | catchment might be truncated or boundaries influence the calculation 120 | of stream segments. 121 | 122 | \bold{Check the results} (subbasins and snapped points). In case points have been snapped 123 | to the wrong stream segment, adjust outlet point locations manually in GRASS and re-run 124 | the function with the updated locations (use \code{\link[rgrass]{read_VECT}} 125 | to import the updated drainage points). 126 | 127 | Generated raster and vector stream \bold{maps might slightly deviate} from each other 128 | as the raster map is thinned (GRASS function \emph{r.thin}) prior to conversion 129 | to a vector map to ensure strictly linear features. 130 | 131 | If you run into \bold{memory issues}, consider argument \code{disk_swap} (see also 132 | \link[GRASS homepage]{https://grass.osgeo.org/grass74/manuals/r.watershed.html#in-memory-mode-and-disk-swap-mode}) 133 | and see discussion on \link[lumpR's github page]{https://github.com/tpilz/lumpR/issues/16}. 134 | } 135 | \references{ 136 | lumpR package introduction with literature study and sensitivity analysis:\cr 137 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 138 | landscape discretisation for hillslope-based hydrological models. 139 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 140 | SoilDataPrep: Package for prepare soil input for hydrological modelling from SoilGrids and Pelettier-data, specifically with WASA-SED. https://github.com/TillF/SoilDataPrep 141 | } 142 | \author{ 143 | Tobias Pilz, Till Francke 144 | } 145 | -------------------------------------------------------------------------------- /man/lump_grass_prep.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/lump_grass_prep.R 3 | \name{lump_grass_prep} 4 | \alias{lump_grass_prep} 5 | \title{Pre-processing for Landscape Unit deviation using GRASS GIS} 6 | \usage{ 7 | lump_grass_prep( 8 | mask = NULL, 9 | dem = NULL, 10 | lcov = NULL, 11 | soil = NULL, 12 | watermask = NULL, 13 | imperviousmask = NULL, 14 | eha = NULL, 15 | flowdir = NULL, 16 | flowacc = NULL, 17 | stream = NULL, 18 | disk_swap = FALSE, 19 | stream_horton = NULL, 20 | elevriv = NULL, 21 | distriv = NULL, 22 | mask_corr = NULL, 23 | svc = NULL, 24 | dir_out = NULL, 25 | svc_ofile = NULL, 26 | eha_thres = NULL, 27 | sizefilter = NULL, 28 | growrad = NULL, 29 | keep_temp = F, 30 | overwrite = F, 31 | silent = F, 32 | addon_path = NULL, 33 | things2do = c("eha", "river", "svc") 34 | ) 35 | } 36 | \arguments{ 37 | \item{mask}{Mask in GRASS location defining the catchment area (e.g. subbasin raster map).} 38 | 39 | \item{dem}{Digital elevation model in GRASS location used for delineation of 40 | environmental hillslope areas. Should be larger than the expected catchment, 41 | otherwise artefacts close to boundaries may occur.} 42 | 43 | \item{lcov}{Landcover / vegetation raster map in GRASS location.} 44 | 45 | \item{soil}{Soil raster map in GRASS location.} 46 | 47 | \item{watermask}{Raster in GRASS location masking water surfaces (value '1') from 48 | other areas (value '0'). Map is used for \code{svc} creation such that a 49 | \code{svc} is completely covered with water ('special_area' in \code{svc_ofile} 50 | equal to 1) or contains no water surface. The map must NOT contain NULL 51 | values within \code{mask}! Default: \code{NULL}.} 52 | 53 | \item{imperviousmask}{The same as for \code{watermask} but for impervious (e.g. urban 54 | and/or rocky) areas. 'special_area' flag in \code{svc_ofile} equal to 2. The map 55 | must NOT contain NULL values within \code{mask}!} 56 | 57 | \item{eha}{Output: Name of Environmental Hillslope Areas (EHA) raster map 58 | exported into GRASS location.} 59 | 60 | \item{flowdir}{Output: Name of flow direction raster map exported into GRASS 61 | location. Provides the "aspect" for each cell measured counterclockwise 62 | from East. Multiplying positive values by 45 will give the direction in 63 | degrees that the surface runoff will travel from that cell; zero indicates 64 | a depression; negative values that surface runoff is leaving the defined region.} 65 | 66 | \item{flowacc}{Output: Name of flow accumulation raster map exported into GRASS 67 | location. Gives the number of upslope cells plus one. Negative values indicate 68 | surface runoff from outside the defined region.} 69 | 70 | \item{stream}{Output: Name of stream segments raster map exported into GRASS 71 | location. If you want to convert it into a vector map apply GRASS function 72 | \emph{r.thin} beforehand!} 73 | 74 | \item{disk_swap}{(optional, default: FALSE) Only needed if memory requirements exceed available RAM (large DEMs): If set to \code{TRUE}, \code{r.watershed} uses the "-m"-flag (slow)} 75 | 76 | \item{stream_horton}{Output: Name of stream segments raster map in Horton stream 77 | order exported into GRASS location.} 78 | 79 | \item{elevriv}{Output: Name of relative elevation raster map exported into GRASS 80 | location. Provides the elevations above stream node in units of \code{dem}.} 81 | 82 | \item{distriv}{Output: Name of distance to river raster map exported into GRASS 83 | location. Provides distances to stream node in number of grid cells.} 84 | 85 | \item{mask_corr}{DEPRECATED! Argument kept for backwards compatibility.} 86 | 87 | \item{svc}{Output: Name of Soil Vegetation Components raster map exported into 88 | GRASS location; cross product of categories of \code{soil} and \code{lcov}.} 89 | 90 | \item{dir_out}{Character string specifying output directory (will be created; 91 | nothing will be overwritten).} 92 | 93 | \item{svc_ofile}{Output: Name of file containing properties of \code{svc}s. For 94 | 'special_area' flag values of 1 for water areas, 2 for impervious areas and 95 | 0 in case it is an ordinary SVC are defined.} 96 | 97 | \item{eha_thres}{Integer specifying threshold for delineation of \emph{EHA} in cells; 98 | parameter for GRASS function \emph{r.watershed}. This is a crucial parameter 99 | affecting the size of delineated hillslopes and the degree of detail of the 100 | landscape discretisation! As a rule of thumb, a value 10-100 times smaller 101 | than \code{thresh_sub} of function \code{\link[lumpR]{calc_subbas}} is usually 102 | a good choice.} 103 | 104 | \item{sizefilter}{Integer specifying the minimum size of EHAs in hectares. 105 | Smaller EHAs (possibly artefacts) will be removed. Parameter for 106 | GRASS function \emph{r.reclass.area}. If set to \code{NULL} (default), 107 | it will be automatically set to a value equivalent to 50 grid cells (ATTENTION: 108 | meters will be assumed as unit of the GRASS projection!).} 109 | 110 | \item{growrad}{Integer specifying growing radius (in raster cells) to remove 111 | holes in the EHA raster resulting from cleaning of artefacts. This parameter is used 112 | in the GRASS function \emph{r.grow}. If set to \code{NULL} (default), it will be 113 | the value 25 will be used (larger values close larger holes, but make for longer computation times!).} 114 | 115 | \item{keep_temp}{\code{logical}. Set to \code{TRUE} if temporary files shall be kept 116 | in the GRASS location, e.g. for debugging or further analyses. Default: \code{FALSE}.} 117 | 118 | \item{overwrite}{\code{logical}. Shall output of previous calls of this function be 119 | deleted? If \code{FALSE} the function returns an error if output already exists. 120 | Default: \code{FALSE}.} 121 | 122 | \item{silent}{\code{logical}. Shall the function be silent (also suppressing warnings 123 | of internally used GRASS functions)? Default: \code{FALSE}.} 124 | 125 | \item{addon_path}{Character string giving the path to your locally installed 126 | GRASS add-ons. Must only be given if necessary, see \code{Note}.} 127 | 128 | \item{things2do}{\code{c("eha","river","svc")}. Enables the specification of sub-tasks only. \code{"eha"}: do EHA generation, 129 | \code{"river"}: calculate river network and morphological parameters, \code{"svc"}: generate SVC map} 130 | } 131 | \value{ 132 | Function returns nothing. Output raster files as specified in arguments 133 | (see above) are written into GRASS location. 134 | } 135 | \description{ 136 | Takes raster data from a GRASS location and calculates elementary hillslopes, 137 | soil-vegetation-components, and Horton stream order using GRASS functions 138 | needed for further Landscape Unit deviation. 139 | } 140 | \note{ 141 | Prepare GRASS location and necessary raster files in advance and start 142 | GRASS session in R using \code{\link[rgrass]{initGRASS}}. 143 | 144 | Make sure that the GRASS functions \emph{r.stream.distance} and \emph{r.stream.order} 145 | are available to your GRASS installation. If not, consider \emph{g.extension} to 146 | install these add-ons. If you installed add-ons locally, it might occur that from within R 147 | the path to the add-ons is not recognised. In such a case locate the local installation 148 | path (in a GRASS terminal check \code{g.extension -a}, \code{echo $GRASS_ADDON_BASE} and \code{which r.stream.distance} / \code{where r.stream.distance}, and specify the 149 | absolute path to add-ons via argument \code{addon_path}. In Windows, replace backslashes for slashes. For more information, see also 150 | \url{http://grasswiki.osgeo.org/wiki/AddOns/}. 151 | 152 | See GRASS documentation for further information on GRASS functions and 153 | parameters. 154 | 155 | If you run into \bold{memory issues}, consider argument \code{disk_swap} (see also 156 | \link[GRASS homepage]{https://grass.osgeo.org/grass74/manuals/r.watershed.html#in-memory-mode-and-disk-swap-mode}) 157 | and see discussion on \link[lumpR's github page]{https://github.com/tpilz/lumpR/issues/16}. 158 | } 159 | \references{ 160 | Source code based on \code{SHELL} and \code{MATLAB} scripts of Till Francke. 161 | 162 | lumpR package introduction with literature study and sensitivity analysis:\cr 163 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 164 | landscape discretisation for hillslope-based hydrological models. 165 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 166 | 167 | Theory of LUMP:\cr 168 | Francke, T.; Guentner, A.; Mamede, G.; Mueller, E. N. and Bronstert, A (2008): 169 | Automated catena-based discretization of landscapes for the derivation of 170 | hydrological modelling units. \emph{International Journal of Geographical 171 | Information Science, Informa UK Limited}, 22(2), 111-132, DOI: 10.1080/13658810701300873 172 | } 173 | \author{ 174 | Tobias Pilz 175 | } 176 | -------------------------------------------------------------------------------- /man/db_wasa_input.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/db_wasa_input.R 3 | \name{db_wasa_input} 4 | \alias{db_wasa_input} 5 | \title{Create WASA input files} 6 | \usage{ 7 | db_wasa_input( 8 | dbname, 9 | dest_dir = "./", 10 | files = c("info.dat", "River/routing.dat", "River/response.dat", "Hillslope/hymo.dat", 11 | "Hillslope/soter.dat", "Hillslope/terrain.dat", "Hillslope/soil_vegetation.dat", 12 | "Hillslope/soil.dat", "Hillslope/vegetation.dat", "Hillslope/svc_in_tc.dat", 13 | "do.dat", "maxdim.dat", "part_class.dat", "Hillslope/soil_particles.dat", 14 | "Hillslope/rainy_season.dat", "Hillslope/x_seasons.dat", "Hillslope/svc.dat", 15 | "Reservoir/reservoir.dat", "Reservoir/lake.dat", "Reservoir/lake_number.dat", 16 | "Reservoir/lake_maxvol.dat"), 17 | overwrite = F, 18 | verbose = TRUE 19 | ) 20 | } 21 | \arguments{ 22 | \item{dbname}{Name of the data source (DSN) registered as ODBC source.} 23 | 24 | \item{dest_dir}{The directory in which the output files (= WASA input files) will be 25 | written. Will be created if it does not exist. Default: \code{./}. Will include the 26 | sub-directories 'Hillslope' and 'River'.} 27 | 28 | \item{files}{Character vector specifying WASA input files that should be created. 29 | See \code{Details}. By default, all files will be created.} 30 | 31 | \item{overwrite}{\code{logical}. Should existing files in \code{dest_dir} be 32 | overwritten? Default: \code{FALSE}.} 33 | 34 | \item{verbose}{\code{logical}. Should detailed information during execution be 35 | printed? Default: \code{TRUE}.} 36 | } 37 | \description{ 38 | Function retrieves parameters from a parameter database and generates ASCII files 39 | as input to the hydrological model WASA. 40 | } 41 | \details{ 42 | Consider function \code{\link[lumpR]{db_check}} before running this function to ensure consistency 43 | and completeness of data in the database. Otherwise, the input files might contain 44 | errors, which might lead to errors or unexpected results during model application. 45 | 46 | Note differences in variable notations between parameter database and WASA's 47 | input files! 48 | 49 | Sediment transport specific variables are not yet included, please configure \code{erosion.ctl} manually. 50 | 51 | The following files will be created: 52 | 53 | \bold{info.dat}\cr 54 | General information (actual date, parameter database version etc.). 55 | 56 | \bold{River/routing.dat}\cr 57 | File contains routing order (i.e. flow direction) at subbasin level. 58 | 59 | \bold{River/response.dat}\cr 60 | File contains routing parameters (lag time and retention in \emph{days}) 61 | at subbasin level. 62 | 63 | 64 | \bold{Hillslope/hymo.dat}\cr 65 | File contains relations between subbasins and landscape units. Only subbasins 66 | present in table 'subbasins' AND 'r_subbas_contains_lu' will be considered. 67 | Columns: 68 | 69 | \emph{Subbasin-ID}\cr 70 | ID of subbasin. 71 | 72 | \emph{Area}\cr 73 | Area of each subbasin in \emph{km^2} (including reservoir areas). 74 | 75 | \emph{nbr}\cr 76 | Number of landscape units in the respective subbasin. 77 | 78 | \emph{LU-IDs}\cr 79 | IDs of landscape units in the respective subbasin 80 | 81 | \emph{areal_fraction_of_LU}\cr 82 | Areal fraction of each LU in the respective subbasin. 83 | 84 | 85 | \bold{Hillslope/soter.dat}\cr 86 | File contains landscape unit parameters and associated terrain components. Only LUs 87 | present in table 'landscape_units' AND 'r_lu_contains_tc' will be considered. 88 | 89 | \emph{LU-ID}\cr 90 | ID of landscape unit. 91 | 92 | \emph{No._of_TC}\cr 93 | Number of TCs in the corresponding LU. 94 | 95 | \emph{TC1}\cr 96 | ID of first terrain component. 97 | 98 | \emph{TC2}\cr 99 | ID of second terrain component. 100 | 101 | \emph{TC3}\cr 102 | ID of third terrain component. 103 | 104 | \emph{TCx}\cr 105 | IDs of the other TCs as specified in field \emph{No._of_TC} (if available). 106 | 107 | \emph{kfsu[mm/d]}\cr 108 | Hydraulic conductivity of bedrock in \emph{mm/d}. 109 | 110 | \emph{length[m]}\cr 111 | Mean slope length in LU in \emph{m}. 112 | 113 | \emph{meandep[mm]}\cr 114 | Mean maximum depth of soil zone in \emph{mm}. 115 | 116 | \emph{maxdep[mm]}\cr 117 | Maximum depth of alluvial soil zone in \emph{mm}. 118 | 119 | \emph{Riverbed[mm]}\cr 120 | Depth of River bed below terrain component in \emph{mm}. 121 | 122 | \emph{gwflag[0/1]}\cr 123 | Groundwater flag for LU. 0: no groundwater, 1: with groundwater. 124 | 125 | \emph{gw_dist[mm]}\cr 126 | Initial depth of groundwater below surface in \emph{mm}. 127 | 128 | \emph{frgw_delay[day]}\cr 129 | Storage coefficient for groundwater outflow in \emph{days}. 130 | 131 | 132 | \bold{Hillslope/terrain.dat}\cr 133 | File contains specification of terrain components. Only TCs 134 | present in tables 'terrain_components' AND 'r_lu_contains_tc' will be considered. 135 | 136 | \emph{TC-ID}\cr 137 | ID of terrain component. 138 | 139 | \emph{fraction}\cr 140 | Areal fraction of TC in corresponding LU. 141 | 142 | \emph{slope[\%]}\cr 143 | Slope of TC in \emph{\%}. 144 | 145 | \emph{position}\cr 146 | Number indicating the relative position of TC along the hillslope. 1: highland, 147 | 2: middle, ..., [highest number]: foot slope. 148 | ATTENTION: The order in WASA input file is reversed in comparison to order within 149 | database! 150 | 151 | 152 | \bold{Hillslope/svc_in_tc.dat}\cr 153 | SVC relations to TC. 154 | 155 | 156 | \bold{Hillslope/soil_vegetation.dat}\cr 157 | Definition of soil vegetation components. Only SVCs occurring in table 'r_tc_contains_svc' 158 | will be considered. 159 | 160 | 161 | \bold{Hillslope/soil.dat}\cr 162 | Horizon specific soil parameters. See file header and \code{\link[lumpR]{db_fill}} 163 | for more information. Only soil types occurring in tables 'soil_veg_components' 164 | and 'r_tc_contains_svc' will be considered. 165 | 166 | \bold{Hillslope/vegetation.dat}\cr 167 | Vegetation parameters. See file header and \code{\link[lumpR]{db_fill}} 168 | for more information. Only vegetation types occurring in table 'soil_veg_components' 169 | and 'r_tc_contains_svc' will be considered. 170 | 171 | \bold{do.dat}\cr 172 | File contains general parameters and control flags for WASA. See file's comments for 173 | more information. Manual investigation and adjustment after creation is necessary 174 | (e.g. for input/output directories, start/stop year of simulation etc.). Note that, 175 | depending on your choices, the manual creation of additional input files will 176 | be necessary. Consult the WASA documentation. 177 | 178 | \bold{maxdim.dat}\cr 179 | \emph{Optional} file that contains maximum dimensions of spatial units to 180 | optimise memory management and improve computational performance. 181 | 182 | \bold{part_class.dat}\cr 183 | \emph{Optional} file for sediment modelling of multiple particle size classes. 184 | File defines the number and the properties of the particle sizes that will be 185 | modelled. Please note that class numbering has to be continuous, starting with 186 | 1. The particle size classes must be ordered from fine to coarse. 187 | 188 | \bold{gauges_catchment_area.txt}\cr 189 | \emph{Optional, auxiliary file not needed by WASA} File relating subcatchment sizes, gauge names and upstream areas. Can be used for calibration workflow. 190 | 191 | \bold{Hillslope/soil_particles.dat}\cr 192 | File contains particle size distributions of topmost soil horizons. 193 | 194 | \bold{Hillslope/rainy_season.dat, Hillslope/x_seasons.dat, }\cr 195 | \emph{Optional} file defining days of year (i.e. nodes, cf. vegetation parameters) 196 | of the rainy/growing season for each year, subbasin and vegetation type. See 197 | doc of \code{\link[lumpR]{db_fill}} and \code{\link[lumpR]{rainy_season}} for 198 | more information. If this file is not supplied, only the first node value of 199 | seasonal vegetation parameters is used. 200 | 201 | \bold{Hillslope/svc.dat}\cr 202 | \emph{Optional} file defining soil vegetation components and giving some erosion 203 | parameters. Mandatory for WASA's sediment module and/or saving/loading of model 204 | states. See doc of \code{\link[lumpR]{db_fill}} (-> 'soil_veg_components') for 205 | description of header. 206 | 207 | \bold{Reservoir/reservoir.dat}\cr 208 | \emph{Optional} file defining properties of strategic reservoirs. 209 | 210 | \bold{Reservoir/lake.dat, lake_number.dat, lake_maxvol.dat}\cr 211 | \emph{Optional} file defining properties of small reservoirs. 212 | } 213 | \references{ 214 | lumpR package introduction with literature study and sensitivity analysis:\cr 215 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 216 | landscape discretisation for hillslope-based hydrological models. 217 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 218 | } 219 | \author{ 220 | Tobias Pilz, Till Francke 221 | } 222 | -------------------------------------------------------------------------------- /R/db_create.R: -------------------------------------------------------------------------------- 1 | # lumpR/db_create.R 2 | # Copyright (C) 2015, 2017 Tobias Pilz 3 | # 4 | # This program is free software: you can redistribute it and/or modify 5 | # it under the terms of the GNU General Public License as published by 6 | # the Free Software Foundation, either version 3 of the License, or 7 | # (at your option) any later version. 8 | # 9 | # This program is distributed in the hope that it will be useful, 10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 | # GNU General Public License for more details. 13 | # 14 | # You should have received a copy of the GNU General Public License 15 | # along with this program. If not, see . 16 | 17 | 18 | 19 | #' Create parameter database 20 | #' 21 | #' Function creates tables in a pre-defined database to store parameters relevant 22 | #' for modelling applications with the WASA model. 23 | #' 24 | #' @param dbname Name of the data source (DSN) registered at ODBC. See \code{Details}. 25 | #' @param overwrite \code{c(NULL,"drop","empty")}. Delete and re-create (\code{"drop"}) or empty (\code{"empty"}) any tables already existing in db. Default: NULL (keep all existing tables). In any case, tables included in \emph{keep_tables} remain untouched. 26 | #' @param keep_tables Vector of type \code{character}. Preserves the specified tables, if existing. Overrides \emph{overwrite}. Default: NULL. 27 | #' @param db_ver \code{numeric}. If \code{Inf} (default) the database will be updated 28 | #' to the latest version calling \code{\link[lumpR]{db_update}} internally. Otherwise, the 29 | #' specified version is created. The earliest possible version is 19. 30 | #' @details 31 | #' This package uses the ODBC interface to connect to a database. Creating the database 32 | #'requires the following prior steps which are OS dependent: 33 | #' \itemize{ 34 | #' \item{Install a \emph{Database Management System} and respective \emph{ODBC-driver} and on your computer. 35 | #' Currently supported (tested) are: SQLite (v. 3.8.9), MariaDB/MySQL (v. 10.0.17), 36 | #' MS Access.} 37 | #' \item{Register an empty database at your ODBC configuration.} 38 | #' } 39 | #'Calling \emph{db_create} creates the necessary tables in the database. These are then filled and processed by subsequent function of \emph{lumpR}. 40 | #'More information can be found at the lumpR package wiki: \url{https://github.com/tpilz/lumpR/wiki} 41 | #' 42 | #' @references 43 | #' lumpR package introduction with literature study and sensitivity analysis:\cr 44 | #' Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 45 | #' landscape discretisation for hillslope-based hydrological models. 46 | #' \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 47 | #' 48 | #' @author 49 | #' Tobias Pilz, Till Francke 50 | #' 51 | db_create <- function( 52 | dbname, overwrite=NULL, keep_tables=NULL, db_ver=Inf 53 | ) { 54 | 55 | if(db_ver < 19) { 56 | stop("Argument 'db_ver' less than 19 is not possible.") 57 | } 58 | 59 | if (is.null(overwrite)) overwrite="" #facilitates following conditionals 60 | 61 | # connect to ODBC registered database 62 | con <- connect_db(dbname) 63 | 64 | dbs_name = odbcGetInfo(con)["DBMS_Name"] #determine the kind of database used 65 | # ensure MySQL/MariaDB uses ANSI quotation (double quotes instead of back ticks) 66 | if(grepl("MariaDB", dbs_name, ignore.case=T)) 67 | sqlQuery(con, "SET sql_mode='ANSI';") 68 | 69 | if(grepl("ACCESS", dbs_name, ignore.case=T) && overwrite=="drop") 70 | warning("You are using an Access database and option overwrite='drop'. Due to technical restrictions, this may cause errors. In this case, please delete the tables manually using MS Access and re-run without this option.") 71 | 72 | #get current version of DB, if any 73 | db_ver_init = sqlQuery(con, "select version from db_version;") 74 | if (is.data.frame(db_ver_init)) 75 | db_ver_init = db_ver_init$version[nrow(db_ver_init)] #use last row 76 | else 77 | db_ver_init = 19 #no current version available, assume the first of db_update 78 | 79 | 80 | if (overwrite == "empty") 81 | keep_tables = unique(c(keep_tables, "db_version")) #conserve table "db_version" anyway 82 | 83 | if (overwrite == "drop" && ("db_version" %in% keep_tables)) 84 | warning("Dropping all tables but keeping 'db_version' will likely corrupt the updating process. Please do not conserve this table or reset db_version manually.") 85 | 86 | 87 | # read file with sql statements to create tables of the database 88 | sql_file <- system.file("database/create_db.sql", package="lumpR") 89 | script <- readLines(sql_file) 90 | 91 | # identify individual queries of the script 92 | script <- gsub("--.*", "", script) 93 | script <- gsub("\t", "", script) 94 | script <- paste(script, collapse=" ") 95 | scriptparts <- strsplit(script, ";")[[1]] 96 | scriptparts <- scriptparts[-length(scriptparts)] 97 | 98 | if (overwrite=="") 99 | keep_tables = sqlTables(con)$TABLE_NAME #keep all existing tables 100 | 101 | # loop over queries 102 | tbls_created <- NULL 103 | for(i in seq(along=scriptparts)){ 104 | 105 | statement <- scriptparts[i] 106 | 107 | # identify table name 108 | is_create_statement = grepl(statement, pattern="^[[:space:]]*CREATE|create") 109 | 110 | if (is_create_statement) { 111 | tablename <- gsub("CREATE TABLE *([[:alpha:]_]+).*","\\1",statement) 112 | tbls_created <- c(tbls_created, gsub("[[:space:]]*", "", tablename)) 113 | } else 114 | tablename <- gsub("INSERT INTO *([[:alpha:]_]+).*","\\1",statement) #extract name of table from CREATE statements 115 | if (tablename == statement) tablename="(none)" #set to "(none)" for non-CREATE statements 116 | tablename <- gsub("[[:space:]]*", "", tablename) 117 | 118 | 119 | # adjust to specific SQL dialects 120 | statement <- sql_dialect(con, statement) 121 | 122 | skip=TRUE 123 | if(is_create_statement & tablename %in% sqlTables(con)$TABLE_NAME) 124 | { 125 | if (!is.null(overwrite) & !(tablename %in% keep_tables)) #delete / empty existing table 126 | { 127 | if (overwrite %in% c("drop","empty")) 128 | { 129 | if (overwrite=="drop") 130 | { 131 | s2 = paste0("drop table ", tablename,";") 132 | skip = FALSE 133 | } 134 | if (overwrite=="empty") 135 | { 136 | s2 = paste0("DELETE FROM ", tablename,";") 137 | message(paste0("Found existing table ", tablename, ", emptying...")) 138 | #browser() 139 | } 140 | res <- sqlQuery2(con, s2, info = "deleting (from) table") 141 | } 142 | } 143 | } else { 144 | skip <- FALSE 145 | } 146 | 147 | if (!is_create_statement & (tablename %in% keep_tables)) #don't alter tables that are to be kept 148 | skip = TRUE 149 | 150 | 151 | if (skip & !is.null(overwrite) && (overwrite!="empty")) 152 | message(paste0("Found existing table ", tablename, ", preserved. Use overwrite=... to drop or empty it.")) 153 | else 154 | if (!skip) 155 | { 156 | #browser() 157 | # create table in database if it does not yet exist 158 | res <- sqlQuery2(con, statement, info = "(creating db)") 159 | 160 | } # skip? 161 | 162 | } # loop over scriptparts 163 | 164 | # delete other tables (those that shall not be preserved and are not part of the base version 19 which is created here) 165 | tbls <- sqlTables(con, tableType="TABLE")[,"TABLE_NAME"] 166 | tbls = tbls[!grepl(x = tbls, "^MSys")] #ignore MS Access internal tables 167 | 168 | r_tbls_del <- which(!(tbls %in% c(keep_tables, tbls_created))) 169 | for (tbl in tbls[r_tbls_del] ) { 170 | statement = paste0("drop table ", tbl,";") 171 | res <- sqlQuery2(con, statement, info="deleting superfluous tables") 172 | } 173 | 174 | # update table meta_info 175 | meta_dat <- sqlFetch(con, "meta_info") 176 | if(any(meta_dat$pid)) { 177 | pid_new <- max(meta_dat$pid) +1 178 | } else { 179 | pid_new <- 1 180 | } 181 | 182 | db_ver_cur = sqlQuery(con, "select version from db_version;") 183 | db_ver_cur = db_ver_cur$version[nrow(db_ver_cur)] #use last row 184 | 185 | meta_out <- data.frame(pid=pid_new, 186 | mod_date=as.POSIXct(Sys.time()), 187 | mod_user=paste0("db_create(), v. ", installed.packages()["lumpR","Version"]), 188 | affected_tables="all", 189 | affected_columns="all", 190 | remarks=paste0("Created database version ", db_ver_cur, " using R package lumpR.")) 191 | write_datetabs(con, meta_out, tab="meta_info", verbose=F) 192 | 193 | # update database if desired 194 | # close connection 195 | tryCatch(odbcClose(con), error=function(e){}) 196 | 197 | if (db_ver > 19) 198 | { 199 | if (!is.null(keep_tables)) #first, update until version encountered before, keeping protected tables 200 | db_update(dbname = dbname, to_ver = db_ver_init, keep_tables = keep_tables) 201 | 202 | db_update(dbname, to_ver = db_ver) 203 | } 204 | 205 | 206 | 207 | 208 | } # EOF 209 | -------------------------------------------------------------------------------- /man/db_check.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/db_check.R 3 | \name{db_check} 4 | \alias{db_check} 5 | \title{Check and modify parameter database for consistency} 6 | \usage{ 7 | db_check( 8 | dbname, 9 | check = c("check_fix_fractions", "filter_small_areas", "tc_slope", "special_areas", 10 | "remove_water_svc", "compute_rocky_frac", "remove_impervious_svc", 11 | "proxy_frgw_delay", "delete_obsolete", "completeness", "subbasin_order"), 12 | option = list(area_thresh = 0.01, treat_slope = c(3, 0.01, 0.1), update_frac_impervious 13 | = F, overwrite = F, tbls_preserve = NULL), 14 | fix = F, 15 | verbose = TRUE 16 | ) 17 | } 18 | \arguments{ 19 | \item{dbname}{Name of the data source (DSN) registered as ODBC-source.} 20 | 21 | \item{check}{Character vector specifying what shall be checked. See \code{Details}.} 22 | 23 | \item{option}{A list of options for certain checks. See \code{Details} 24 | for the different options and their meaning.} 25 | 26 | \item{fix}{\code{logical}. If \code{FALSE} (the \code{default}) a report of the 27 | selected checks will be created. The database will not be modified. If \code{TRUE}, 28 | changes to the database according to the selected checks will be made. 29 | WARNING: \code{fix = TRUE} may irrevocably modify your database. If in doubt, make a backup before.} 30 | 31 | \item{verbose}{\code{logical}. Should detailed information during execution be 32 | printed? When \code{TRUE} (the \code{default}), output of writing updated values 33 | into database can be rather long so you might want to direct output into an 34 | external log file. Always set to \code{TRUE} if \code{fix = FALSE}.} 35 | } 36 | \description{ 37 | Function includes several options to check and correct the parameter database for completeness 38 | and consistency. 39 | } 40 | \details{ 41 | The following checks / modifications are currently included and can be specified via argument \code{checks}. 42 | Execute checks in pre-defined order as some steps build upon each other and 43 | lead to erroneous results when interchanged. However, some steps might be 44 | unnecessary for your purpose and can be left out. 45 | 46 | \bold{check_fix_fractions}\cr 47 | Check/fix that the fractions of all sub-entities sum to 1. 48 | 49 | \bold{filter_small_areas}\cr 50 | Tiny areas as result of landscape disaggregation considered irrelevant during model 51 | application will be removed and the areal fractions updated accordingly. The model 52 | will run faster by removing unnecessary computational burden. Namely, this affects LUs 53 | within subbasins, TCs within LUs and SVCs within TCs. 54 | If the fraction to be removed is greater than 10 \% of the total area of the next higher 55 | spatial level's class, datasets will be kept. In this case you might try a smaller value for area_thresh'.\cr 56 | \emph{Option: 'area_thresh'}\cr 57 | A threshold defining the minimum areal fraction of a certain spatial disaggregation 58 | unit within the next higher spatial level (e.g. LUs within subbasins). Default: 0.01. 59 | 60 | \bold{tc_slope}\cr 61 | In WASA (and other models probably as well) slopes equal to or less than zero are 62 | not allowed. This check helps to identify such TCs and provides the following option 63 | to solve the issue:\cr 64 | \emph{Option: 'treat_slope'}\cr 65 | A numeric vector with two or three elements:\cr 66 | The first being one of \{1,2,3\}:\cr 67 | 1: Remove TCs with slope <= 0 from 'r_lu_contains_tc' whereas areal fraction within 68 | the LU must be smaller than a defined threshold (second value of the vector).\cr 69 | 2: Where slope is 0, change it to small positive value specified as second 70 | value of the vector (interpreted as slope in \%).\cr 71 | 3: A combination of the two former choices whereas option 1 is applied before 72 | option 2, the second value of the vector defining the areal threshold and the 73 | third giving the slope replacement value. This is the default setting with 74 | threshold = 0.01 and slope = 0.1 \%. 75 | 76 | \bold{special_areas}\cr 77 | (This check is unnecessary if you specified \code{watermask}) and \code{imperviousmask} in the workflow before) 78 | Define certain Soil-Vegetation Components as special areas via column 'special_area' 79 | in table 'soil_veg_components' inferred from table 'vegetation' and/or 'soils'. This columns is 80 | necessary for \bold{remove_water_svc} and \bold{compute_rocky_frac} to work. 81 | Currently values '0' for an ordinary SVC, '1' for water areas, and '2' for 82 | impervious surfaces are supported.\cr 83 | \emph{Option: 'special_area'}\cr 84 | A \code{data.frame} with 3 named vectors:\cr 85 | 'reference_tbl': \code{character} giving the name(s) of the database table(s) 86 | containing the special area(s) to be mapped to SVCs. Tables 'vegetation' and 87 | 'soils' are supported.\cr 88 | 'ref_id': \code{integer} giving the 'pid' of the special area within the specified 89 | reference table.\cr 90 | 'special_id': \code{integer} giving the flag of column 'special_area' in table 91 | 'soil_veg_components'. Currently recognised in further processing are '0' for 92 | ordinary SVCs, '1' for water areas, and '2' for impervious surfaces.\cr 93 | For instance, if within table 'vegetation' you have classes with pid 3 and 4 94 | indicating water surfaces and in 'soils' pid 10 is an impervious surface 95 | specify the following: \code{special_area = data.frame(reference_tbl= 96 | c("vegetation", "vegetation", "soils"), ref_id=c(3,4,10), special_id=c(1,1,2))}. 97 | 98 | \bold{remove_water_svc}\cr 99 | Remove SVCs marked as water from table 'r_tc_contains_svc', i.e. those SVCs where 100 | in table 'soil_veg_components' column 'special_area' is equal to 1. Areal fractions 101 | will be updated (normalized to 1). Requires column 'special_area' to be set correctly 102 | (e.g. by running option 'special_area' before) 103 | 104 | \bold{compute_rocky_frac}\cr 105 | Compute rocky fractions, i.e. fractions of impervious surfaces, for TCs (table 106 | 'terrain_components', column 'frac_rocky') from impervious SVCs (column 'special_area' 107 | in 'soil_veg_components' equal to 2) and topmost soil horizons (in table horizons' 108 | column 'position' equal to 1 and 'coarse_frag' equal to 1). These undergo special 109 | treatment in the WASA model. SVCs with soil profile containing 100\% coarse 110 | fragments in topmost horizon will be marked as impervious. 111 | If the column 'frac_rocky' already contains values, the computed values are added to these. 112 | In any case, this step should be followed by 'remove_impervious_svc'. 113 | 114 | \bold{remove_impervious_svc}\cr 115 | Remove SVCs marked as impervious from table 'r_tc_contains_svc', i.e. those SVCs where 116 | in table 'soil_veg_components' column 'special_area' is equal to 2.\cr 117 | \emph{Option: 'update_frac_impervious'}\cr 118 | Value of type \code{logical}:\cr 119 | FALSE (default): Areal fractions will not be updated. I.e., the sum of 'fraction' for a specific 120 | 'tc_id' plus 'frac_rocky' of table 'terrain_components' of that specific TC (calculated by 121 | check 'compute_rocky_frac') sums up to unity. This is a requirement of the WASA-SED model.\cr 122 | TRUE: Areal fractions will be updated such that 'fraction' for a specific 'tc_id' sums to unity. 123 | 124 | \bold{proxy_frgw_delay}\cr 125 | Estimate storage coefficient for groundwater delay ('frgw_delay') in \emph{days} 126 | for each LU based on a proxy and manually specified total mean groundwater delay 127 | in \emph{days}. The proxy is estimated from average slope length, slope and rocky 128 | fraction according to empirical formulas:\cr 129 | \code{proxy = slopelength * (1 - frac_rocky) / slope}. and \cr 130 | \code{frgw_delay = proxy * total_mean_delay / mean(proxy)}. 131 | Existing values of 'frgw_delay' will be overwritten.\cr 132 | \emph{Option: 'total_mean_delay'}\cr 133 | Total mean groundwater delay in \emph{days} estimated a priori for the whole 134 | catchment (e.g. from baseflow analysis). All proxy values are scaled, so their 135 | mean matches this value (see formula above). 136 | 137 | \bold{delete_obsolete}\cr 138 | Check for (and optionally delete) obsolete datasets. I.e. LUs not in any subbasin, TCs 139 | not in any LU, SVCs not in any TC from the \emph{contains}- and the parent tables, 140 | and datasets in 'rainy_season' with obsolete subbasins (if table 'rainy_season' exists). 141 | Dependencies are respected. Areal fractions will be updated in case obsolete datasets are removed.\cr 142 | \emph{Option: 'tbls_preserve'}\cr 143 | Vector of type \code{character} giving the names of tables where obsolete datasets will NOT be removed. 144 | Default: \code{NULL}. 145 | 146 | \bold{completeness}\cr 147 | Check database for completeness. I.e. check if all entities in a higher hierarchy are used and specified in the related tables 148 | of lower hierarchy. Reports only, ignores \code{fix=T} and does no changes to the database. 149 | 150 | \bold{subbasin_order}\cr 151 | Compute subbasin order for WASA's routing input file \code{routing.dat}. Order will 152 | be derived from column 'drains_to' and written to 'a_stream_order' of table 'subbasins'.\cr 153 | \emph{Option: 'overwrite'}: Overwrite existing vaues. 154 | } 155 | \note{ 156 | In case the default value of option \emph{'update_frac_impervious'} shall NOT be used, 157 | you should always explicitly specify it, even when check 'remove_impervious_svc' is not applied, 158 | to make sure, 'fraction' of table 'r_tc_contains_svc' is always correctly calculated. 159 | 160 | Database will only be touched (if \code{fix = TRUE}) after all checks are completed successfully. 161 | If the function stops with an error during checks, the database will be left unchanged. 162 | } 163 | \examples{ 164 | 165 | \dontrun{ 166 | db_check(dbname, 167 | check=c("subbasin_order"), 168 | fix=TRUE, 169 | verbose=T, option=list(overwrite=FALSE)) 170 | } 171 | 172 | } 173 | \references{ 174 | lumpR package introduction with literature study and sensitivity analysis:\cr 175 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 176 | landscape discretisation for hillslope-based hydrological models. 177 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 178 | } 179 | \author{ 180 | Tobias Pilz, Till Francke 181 | } 182 | -------------------------------------------------------------------------------- /inst/database/create_db.sql: -------------------------------------------------------------------------------- 1 | 2 | 3 | CREATE TABLE db_version ( 4 | ID INT(11) AUTO_INCREMENT NOT NULL, 5 | version INT DEFAULT 0 COMMENT 'version number', 6 | description NVARCHAR(250) COMMENT 'verbal description of changes', 7 | new_tables NVARCHAR(250) COMMENT 'tables new in this version', 8 | modified_tables NVARCHAR(250) COMMENT 'tables modified in this version', 9 | remarks NVARCHAR(250) COMMENT 'additional remarks', 10 | date_time DATETIME, 11 | PRIMARY KEY (ID) 12 | ) ENGINE=InnoDB; 13 | 14 | INSERT INTO db_version VALUES ( 15 | 19, 16 | 19, 17 | 'First version within LUMP R-package', 18 | 'none', 19 | 'horizons, landscape_units, particle_classes, soils, soil_veg_components, subbasins, terrain_components, vegetation, db_version', 20 | 'adjusted data type in db_version and column names for the other tables', 21 | '2015-05-11 17:08:00'); 22 | 23 | 24 | CREATE TABLE meta_info ( 25 | pid INT(11) AUTO_INCREMENT NOT NULL COMMENT 'automatic counter, can be used as data-version number', 26 | mod_date DATETIME COMMENT 'date of modification', 27 | mod_user NVARCHAR(50) COMMENT 'modified by', 28 | affected_tables NVARCHAR(255) COMMENT 'modified tables', 29 | affected_columns NVARCHAR(255) COMMENT 'modified columns', 30 | remarks NVARCHAR(255) COMMENT 'remarks', 31 | PRIMARY KEY (pid) 32 | ) ENGINE=InnoDB; 33 | 34 | 35 | CREATE TABLE vegetation ( 36 | pid INT DEFAULT 0 COMMENT 'primary key', 37 | description NVARCHAR(50) COMMENT 'description', 38 | stomat_r DOUBLE DEFAULT 0 COMMENT 'stomata resistance without water stress [sec/m]', 39 | min_suction DOUBLE DEFAULT 0 COMMENT 'suction threshold for water stress effect on resistance (begin of stomata closure) [hPa]', 40 | max_suction DOUBLE DEFAULT 0 COMMENT 'suction threshold for water stress effect on resistance (total closure of stomata - wilting point) [hPa]', 41 | height1 DOUBLE DEFAULT 0 COMMENT 'Average height of vegetation canopy [m] before rainy season', 42 | height2 DOUBLE DEFAULT 0 COMMENT 'Average height of vegetation canopy [m] beginning rainy season', 43 | height3 DOUBLE DEFAULT 0 COMMENT 'Average height of vegetation canopy [m] end rainy season', 44 | height4 DOUBLE DEFAULT 0 COMMENT 'Average height of vegetation canopy [m] after rainy season', 45 | root_depth1 DOUBLE DEFAULT 0 COMMENT 'Rooting depth of vegetation [m] before rainy season', 46 | root_depth2 DOUBLE DEFAULT 0 COMMENT 'Rooting depth of vegetation [m] beginning rainy season', 47 | root_depth3 DOUBLE DEFAULT 0 COMMENT 'Rooting depth of vegetation [m] end rainy season', 48 | root_depth4 DOUBLE DEFAULT 0 COMMENT 'Rooting depth of vegetation [m] after rainy season', 49 | lai1 DOUBLE DEFAULT 0 COMMENT 'Leaf area index of vegetation cover [-] before rainy season', 50 | lai2 DOUBLE DEFAULT 0 COMMENT 'Leaf area index of vegetation cover [-] beginning rainy season', 51 | lai3 DOUBLE DEFAULT 0 COMMENT 'Leaf area index of vegetation cover [-] end rainy season', 52 | lai4 DOUBLE DEFAULT 0 COMMENT 'Leaf area index of vegetation cover [-] after rainy season', 53 | alb1 DOUBLE DEFAULT 0 COMMENT 'Surface albedo [-] before rainy season', 54 | alb2 DOUBLE DEFAULT 0 COMMENT 'Surface albedo [-] beginning rainy season', 55 | alb3 DOUBLE DEFAULT 0 COMMENT 'Surface albedo [-] end rainy season', 56 | alb4 DOUBLE DEFAULT 0 COMMENT 'Surface albedo [-] after rainy season', 57 | c_manning_n DOUBLE COMMENT '(optional for erosion modelling) transferred to soil_veg_components if m_copy_mannings_n is called', 58 | c_musle_c1 DOUBLE COMMENT '(optional for erosion modelling) transferred to soil_veg_components if m_copy_c_factor is called', 59 | c_musle_c2 DOUBLE COMMENT '(optional for erosion modelling) C-factor seasonality (leave empty for invariant value), transferred to soil_veg_components if m_copy_c_factor is called', 60 | c_musle_c3 DOUBLE COMMENT '(optional for erosion modelling) C-factor seasonality (leave empty for invariant value), transferred to soil_veg_components if m_copy_c_factor is called', 61 | c_musle_c4 DOUBLE COMMENT '(optional for erosion modelling) C-factor seasonality (leave empty for invariant value), transferred to soil_veg_components if m_copy_c_factor is called', 62 | UNIQUE (pid) 63 | ) ENGINE=InnoDB; 64 | 65 | 66 | CREATE TABLE horizons ( 67 | pid INT DEFAULT 0, 68 | description NVARCHAR(50), 69 | soil_id INT DEFAULT 0 COMMENT 'foreign_key soils', 70 | position INT DEFAULT 0 COMMENT 'position of horizon from top', 71 | theta_r DOUBLE DEFAULT 0 COMMENT 'residual soil water content [Vol.-]', 72 | theta_pwp DOUBLE DEFAULT 0 COMMENT 'water content at permanent wilting point [Vol.-]', 73 | fk DOUBLE DEFAULT 0 COMMENT 'field capacity FK [Vol.-]', 74 | fk63 DOUBLE DEFAULT 0 COMMENT 'field capacity FK63 [Vol.-]', 75 | nfk DOUBLE DEFAULT 0 COMMENT 'usable field capacity [Vol.-]', 76 | theta_s DOUBLE DEFAULT 0 COMMENT 'saturated water content [Vol.-]', 77 | thickness DOUBLE DEFAULT 0 COMMENT 'thickness of soil horizon [mm]', 78 | ks DOUBLE DEFAULT 0 COMMENT 'saturated hydraulic conductivity [mm/d]', 79 | suction DOUBLE DEFAULT 0 COMMENT 'suction at the wetting front [mm]', 80 | pore_size_i DOUBLE DEFAULT 0 COMMENT 'pore-size-index', 81 | bubb_pres DOUBLE DEFAULT 0 COMMENT 'bubble pressure [cm]', 82 | coarse_frag DOUBLE DEFAULT 0 COMMENT 'fraction of coarse fragments [Vol.-]', 83 | shrinks BOOL DEFAULT 0 COMMENT 'flag for soil structure, currently not used, set to 0', 84 | UNIQUE (soil_id, position) 85 | ) ENGINE=InnoDB; 86 | 87 | 88 | CREATE TABLE soils ( 89 | pid INT DEFAULT 0, 90 | description NVARCHAR(50), 91 | bedrock_flag BOOL NOT NULL COMMENT 'bedrock below deepest horizon', 92 | alluvial_flag BOOL NOT NULL COMMENT 'this is an alluvial soil', 93 | b_om DOUBLE DEFAULT 0 COMMENT 'topsoil organic matter content [mass fraction]', 94 | a_musle_k DOUBLE DEFAULT 0 COMMENT 'used for automatic calculations, do not insert anything', 95 | a_clay DOUBLE DEFAULT 0 COMMENT 'used for automatic calculations, do not insert anything', 96 | a_silt DOUBLE DEFAULT 0 COMMENT 'used for automatic calculations, do not insert anything', 97 | a_sand DOUBLE DEFAULT 0 COMMENT 'used for automatic calculations, do not insert anything', 98 | a_f_csand DOUBLE DEFAULT 0 COMMENT 'used for automatic calculations, do not insert anything', 99 | a_f_cl_si DOUBLE DEFAULT 0 COMMENT 'used for automatic calculations, do not insert anything', 100 | a_f_orgc DOUBLE DEFAULT 0 COMMENT 'used for automatic calculations, do not insert anything', 101 | a_f_hisand DOUBLE DEFAULT 0 COMMENT 'used for automatic calculations, do not insert anything', 102 | UNIQUE (pid) 103 | ) ENGINE=InnoDB; 104 | 105 | 106 | CREATE TABLE subbasins ( 107 | pid INT NOT NULL DEFAULT 0, 108 | description NVARCHAR(50), 109 | drains_to INT NOT NULL DEFAULT 0 COMMENT 'forein key to subbasin', 110 | area DOUBLE NOT NULL DEFAULT 0 COMMENT 'area [km**2]', 111 | a_stream_order TINYINT DEFAULT 0 COMMENT 'stream order (gerated automatically by make_input)', 112 | lag_time DOUBLE COMMENT 'runoff lag time [d]', 113 | retention DOUBLE COMMENT 'runoff retention time [d]', 114 | UNIQUE (pid) 115 | ) ENGINE=InnoDB; 116 | 117 | 118 | CREATE TABLE landscape_units ( 119 | pid INT DEFAULT 0, 120 | description NVARCHAR(50), 121 | kf_bedrock DOUBLE DEFAULT 0 COMMENT 'Hydraulic conductivity of bedrock [mm/d]', 122 | slopelength DOUBLE DEFAULT 0 COMMENT 'Mean slope length in landscape unit [m]', 123 | soil_depth DOUBLE DEFAULT 0 COMMENT 'Mean maximum depth of soil zone [mm]', 124 | allu_depth DOUBLE DEFAULT 0 COMMENT 'Maximum depth of alluvial soil zone [mm]', 125 | riverbed_depth DOUBLE DEFAULT 0 COMMENT 'Depth of river bed below terrain component [mm]', 126 | gw_flag BOOL NOT NULL COMMENT 'Flag for landscape unit [0: no groundwater, 1: with groundwater]', 127 | gw_dist DOUBLE DEFAULT 0 COMMENT 'Initial depth of groundwater below surface [mm]', 128 | frgw_delay DOUBLE DEFAULT 0 COMMENT 'Storage coefficient for groundwater outflow [day]', 129 | sdr_lu DOUBLE COMMENT '(optional for erosion modelling) sediment delivery ratio on LU-scale', 130 | UNIQUE (pid) 131 | ) ENGINE=InnoDB; 132 | 133 | 134 | CREATE TABLE terrain_components ( 135 | pid INT DEFAULT 0, 136 | description NVARCHAR(50), 137 | slope DOUBLE DEFAULT 0 COMMENT 'Slope of terrain component [%]', 138 | frac_rocky DOUBLE DEFAULT 0 COMMENT 'fraction of impermeable (rock) area in each terrain component [-]', 139 | beta_fac DOUBLE COMMENT '(optional for erosion modelling) ratio of rill/interrill erosion (computation of the L-factor see Renard et al., 1997, pp.101)', 140 | sdr DOUBLE COMMENT '(optional for erosion modelling) sediment delivery ratio on TC-scale', 141 | UNIQUE (pid) 142 | ) ENGINE=InnoDB; 143 | 144 | 145 | CREATE TABLE soil_veg_components ( 146 | pid INT DEFAULT 0, 147 | description NVARCHAR(50), 148 | soil_id INT NOT NULL DEFAULT 0 COMMENT 'foreign key soils', 149 | veg_id INT NOT NULL DEFAULT 0 COMMENT 'foreign key vegetation', 150 | musle_k DOUBLE DEFAULT 0 COMMENT 'MUSLE K-factor [(ton acre hr)/(acre ft-ton inch)]', 151 | musle_p DOUBLE DEFAULT 0 COMMENT 'MUSLE P-factor', 152 | coarse_frac DOUBLE DEFAULT 0 COMMENT 'coarse fraction [%]', 153 | special_area INT DEFAULT 0 COMMENT 'Flag for special areas: 1: water, 2: impervious, 0: ordinary SVC.', 154 | manning_n DOUBLE DEFAULT 0 COMMENT 'Mannings n roughness coefficient for overland flow', 155 | musle_c1 DOUBLE DEFAULT 0 COMMENT '(optional for erosion modelling) C-factor seasonality (leave empty for invariant value), transferred to soil_veg_components if m_copy_c_factor is called', 156 | musle_c2 DOUBLE COMMENT '(optional for erosion modelling) C-factor seasonality (leave empty for invariant value), transferred to soil_veg_components if m_copy_c_factor is called', 157 | musle_c3 DOUBLE COMMENT '(optional for erosion modelling) C-factor seasonality (leave empty for invariant value), transferred to soil_veg_components if m_copy_c_factor is called', 158 | musle_c4 DOUBLE COMMENT '(optional for erosion modelling) C-factor seasonality (leave empty for invariant value), transferred to soil_veg_components if m_copy_c_factor is called', 159 | UNIQUE (pid) 160 | ) ENGINE=InnoDB; 161 | 162 | 163 | CREATE TABLE r_subbas_contains_lu ( 164 | subbas_id INT NOT NULL DEFAULT 0 COMMENT 'foreign key to subbas', 165 | lu_id INT DEFAULT 0 COMMENT 'foreign key to landscape units', 166 | fraction DOUBLE NOT NULL DEFAULT 0 COMMENT 'fraction that this LU covers in the subbasin', 167 | UNIQUE (subbas_id, lu_id) 168 | ) ENGINE=InnoDB; 169 | 170 | 171 | CREATE TABLE r_lu_contains_tc ( 172 | lu_id INT DEFAULT 0 COMMENT 'foreign key to landscape_units', 173 | tc_id INT NOT NULL DEFAULT 0 COMMENT 'foreign key to terrain_components', 174 | fraction DOUBLE DEFAULT 0 COMMENT 'areal fraction of TC in the LU', 175 | position TINYINT DEFAULT 0 COMMENT 'hillslope position of TC in LU (counting from hillslope bottom)', 176 | UNIQUE (lu_id, tc_id) 177 | ) ENGINE=InnoDB; 178 | 179 | 180 | CREATE TABLE r_tc_contains_svc ( 181 | tc_id INT NOT NULL DEFAULT 0 COMMENT 'foreign key terrain_component', 182 | svc_id INT NOT NULL DEFAULT 0 COMMENT 'foreign key soil_veg_comp', 183 | fraction DOUBLE NOT NULL DEFAULT 0 COMMENT 'fraction of SVC in TC', 184 | UNIQUE (tc_id, svc_id) 185 | ) ENGINE=InnoDB; 186 | 187 | 188 | CREATE TABLE particle_classes ( 189 | class_id INT DEFAULT 0 COMMENT 'continuous number of particle size class', 190 | description NVARCHAR(50) COMMENT 'optional name of particle size class (e.g. clay)', 191 | upper_limit DOUBLE DEFAULT 0 COMMENT 'upper_limit of respective particle size class [mm]', 192 | UNIQUE (class_id) 193 | ) ENGINE=InnoDB; 194 | 195 | 196 | CREATE TABLE r_soil_contains_particles ( 197 | soil_id INT DEFAULT 0 COMMENT 'foreign key to soils', 198 | class_id INT DEFAULT 0 COMMENT 'foreign key to particle_classes', 199 | fraction DOUBLE DEFAULT 0 COMMENT 'mass-fraction that falls into the respective particle size class', 200 | UNIQUE (soil_id, class_id) 201 | ) ENGINE=InnoDB; 202 | 203 | -------------------------------------------------------------------------------- /R/disc_wrapper.R: -------------------------------------------------------------------------------- 1 | #' Wrapper function performing a complete landscape discretisation 2 | #' 3 | #' @return The function returns nothing. A number of plots, text files, and GRASS data 4 | #' are produced. 5 | #' 6 | #' @details This function is a wrapper function performing a complete landscape 7 | #' discretisation by calling the functions \code{\link[lumpR]{calc_subbas}}, \code{\link[lumpR]{lump_grass_prep}}, 8 | #' \code{\link[lumpR]{area2catena}}, \code{\link[lumpR]{prof_class}}, \code{\link[lumpR]{lump_grass_post}}, 9 | #' \code{\link[lumpR]{lump_grass_prep}}, \code{\link[lumpR]{db_create}}, \code{\link[lumpR]{db_fill}}, 10 | #' and \code{\link[lumpR]{db_check}}. See function's documentations for information about 11 | #' the arguments. 12 | #' 13 | #' @note This function was created for automated landscape discretisation, e.g. within a 14 | #' Monte Carlo analysis. Use only if you are already familiar with the lumpR package 15 | #' and can be sure that the procedure works for your input data! 16 | #' 17 | #' @references 18 | #' \bold{lumpR paper}\cr 19 | #' Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 20 | #' landscape discretisation for hillslope-based hydrological models. 21 | #' \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 22 | #' 23 | #' @author Tobias Pilz 24 | 25 | disc_wrapper <- function( 26 | # input # 27 | dem = NULL, 28 | drain_points = NULL, 29 | river = NULL, 30 | flowaccum = NULL, 31 | drainage_dir = NULL, 32 | lcov = NULL, 33 | soil = NULL, 34 | watermask = NULL, 35 | imperviousmask = NULL, 36 | supp_quant = NULL, 37 | supp_qual = NULL, 38 | soil_depth = NULL, 39 | sdr = NULL, 40 | veg_path = NULL, 41 | soil_path = NULL, 42 | odbc_file = "~/.odbc.ini", 43 | dbname = NULL, 44 | db_driver = "SQLITE3", 45 | db_desc = "lumpR database automatically generated with lumpR::disc_wrapper()", 46 | db_server = "localhost", 47 | db_checks = NULL, 48 | db_option = NULL, 49 | # output: GRASS # 50 | subbas = NULL, 51 | stream = NULL, 52 | stream_eha = NULL, 53 | stream_horton = NULL, 54 | points_processed = NULL, 55 | eha = NULL, 56 | flowdir = NULL, 57 | flowacc = NULL, 58 | elevriv = NULL, 59 | distriv = NULL, 60 | svc = NULL, 61 | lu = NULL, 62 | # output: files # 63 | output_dir = getwd(), 64 | svc_file = "svc.dat", 65 | catena_out = "catena.dat", 66 | catena_head_out = "catena_header.dat", 67 | luoutfile = "lu_pars.dat", 68 | tcoutfile = "tc_pars.dat", 69 | lucontainstcoutfile = "lu_tc.dat", 70 | tccontainssvcoutfile = "tc_svc.dat", 71 | terraincomponentsoutfile = "tc_db.dat", 72 | sub_ofile = "sub.dat", 73 | sub_lu = "sub_lu.dat", 74 | lupar_ofile = "lu_db.dat", 75 | recl_lu = "reclass_lu.dat", 76 | # parameters: discretisation # 77 | thresh_sub = NULL, 78 | eha_thres = NULL, 79 | no_LUs = NULL, 80 | no_TCs = NULL, 81 | # parameters: runtime and others # 82 | disk_swap = FALSE, 83 | drainp_out_id = NULL, 84 | thresh_stream = NULL, 85 | snap_dist = NULL, 86 | rm_spurious = NULL, 87 | prep_things2do = c("eha", "river", "svc"), 88 | groundwater = TRUE, 89 | ridge_thresh = NULL, 90 | min_cell_in_slope = NULL, 91 | min_catena_length = NULL, 92 | max_riv_dist = NULL, 93 | grass_files = FALSE, 94 | plot_catena = TRUE, 95 | plot_profclass = TRUE, 96 | plot_silhouette = TRUE, 97 | keep_temp = FALSE, 98 | overwrite = FALSE, 99 | db_overwrite = NULL, 100 | silent = FALSE, 101 | ncores = 1, 102 | addon_path = NULL 103 | ) { 104 | 105 | 106 | # SUBBASIN DELINEATION # 107 | calc_subbas( 108 | # INPUT # 109 | dem=dem, 110 | drain_points=drain_points, 111 | river=river, 112 | flowaccum = flowaccum, 113 | drainage_dir = drainage_dir, 114 | # OUTPUT # 115 | basin_out=subbas, 116 | stream=stream, 117 | points_processed=points_processed, 118 | # PARAMETERS # 119 | disk_swap = disk_swap, 120 | outlet=ifelse(is.null(drainp_out_id), 1, ifelse(is.character(drainp_out_id), which(drain_points$id == drainp_out_id), drainp_out_id)), 121 | thresh_stream=thresh_stream, 122 | thresh_sub=thresh_sub, 123 | snap_dist=snap_dist, 124 | rm_spurious=rm_spurious, 125 | keep_temp=keep_temp, 126 | overwrite=overwrite, 127 | silent=silent 128 | ) 129 | 130 | 131 | 132 | # PREPROCESSING AND HILLSLOPE DEVIATION # 133 | lump_grass_prep( 134 | # INPUT # 135 | mask = subbas, 136 | dem = dem, 137 | lcov = lcov, 138 | soil = soil, 139 | watermask = watermask, 140 | imperviousmask = imperviousmask, 141 | # OUTPUT # 142 | eha=eha, 143 | flowdir = flowdir, 144 | flowacc = flowacc, 145 | stream = stream_eha, 146 | stream_horton = stream_horton, 147 | elevriv = elevriv, 148 | distriv = distriv, 149 | svc = svc, 150 | dir_out = output_dir, 151 | svc_ofile = svc_file, 152 | # PARAMETERS # 153 | eha_thres = eha_thres, 154 | sizefilter = NULL, # use default 155 | growrad = NULL, # use default 156 | keep_temp=keep_temp, 157 | overwrite=overwrite, 158 | silent=silent, 159 | things2do = prep_things2do, 160 | addon_path = addon_path 161 | ) 162 | 163 | 164 | 165 | # CALCULATE MEAN CATENA FOR HILLSLOPES # 166 | area2catena( 167 | # INPUT # 168 | mask=subbas, 169 | flowacc=flowacc, 170 | eha=eha, 171 | distriv=distriv, 172 | elevriv=elevriv, 173 | supp_quant=supp_quant, 174 | supp_qual=supp_qual, 175 | # OUTPUT # 176 | dir_out=output_dir, 177 | catena_out=catena_out, 178 | catena_head_out=catena_head_out, 179 | # PARAMETERS # 180 | ridge_thresh=ridge_thresh, 181 | min_cell_in_slope=min_cell_in_slope, 182 | min_catena_length=min_catena_length, 183 | max_riv_dist=max_riv_dist, 184 | plot_catena=plot_catena, 185 | grass_files=grass_files, 186 | ncores=ncores, 187 | eha_subset=NULL, 188 | overwrite=overwrite, 189 | silent=silent 190 | ) 191 | 192 | # change header file according to rstats_header 193 | header_dat <- readLines(paste(output_dir, catena_head_out, sep="/")) 194 | no_LUs[1] <- no_LUs[1] * -1 195 | header_dat[8] <- paste(no_LUs, "\t", sep="", collapse="") 196 | header_dat[9] <- paste(c(no_TCs, rep(0, length(no_LUs)-1)), "\t", sep="", collapse="") 197 | writeLines(header_dat,paste(output_dir, catena_head_out, sep="/")) 198 | 199 | 200 | 201 | # CATENA CLASSIFICATION INTO LANDSCAPE UNITS AND TERRAIN COMPONENTS # 202 | # get resolution (mean between x and y resolution) 203 | res <- mean(gmeta()$nsres, gmeta()$ewres) 204 | 205 | prof_class( 206 | # INPUT # 207 | catena_file=paste(output_dir, catena_out, sep="/"), 208 | catena_head_file=paste(output_dir, catena_head_out, sep="/"), 209 | svc_column="svc", 210 | # OUTPUT # 211 | dir_out=output_dir, 212 | luoutfile=luoutfile, 213 | tcoutfile=tcoutfile, 214 | lucontainstcoutfile=lucontainstcoutfile, 215 | tccontainssvcoutfile=tccontainssvcoutfile, 216 | terraincomponentsoutfile=terraincomponentsoutfile, 217 | recl_lu=recl_lu, 218 | saved_clusters=NULL, 219 | # PARAMETERS # 220 | seed=1312, 221 | resolution=res, 222 | classify_type=' ', 223 | max_com_length=50, 224 | com_length=NULL, 225 | make_plots=plot_profclass, 226 | plot_silhouette = plot_silhouette, 227 | eha_subset=NULL, 228 | eha_blacklist = NULL, 229 | overwrite=overwrite, 230 | silent=silent 231 | ) 232 | 233 | 234 | 235 | # POST PROCESSING # 236 | lump_grass_post( 237 | # INPUT # 238 | mask = subbas, 239 | dem = dem, 240 | recl_lu = paste(output_dir, recl_lu, sep="/"), 241 | lu = lu, 242 | subbasin = subbas, 243 | eha = eha, 244 | flowacc = flowacc, 245 | flowdir = flowdir, 246 | stream_horton = stream_horton, 247 | soil_depth = soil_depth, 248 | sdr = sdr, 249 | # OUTPUT # 250 | dir_out = output_dir, 251 | sub_ofile = sub_ofile, 252 | lu_ofile = sub_lu, 253 | lupar_ofile = lupar_ofile, 254 | # PARAMETER # 255 | fill_holes=T, 256 | groundwater=groundwater, 257 | keep_temp = keep_temp, 258 | overwrite = overwrite, 259 | silent = silent 260 | ) 261 | 262 | 263 | 264 | # create information file for filling landscape_units into database (SIMPLEST POSSIBLE PARAMETER VALUES USED HEREIN) 265 | luout <- read.table(paste(output_dir, luoutfile, sep="/"), header=T) 266 | lupar <- read.table(paste(output_dir, lupar_ofile, sep="/"), header=T) 267 | lupar$slopelength <- luout$x_length 268 | lupar$soil_depth <- 1000 # groundwater option II.2.1 (WASA documentation) 269 | lupar$allu_depth <- 3000 # groundwater option II.2.1 (WASA documentation) 270 | lupar$riverbed_depth <- 1500 # riverbed in any case below soil (no information whether this is reasonable or not) 271 | lupar$kf_bedrock <- 10 272 | lupar$frgw_delay <- 20 273 | write.table(lupar, paste(output_dir, "lu_db_edit.dat", sep="/"), quote = F, row.names = F, sep="\t") 274 | 275 | # copy soil and vegetation parameter files into output_dir 276 | file.copy(paste(veg_path, "vegetation.dat", sep="/"), paste(output_dir, "vegetation.dat", sep="/"), overwrite=T) 277 | file.copy(paste(veg_path, "rainy_season.dat", sep="/"), paste(output_dir, "rainy_season.dat", sep="/"), overwrite=T) 278 | file.copy(paste(soil_path, "soil.dat", sep="/"), paste(output_dir, "soil.dat", sep="/"), overwrite=T) 279 | file.copy(paste(soil_path, "horizons.dat", sep="/"), paste(output_dir, "horizons.dat", sep="/"), overwrite=T) 280 | file.copy(paste(soil_path, "particle_classes.dat", sep="/"), paste(output_dir, "particle_classes.dat", sep="/"), overwrite=T) 281 | file.copy(paste(soil_path, "r_soil_contains_particles.dat", sep="/"), paste(output_dir, "r_soil_contains_particles.dat", sep="/"), overwrite=T) 282 | 283 | 284 | 285 | # DATABASE # 286 | 287 | # LINUX ONLY: 288 | # register database (write into .odbc.ini in your $HOME) 289 | if(grepl("linux", Sys.info()["sysname"], ignore.case = T)) { 290 | odbc_dat <- readLines(odbc_file) 291 | if(any(grepl(paste0("[", dbname, "]"), odbc_dat, fixed = T))) { 292 | 293 | if(!overwrite) stop(paste0("Database entry already exists in ", odbc_file, "!")) 294 | 295 | # remove entry 296 | entry <- grep(paste0("[", dbname, "]"), odbc_dat, fixed = T) 297 | entry_end <- NULL 298 | for (e in entry) { 299 | entry_t <- which(odbc_dat[e:length(odbc_dat)] == "")[1] 300 | entry_end <- c(entry_end, e+entry_t-1) 301 | } 302 | r_del <- do.call(c, mapply(seq, entry, entry_end, SIMPLIFY = FALSE)) 303 | odbc_dat <- odbc_dat[-r_del] 304 | write(odbc_dat, file=odbc_file, ncolumns=1, sep="\n") 305 | } 306 | str_odbc <- c(paste0("[", dbname, "]"), # adjust as you like 307 | paste0("Description = ", db_desc), 308 | paste0("Driver = ", db_driver), # INSTALL AND FILL IN HERE YOUR ODBC DRIVER! 309 | paste0("ServerName = ", db_server), # as needed 310 | paste0("Database = ",output_dir, "/dbase.db"), # adjust as you like 311 | "") 312 | write(str_odbc, file=odbc_file, ncolumns=1, append=T, sep="\n") 313 | } 314 | 315 | # create database 316 | db_create(dbname, overwrite = db_overwrite) 317 | 318 | # fill database 319 | db_fill(dbname=dbname, 320 | tables = c("r_subbas_contains_lu", "subbasins", 321 | "landscape_units", "r_lu_contains_tc", "terrain_components", "r_tc_contains_svc", 322 | "vegetation", "soils", "horizons", "soil_veg_components", 323 | "particle_classes", "r_soil_contains_particles", 324 | "rainy_season"), 325 | dat_files=c(sub_lu, sub_ofile, 326 | "lu_db_edit.dat", lucontainstcoutfile, terraincomponentsoutfile, tccontainssvcoutfile, 327 | "vegetation.dat", "soil.dat","horizons.dat", svc_file, 328 | "particle_classes.dat", "r_soil_contains_particles.dat", 329 | "rainy_season.dat"), 330 | dat_dir=output_dir, 331 | overwrite=overwrite, verbose= !silent) 332 | 333 | # checks 334 | db_check(dbname, check=db_checks, option=db_option, fix=T, verbose= !silent) 335 | 336 | 337 | } # EOF -------------------------------------------------------------------------------- /man/lump_grass_post.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/lump_grass_post.R 3 | \name{lump_grass_post} 4 | \alias{lump_grass_post} 5 | \title{Post-processing of Landscape Unit deviation using GRASS GIS} 6 | \usage{ 7 | lump_grass_post( 8 | mask = NULL, 9 | dem = NULL, 10 | recl_lu = NULL, 11 | lu = NULL, 12 | subbasin = NULL, 13 | eha = NULL, 14 | flowacc = NULL, 15 | flowdir = NULL, 16 | stream_horton = NULL, 17 | soil_depth = NULL, 18 | sdr = NULL, 19 | dir_out = "./", 20 | sub_ofile = NULL, 21 | lu_ofile = NULL, 22 | lupar_ofile = NULL, 23 | fill_holes = T, 24 | groundwater = 0, 25 | na_val = NA, 26 | keep_temp = F, 27 | overwrite = F, 28 | silent = F 29 | ) 30 | } 31 | \arguments{ 32 | \item{mask}{Name of mask raster map masking the study area. E.g. output \code{basin_out} 33 | of \code{\link[lumpR]{calc_subbas}}.} 34 | 35 | \item{dem}{DEM raster map in GRASS location as used in \code{\link[lumpR]{lump_grass_prep}}.} 36 | 37 | \item{recl_lu}{Name of GRASS reclassification file: EHA -> LU. Output of 38 | \code{\link[lumpR]{prof_class}}. If omitted, the existing raster layer \code{lu} is used.} 39 | 40 | \item{lu}{Input or Output: Name of Landscape Units (LU) raster map already existing in 41 | GRASS location or to be generated using \code{recl_lu}.} 42 | 43 | \item{subbasin}{Subbasin raster map in GRASS location as used in \code{\link[lumpR]{lump_grass_prep}} 44 | and/or created by \code{\link[lumpR]{calc_subbas}}.} 45 | 46 | \item{eha}{Name of Elementary Hillslope Areas (EHA) raster map in GRASS 47 | location. Output of \code{\link[lumpR]{lump_grass_prep}}.} 48 | 49 | \item{flowacc}{Name of flow accumulation raster map in GRASS location. Can 50 | be created with \code{\link[lumpR]{lump_grass_prep}}.} 51 | 52 | \item{flowdir}{Name of flow direction raster map in GRASS location. Can 53 | be created with \code{\link[lumpR]{lump_grass_prep}}.} 54 | 55 | \item{stream_horton}{Name of Horton stream order raster map in GRASS location. Can 56 | be created with \code{\link[lumpR]{lump_grass_prep}}. If left empty, the channel length, 57 | slope and retention times are set to \code{NA}.} 58 | 59 | \item{soil_depth}{Name of soil depth [mm] raster map in GRASS location. If \code{NULL} 60 | (default), \code{na_val} is used.} 61 | 62 | \item{sdr}{Name of sediment delivery ratio [-] raster map in GRASS location. If empty, 63 | this optional column is omitted.} 64 | 65 | \item{dir_out}{Character string specifying output directory (will be created; 66 | any overwriting will be prompted).} 67 | 68 | \item{sub_ofile}{Output: Name of subbasin statistics file containing subbasin 69 | parameters. See \code{Details} below. If \code{NULL} (default) this file 70 | will not be generated.} 71 | 72 | \item{lu_ofile}{Output: Name of file containing subbasins and the corresponding 73 | LUs with their fraction of area in the subbasin. If \code{NULL} (default) 74 | this file will not be generated.} 75 | 76 | \item{lupar_ofile}{Output: Name of file containing LUs and related parameters. 77 | See \code{Details} below. If \code{NULL} (default) this file will not be generated.} 78 | 79 | \item{fill_holes}{TRUE: fill any holes in map \code{eha} (e.g. as result of skipped/non-classified 80 | EHAs) by growing} 81 | 82 | \item{groundwater}{Flag: 1: respect groundwater and infer parameters. 0 (default): 83 | Ignore groundwater and associated parameters.} 84 | 85 | \item{na_val}{Value used to indicate \code{NA} values in output files. Default: \code{NA}.} 86 | 87 | \item{keep_temp}{\code{logical}. Set to \code{TRUE} if temporary files shall be kept 88 | in the GRASS location, e.g. for debugging or further analyses. Default: \code{FALSE}.} 89 | 90 | \item{overwrite}{\code{logical}. Shall output of previous calls of this function be 91 | deleted? If \code{FALSE} the function returns an error if output already exists. 92 | Default: \code{FALSE}.} 93 | 94 | \item{silent}{\code{logical}. Shall the function be silent (also suppressing warnings 95 | of internally used GRASS functions)? Default: \code{FALSE}.} 96 | } 97 | \value{ 98 | Function returns nothing. Output files (\code{sub_ofile, lupar_ofile, lu_ofile}) 99 | are written into output directory and raster map (\code{lu}) exported into GRASS 100 | location as specified in arguments. 101 | } 102 | \description{ 103 | Creates raster map of Landscape Units and files containing information of 104 | and parameter estimation for Subbasins and Landscape Units in the catchment 105 | using outputs of \code{\link[lumpR]{lump_grass_prep}} and \code{\link[lumpR]{prof_class}}. 106 | } 107 | \details{ 108 | \bold{Subbasin parameters}\cr 109 | Subbasin parameter estimation given in \code{sub_ofile} contains: 110 | 111 | \emph{pid}\cr 112 | Subbasin identifier. 113 | 114 | \emph{description}\cr 115 | Subbasin description you can fill in manually if needed. 116 | 117 | \emph{lat}\cr 118 | Latitude of subbasin centroid in \emph{decimal degrees} (negative values for southern hemisphere). 119 | 120 | \emph{lon}\cr 121 | Longitude of subbasin centroid in \emph{decimal degrees west of Greenwhich}, e.g. 122 | Greenwich: 0°, New York: 75°, Berlin: 345°. 123 | 124 | \emph{elev}\cr 125 | Average elevation above sea level of subbasin \emph{m}. 126 | 127 | \emph{area}\cr 128 | Subbasin area in \emph{km^2}. 129 | 130 | \emph{x}\cr 131 | X-coordinate of subbasin centroid in units of GRASS location. 132 | 133 | \emph{y}\cr 134 | Y-coordinate of subbasin centroid in units of GRASS location. 135 | 136 | \emph{drains_to}\cr 137 | Pid of subbasin the current subbasin drains to. It is determined by identifying 138 | the cell with the highest flow accumulation value (= subbasin outlet). By 139 | deriving the drainage direction value of that raster cell the next downstream 140 | cell is identified along with corresponding subbasin number. 141 | 142 | \emph{lag_time}\cr 143 | Time in \emph{days} a runoff signal in the current subbasin needs to be directed 144 | from the subbasin input to the outlet. Estimated from channel geometry (see below). 145 | 146 | \emph{retention}\cr 147 | Maximum time period in \emph{days} over which a runoff signal is distributed by 148 | the routing process. Estimated from channel geometry (see below). 149 | 150 | \emph{chan_len}\cr 151 | Length of the main channel of the respective subbasin in \emph{m}. Estimated 152 | from channel geometry (see below). 153 | 154 | \emph{channel geometry}\cr 155 | Main channel length: For each subbasin the main channel is determined from Horton 156 | stream raster map. Its length is then calculated depending on raster resolution 157 | and flow direction.\cr 158 | Channel slope: Minimum (= inflow) and maximum (= outflow) flow accumulation and 159 | elevation of the corresponding raster cells are determined. The difference in 160 | elevation is divided by main channel length.\cr 161 | Channel width: Maximum flow accumulation is determined and the corresponding 162 | drainage area calculated by resolution of raster cells. Channel width is then 163 | calculated from the empirical formula: width[m] = 1.29 * darea[km2] ^ 0.6.\cr 164 | Channel depth: Empirical formula based on drainage area: depth[m] = 0.13 * darea[km2] ^ 0.4.\cr 165 | Flow velocity: Is calculated using Mannings equation with an n-value of 0.075. 166 | Flow velocities are calculated to derive flow travel times (velocity / channel 167 | length) for bankfull (= high flow condition), 2/3 (= average conditions) and 168 | 1/10 (= low flow conditions) water levels to derive lag time (travel time for 169 | average conditions) and retention time (max - min travel time). 170 | 171 | 172 | \bold{Landscape Units in Subbasins}\cr 173 | \code{lu_ofile} contains: 174 | 175 | \emph{subbas_id}\cr 176 | Subbasin identifier. 177 | 178 | \emph{lu_id}\cr 179 | Landscape Unit identifier. 180 | 181 | \emph{fraction}\cr 182 | Areal fraction of Landscape Unit within corresponding Subbasin. 183 | 184 | 185 | \bold{Landscape Unit parameters}\cr 186 | Landscape Unit parameter estimation given in \code{lupar_ofile} contains: 187 | 188 | \emph{pid}\cr 189 | Landscape Unit identifier. 190 | 191 | \emph{description}\cr 192 | Description for this Landscape Unit. Can be adjusted manually if you want. 193 | Generally set to \code{na_val}. 194 | 195 | \emph{kf_bedrock}\cr 196 | Hydraulic conductivity of bedrock. Fill in values manually. Generally set 197 | to \code{na_val}. Use in WASA model is optional (see WASA documentation 198 | -> 'kfsu' and notes on 'bedrock'). 199 | 200 | \emph{slopelength}\cr 201 | Slope length of Landscape Unit [m]. Value can be obtained from output of 202 | \code{\link[lumpR]{prof_class}}. Herein set to \code{na_val}. 203 | 204 | \emph{soil_depth}\cr 205 | Soil depth in \emph{mm} averaged over respective landscape unit. Use in 206 | WASA model is optional (see WASA documentation -> 'meandep' and notes on 207 | 'bedrock'). Herein set to \code{na_val}. 208 | 209 | \emph{allu_depth}\cr 210 | Depth of alluvial soils in \emph{mm}. Use in WASA model is optional (see 211 | WASA documentation -> 'maxdep' and notes on 'bedrock'). Herein set to \code{na_val}. 212 | 213 | \emph{riverbed_depth}\cr 214 | Depth of river bed below Terrain Component in \emph{mm}. Use in WASA model 215 | is optional (see WASA documentation -> 'riverbed' and notes on 'bedrock'). 216 | Herein set to \code{na_val}. 217 | 218 | \emph{gw_flag}\cr 219 | Groundwater flag: 0: no groundwater in this LU. 1: LU contains groundwater. 220 | At the moment set to 0 by default for every LU. Use in WASA model is optional 221 | (see WASA documentation -> 'gw_flag' and notes on groundwater). 222 | 223 | \emph{gw_dist}\cr 224 | Initial depth of groundwater below surface in \emph{mm}. At the moment set to 225 | 1000 by default for every LU if \code{groundwater = 1}. Use in WASA model is optional 226 | (see WASA documentation -> 'gw_dist' and notes on groundwater). 227 | 228 | \emph{frgw_delay}\cr 229 | Storage coefficient for groundwater outflow in \emph{days}. At the moment set to 230 | 200 by default for every LU if \code{groundwater = 1}. Use in WASA model is optional 231 | (see WASA documentation -> 'frgw_delay' and notes on groundwater). 232 | 233 | \emph{sdr_lu} (optional)\cr 234 | sediment delivery ratio from raster map \code{sdr}, if specified 235 | } 236 | \note{ 237 | Prepare GRASS location and necessary raster files in advance (e.g. using 238 | \code{\link[lumpR]{lump_grass_prep}}) and start GRASS session in R using 239 | \code{\link[rgrass]{initGRASS}}. 240 | 241 | \bold{IMPORTANT:} Herein, when specifying the GRASS input maps, please do 242 | explicitly refer to the mapset if it is different from the mapset given in 243 | initGRASS() (even PERMANENT!), as otherwise internally used read_RAST() command 244 | resulted in errors under Windows. 245 | 246 | TODO:\cr 247 | - check empirical formulas for channel width and channel depth\cr 248 | - LU parameter estimation\cr 249 | - include options to add parameters manually in case data are available\cr 250 | - include option to make function more efficient regarding RAM usage (e.g. by 251 | wrting/reading temporary raster data to/from disk) at the cost of higher computational burden 252 | } 253 | \references{ 254 | Source code based on \code{SHELL} and \code{MATLAB} scripts of Till Francke. 255 | 256 | lumpR package introduction with literature study and sensitivity analysis:\cr 257 | Pilz, T.; Francke, T.; Bronstert, A. (2017): lumpR 2.0.0: an R package facilitating 258 | landscape discretisation for hillslope-based hydrological models. 259 | \emph{Geosci. Model Dev.}, 10, 3001-3023, doi: 10.5194/gmd-10-3001-2017 260 | 261 | Theory of LUMP:\cr 262 | Francke, T.; Guentner, A.; Mamede, G.; Mueller, E. N. and Bronstert, A (2008): 263 | Automated catena-based discretization of landscapes for the derivation of 264 | hydrological modelling units. \emph{International Journal of Geographical 265 | Information Science, Informa UK Limited}, 22(2), 111-132, DOI: 10.1080/13658810701300873 266 | 267 | Subbasin Parameters:\cr 268 | Bronstert, A., Guentner, A., Jaeger, A., Krol, M. & Krywkow, J. (1999): Grossraeumige 269 | hydrologische Parametrisierung und Modellierung als Teil der integrierten 270 | Modellierung. In: Fohrer, N. & Doell, P. (Eds.): Modellierung des Wasser- und 271 | Stofftransports in grossen Einzugsgebieten. \emph{Kassel University Press}, Kassel, 272 | Germany, 31-40. 273 | 274 | Guentner, A. (2002): Large-scale hydrological modelling in the semi-arid 275 | North-East of Brazil. \emph{PIK Report 77}, Potsdam Institute for Climate 276 | Impact Research, Potsdam, Germany. 277 | } 278 | \author{ 279 | Tobias Pilz 280 | } 281 | -------------------------------------------------------------------------------- /R/reservoir_outlet.R: -------------------------------------------------------------------------------- 1 | # lumpR/reservoir_outlet.R 2 | # Copyright (C) 2014,2015,2017,2018,2025 Tobias Pilz 3 | # 4 | # This program is free software: you can redistribute it and/or modify 5 | # it under the terms of the GNU General Public License as published by 6 | # the Free Software Foundation, either version 3 of the License, or 7 | # (at your option) any later version. 8 | # 9 | # This program is distributed in the hope that it will be useful, 10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 | # GNU General Public License for more details. 13 | # 14 | # You should have received a copy of the GNU General Public License 15 | # along with this program. If not, see . 16 | 17 | 18 | #' Determine outlet coordinates of reservoirs 19 | #' 20 | #' Takes a flow accumulation raster (or DEM for computation) and reservoir vector 21 | #' file from a GRASS location and estimates the outlet coordinates of each reservoir 22 | #' polygon. Can be run before \code{\link[lumpR]{reservoir_strategic}} to produce the required input. May also be used to provide outlet points for subbasin delineation. 23 | #' 24 | #' @param flowacc Flow accumulation raster in GRASS location used for determination 25 | #' of reservoir outlets (= highest accumulation value). Set to \code{NULL} if 26 | #' it should be calculated based on a DEM. Default: \code{NULL}. 27 | #' 28 | #' @param dem Digital elevation model in GRASS location used for calculation of 29 | #' flow accumulation if no flow accumulation raster is given. Default: \code{NULL}. 30 | #' 31 | #' @param res_vct Reservoir vector file (polygon) in GRASS location. For each polygon coordinates 32 | #' of the outlet (cell with highest flow accumulation) are determined. Needs 33 | #' at least the column \code{res_id} (integer) as reservoir identifier. 34 | #' If there are no columns \code{elevation} (double) and \code{area} (double) [hectars], they will be added. 35 | #' 36 | #' @param outlets_vect Output: Name of vector file of outlet locations to be exported 37 | #' to GRASS location. Same fields as \code{res_vct}, fields 38 | #' \code{res_id}, \code{elevation} and \code{area} may have been added. 39 | #' 40 | #' @param keep_temp \code{logical}. Set to \code{TRUE} if temporary files shall be kept 41 | #' in the GRASS location, e.g. for debugging or further analyses. Default: \code{FALSE}. 42 | #' @param overwrite \code{logical}. Shall output of previous calls of this function be 43 | #' deleted? If \code{FALSE} the function returns an error if output already exists. 44 | #' Default: \code{FALSE}. 45 | #' @param silent \code{logical}. Shall the function be silent (also suppressing warnings 46 | #' of internally used GRASS functions)? Default: \code{FALSE}. 47 | #' 48 | #' @return Function returns nothing, but produces \code{outlets_vect}. \bold{WARNING:} Up to version 2.5.0 this function 49 | #' returned a \code{SpatialPoints} object with the outlet coordinates. 50 | #' 51 | #' @note Prepare GRASS location and necessary files in advance and start GRASS 52 | #' session in R using \code{\link[rgrass]{initGRASS}}. Location should not 53 | #' contain any maps ending on *_t as these will be removed by calling the 54 | #' function to remove temporary maps. 55 | #' 56 | #' Internal operations require a non-dbf datatabes driver (SQLite, PostgreSQL, MySQL, ODBC, ...). 57 | #' Automatic switiching to sqlite will be attempted. 58 | #' 59 | #' \code{res_vct} must not contain a column \code{cat_new} as this will be the new identifier 60 | #' column for \code{outlets_vect}. 61 | #' 62 | #' Check the results by investigating vector file with outlet points written 63 | #' to GRASS location. Due to small projection inaccuracies between the DEM / flow 64 | #' accumulation raster and the reservoir vector file, calculated outlet locations 65 | #' might more or less deviate from true locations! 66 | #' 67 | #' Can be run before \code{\link[lumpR]{reservoir_strategic}}. 68 | 69 | #' @author Tobias Pilz 70 | 71 | reservoir_outlet <- function( 72 | ### INPUT ### 73 | flowacc = NULL, 74 | dem = NULL, 75 | res_vct = NULL, 76 | 77 | ### OUTPUT ### 78 | outlets_vect = NULL, 79 | 80 | ### PARAMETERS ### 81 | keep_temp = FALSE, 82 | overwrite = FALSE, 83 | silent=F 84 | ) { 85 | 86 | 87 | if(!silent) message("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%") 88 | if(!silent) message("% START reservoir_outlet()") 89 | if(!silent) message("%") 90 | if(!silent) message("% Initialise function...") 91 | 92 | 93 | tryCatch(gmeta(), error = function(e) stop("Cannot execute GRASS commands. Maybe you forgot to run initGRASS()?")) 94 | 95 | # CLEAN UP AND RUNTIME OPTIONS # 96 | cmd_out <- execGRASS("g.version", intern=TRUE) 97 | if (cmd_out=="") 98 | stop("Couldn't connect to GRASS-session. Try removing any open sinks by calling 'sink()' repeatedly. Or restart R.") 99 | 100 | # check arguments and input 101 | if(is.null(flowacc) & is.null(dem)) 102 | stop("Either argument 'dem' or 'flowacc' has to be specified!") 103 | if(!is.null(dem)) check_raster(dem,"dem") 104 | if(!is.null(flowacc)) check_raster(flowacc,"flowacc") 105 | check_vector(res_vct, "res_vct") 106 | if(is.null(outlets_vect)) 107 | stop("Argument 'outlets_vect' needs to be specified!") 108 | 109 | #check for necessary columns in vector file 110 | cmd_out <- execGRASS("v.info", map=res_vct, flags=c("c", "e"), intern=T) 111 | if (!any(grepl(cmd_out, pattern="INTEGER\\|res_id"))) 112 | stop(paste0("Reservoir vector file '",res_vct,"' has no column 'res_id' (INTEGER), please add it.")) 113 | # if (!any(grepl(cmd_out, pattern="CHARACTER\\|name"))) 114 | # stop(paste0("Reservoir vector file '",res_vct,"' has no column 'name' (CHARACTER), please add it.")) 115 | 116 | if (!any(grepl(cmd_out, pattern="\\|area"))) #add area field in hectars, if not present 117 | { 118 | x <- execGRASS("v.to.db", map=res_vct, option="area", columns="area", units="hectares", flags="overwrite", intern=TRUE) 119 | } 120 | 121 | 122 | # suppress annoying GRASS outputs 123 | tmp_file <- file(tempfile(), open="wt") 124 | sink(tmp_file, type="output") 125 | 126 | 127 | # also supress warnings in silent mode 128 | if(silent){ 129 | tmp_file2 <- file(tempfile(), open="wt") 130 | sink(tmp_file2, type="message") 131 | oldw <- getOption("warn") 132 | options(warn = -1) 133 | } 134 | 135 | 136 | tryCatch({ 137 | 138 | # remove mask if any 139 | tryCatch(suppressWarnings(execGRASS("r.mask", flags=c("r"))), error=function(e){}) 140 | 141 | # remove output of previous function calls if overwrite=T 142 | if (overwrite) { 143 | cmd_out <- execGRASS("g.remove", type="raster,vector", pattern=paste("*_t", outlets_vect, sep=","), flags=c("f", "b"), intern=T) 144 | } else { 145 | # remove temporary maps in any case 146 | cmd_out <- execGRASS("g.remove", type="raster,vector", pattern="*_t", flags=c("f", "b"), intern=T) 147 | } 148 | 149 | 150 | if(!silent) message("% OK") 151 | if(!silent) message("%") 152 | if(!silent) message("% Determine highest flow accumulation value for each reservoir...") 153 | 154 | # GRASS calculation of flow accumulation 155 | if (is.null(flowacc)) { 156 | flowacc <- "accum_t" 157 | x <- execGRASS("r.watershed", elevation=dem, accumulation=flowacc, flags="s", intern=T) 158 | } 159 | 160 | # check if flowacc is integer 161 | cmd_out <- execGRASS("r.info", map=flowacc, flags="g", intern=T) 162 | type_line=which(grepl(cmd_out, pattern = "datatype=")) #search for line holding data type 163 | data_type=strsplit(cmd_out[type_line], split = "=")[[1]][2] 164 | if (data_type=="CELL") #if flowaccum is already integer, use it. Otherwise, create interger variant 165 | x <- execGRASS("g.copy", raster=paste0(flowacc,",accum_t"), flags=c("overwrite"), intern=T) else 166 | x <- execGRASS("r.mapcalc", expression=paste0("accum_t = round(", flowacc, ")"), flags=c("overwrite"), intern=T) 167 | 168 | #we need a non-dbf driver connection to realize the next steps 169 | org_settings=NULL 170 | x <- execGRASS("db.connect", flags=c("p"), intern=TRUE) #check current db-driver 171 | if (!grepl(x[1], pattern = "SQLite|PostgreSQL|MySQL|ODBC")) #currently running under unsupported driver, try switching 172 | { 173 | #keep original settings and convert into key/value pairs 174 | org_settings=list() 175 | for (s in x) 176 | { 177 | s2=strsplit(s, split = ": ") 178 | if (length(s2[[1]])>1) 179 | org_settings[[s2[[1]][1]]] = s2[[1]][2] 180 | } 181 | org_settings$cmd="db.connect" #for later use in resetting db-connection 182 | org_settings$intern=TRUE 183 | 184 | x <- execGRASS("db.drivers", flags=c("p"), intern=TRUE) #check available drivers 185 | if (!any(grepl(x, pattern = "sqlite", ignore.case = TRUE))) #is sqlite available? 186 | stop(paste0("Current db-driver (", org_settings$driver,") not supported for this operation. Cannot connect to 'sqlite' as alternative. Please fix this manually by using 'db.connect' with a supported driver (SQLite|PostgreSQL|MySQL|ODBC)")) 187 | else 188 | { #connect to sqlite 189 | x <- execGRASS("db.connect", driver="sqlite", database="$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db", intern=TRUE) #set to sqlite 190 | x <- execGRASS("db.connect", flags = "c", intern=TRUE) #test connection 191 | x <- execGRASS("db.connect", flags=c("p"), intern=TRUE) #check current db-driver 192 | if (!any(x== "driver: sqlite")) 193 | stop(paste0("Current db-driver (", org_settings$driver,") not supported for this operation. Cannot connect to 'sqlite' as alternative. Please fix this manually by using 'db.connect' with a supported driver (SQLite|PostgreSQL|MySQL|ODBC)")) 194 | } 195 | } 196 | 197 | x <- execGRASS("g.copy", vector=paste0(res_vct,",resv_t"), flags=c("overwrite"), intern=T) #working copy of reservoir outlines 198 | 199 | #find maximum value of flowaccumulation for each reservoir - this should be the outlet 200 | x <- execGRASS("v.rast.stats", map="resv_t", raster=flowacc, method="max", column_prefix="fa", intern=TRUE) 201 | 202 | #convert map of max_flow_accum values to raster 203 | x <- execGRASS("v.to.rast", input="resv_t", output="max_flowaccum_t", use="attr", attribute_column="fa_maximum", flags="overwrite", intern=TRUE) 204 | 205 | #intersect map of flowaccum and max values of flowaccum to precisely locate cells 206 | x <- execGRASS("r.mapcalc", expression="outlet_cells_t=if(accum_t==max_flowaccum_t,1,null())", flags="overwrite", intern=TRUE) 207 | 208 | #convert outlet points to vector 209 | x <- execGRASS("r.to.vect", input="outlet_cells_t", type="point", output=outlets_vect, flags=c("overwrite", "t"), intern=TRUE) 210 | 211 | #add subbasin-ID to outlet cells 212 | x <- execGRASS("v.db.addtable", map=outlets_vect, key = "cat_new", intern=TRUE) 213 | x <- execGRASS("v.db.addcolumn", map=outlets_vect, columns="res_id int", intern=TRUE) 214 | x <- execGRASS("v.what.vect", map=outlets_vect, column="res_id", query_map="resv_t", query_column="res_id", intern=TRUE) 215 | #x <- execGRASS("v.what.vect", map=outlets_vect, column="name", query_map="resv_t", query_column="name", intern=TRUE) 216 | 217 | # preserve attribute table of res_vct 218 | x <- execGRASS("v.db.dropcolumn", map = "resv_t", columns = "fa_maximum", intern=T) 219 | 220 | #sadly, this command does not work when DBF-driver is used (default in Windows) 221 | x <- execGRASS("v.db.join", map = outlets_vect, column = "res_id", other_table = "resv_t", other_column = "res_id", intern=T) 222 | 223 | #restore original driver settings, if changed earlier 224 | if(!is.null(org_settings)) 225 | x=do.call(what=execGRASS, args = org_settings) 226 | # x <- execGRASS("db.connect", driver="dbf", database="e:\\till\\uni\\r_lib\\package_build\\lumpR\\lumpr_test\\wasa_example\\grassdata\\Esera\\PERMANENT\\dbf\\", intern=TRUE) 227 | 228 | 229 | #add elevation field, if not present 230 | cmd_out <- execGRASS("v.info", map=outlets_vect, flags=c("c", "e"), intern=T) 231 | if (!any(grepl(cmd_out, pattern="\\|elevation"))) 232 | { 233 | x <- execGRASS("v.db.addcolumn", map=outlets_vect, columns="elevation double", intern=TRUE) 234 | x <- execGRASS("v.what.rast", map=outlets_vect, column="elevation", raster=dem, intern=TRUE) 235 | } 236 | 237 | # delete temp 238 | if(keep_temp == FALSE) 239 | x <- execGRASS("g.remove", type="raster,vector", pattern="*_t", flags=c("f", "b"), intern=T) 240 | 241 | 242 | if(!silent) message(paste0("% Outlet points saved in map '",outlets_vect,"'")) 243 | if(!silent) message("%") 244 | if(!silent) message("% DONE!") 245 | if(!silent) message("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%") 246 | 247 | # stop sinking 248 | closeAllConnections() 249 | 250 | # restore original warning mode 251 | if(silent) 252 | options(warn = oldw) 253 | 254 | 255 | # exception handling 256 | }, error = function(e) { 257 | 258 | # stop sinking 259 | closeAllConnections() 260 | 261 | # restore original warning mode 262 | if(silent) 263 | options(warn = oldw) 264 | 265 | x <-tryCatch(suppressWarnings(execGRASS("r.mask", flags=c("r"), intern = T)), error=function(e){}) 266 | 267 | if(keep_temp == FALSE) 268 | x <- execGRASS("g.remove", type="raster,vector", pattern=paste("*_t",outlets_vect, sep=","), flags=c("f", "b"), intern=T) 269 | 270 | stop(paste(e)) 271 | }) 272 | 273 | } # EOF 274 | --------------------------------------------------------------------------------