Package 'SoilHyP'

Akaike Information Criterion (AIC)

Description

Akaike Information Criterion with or without correction term. Expression from Ye et al. (2008). Correction term by Hurvich and Tsai (1989).

Usage

AIC_HY(Phi, n.data, n.par, corr = TRUE)

Arguments

Phi	objective function value
n.data	number of measured data
n.par	number of adjustable parameters
corr	correction term TRUE or FALSE (see details)

Details

corr:
If number of measurements is small compared to the number of parameters, AIC can be extended by a correction term.

References

Ye, M., P.D. Meyer, and S.P. Neuman (2008): On model selection criteria in multimodel analysis. Water Resources Research 44 (3) W03428, doi:10.1029/2008WR006803.

Hurvich, C., and C. Tsai (1989): Regression and time series model selection in small samples. Biometrika 76 (2), 297–307, doi:10.1093/biomet/76.2.297.

Peters and Durner (2015): SHYPFIT 2.0 User's Manual.

Akaike, H. (1974): A new look at statistical model identification, IEEE Trans. Autom. Control, AC-19, 716–723.

---

Bayesian Information Criterion (BIC)

Description

Bayesian Information Criterion (Schwarz, 1978) for least square estimations.

Usage

BIC_HY(Phi, n.data, n.par)

Arguments

Phi	objective function value
n.data	number of measured data
n.par	number of adjustable parameters

References

Ye, M., P.D. Meyer, and S.P. Neuman (2008): On model selection criteria in multimodel analysis. Water Resources Research 44 (3) W03428, doi:10.1029/2008WR006803.

Schwarz, G. (1978): Estimating the dimension of a model. The Annals of Statistics 6 (2), 461–464. URL: http://dx. doi. org/10.1214/aos/1176344136.

Peters and Durner (2015): SHYPFIT 2.0 User's Manual.

---

Saturated hydraulic conductivity

Description

Calculates saturated hydraulic conductivity (ks) following Darcy's law

Usage

calcKS(V, Tmeas, L, A, dP)

Arguments

V	water volume passed sample [L³]
Tmeas	duration of measurement [time]
L	length of the sample [L]
A	cross-sectional area [L²]
dP	pressure difference between top and bottom of the sample during the measurement [L]

Details

Keep units consistent, e.g: V = cm³, dP = cm, A = cm², L = cm, Tmeas = hour

Value

hydraulic conductivity (ks) [L/time].

---

Evaporation experiment data

Description

Example data of an Evaporation experiment

Usage

data(dataSEM)

Format

An object of class dataSEM (inherits from data.frame) with 332 rows and 4 columns.

Details

Columns:

ts: timestamp [hour]
weight: total weight of soil sample [g]
tens.up: measurements of upper tensiometer [cm]
tens.low: measurements of lower tensiometer [cm]

---

Soil hydraulic property data

Description

Soil hydraulic property data including soil water contents (th), unsaturated hydraulic conductivities (Ku) and the corresponding suctions/pressure heads.

Usage

data(dataSHP)

Format

An object of class data.frame with 331 rows and 3 columns.

Details

Columns:

Ku: unsaturated hydraulic conductivity
th: volumetric water content
suc: suction

---

Dataset of soil hydraulic properties for testthat

Description

List with soil water contents (th) and unsaturated hydraulic conductivity values (ku) for spezific parameter of the uni- and bimodal hydraulic functions of van Genuchten and Peters-Durner-Iden (PDI).

Usage

data(dataSHP)

Format

An object of class list of length 8.

Details

List objects:

dataTestthat$th.vgm.uni: soil water contents for unimodal van Genuchten for parameter ths = 0.4, thr = 0, alfa = 0.02 and n = 1.5

dataTestthat$th.vgm.bi: soil water contents for bimodal van Genuchten for parameter ths = 0.4, thr = 0, alfa = 0.02, n = 2, w2 = 0.2, alfa2 = 1 and n2 = 10

dataTestthat$th.pdi.uni: soil water contents for unimodal PDI for parameter ths = 0.4, thr = 0, alfa = 0.02 and n = 1.5

dataTestthat$th.pdi.bi: soil water contents for bimodal PDI for parameter ths = 0.4, thr = 0, alfa = 0.02, n = 2, w2 = 0.2, alfa2 = 1 and n2 = 10

dataTestthat$ku.vgm.uni: soil water contents for unimodal van Genuchten for parameter Ks = 10, ths = 0.5, thr = 0, alfa = 0.02, n = 1.5 and tau = 0.5

dataTestthat$ku.vgm.bi: soil water contents for bimodal van Genuchten for parameter Ks = 10, ths = 0.5, thr = 0, alfa = 0.02, n = 1.5, tau = 0.5, w2 = 0.1, alfa2 = 0.1 and n2 = 3

dataTestthat$ku.pdi.uni: soil water contents for unimodal PDI for parameter Ks = 10, ths = 0.5, thr = 0, alfa = 0.02, n = 1.5, tau = 0.5 and omega = 0.001

dataTestthat$ku.pdi.bi: soil water contents for bimodal PDI for parameter Ks = 10, ths = 0.5, thr = 0, alfa = 0.02, n = 1.5, tau = 0.5, omega = 0.001, w2 = 0.2, alfa2 = 1 and n2 = 10

---

Calculate Soil Water Content from dielectric constant

Description

Calculate volumetric soil water content (SWC [L³/L³] from dielectric constant (DK) using different equations (e.g. Topp et al. 1980). Contains mainly functions for peat and other organic soils.

Usage

DK_to_SWC(
  DK,
  FUN = c("topp", "jacobsen", "jacobsen_soil_prop", "pepin_5cm", "pepin", "roth_org",
    "malicki_bd", "malicki_ths", "myllys", "myllys_sphagnum", "myllys_carex", "kellner",
    "kellner_h2", "kellner_h3", "kellner_h4", "beckwith", "yoshikawa_deadmoss",
    "yoshikawa_livemoss", "nagare", "oleszczuk", "gs3"),
  bd,
  ths,
  clay,
  SOM
)

Arguments

DK	dielectric constant
FUN	character string specifying the polynominal function. See details.
bd	bulk density [g/cm³] (needed for FUN == 'malicki_bd' and 'jacobsen_soil_prop')
ths	porosity or saturated water content [L³/L³] (needed for 'malicki_ths')
clay	content of clay [percent] (only needed for 'jacobsen')
SOM	soil organic matter [percent] (for 'jacobsen_soil_prop')

Details

Possible functions (FUN) are':

'topp'

Topp et al. (1980)

'jacobsen'

Jacobsen and Schjonning (1993), equation 2

'jacobsen_soil_prop'

Jacobsen and Schjonning (1993), equation 3 (bd, ths and SOM are required as input)

'pepin_5cm'

Pepin, S. et al. (1992), Table 2 Depth 5 cm

'pepin'

Pepin, S. et al. (1992), Table 2 Pooled data

'roth_org'

Roth et al. (1992), Tabel 3c

'malicki_bd'

Malicki, M.A. et al. (1996), equation 10 (bd is required as input)

'malicki_ths'

Malicki, M.A. et al. (1996), equation 12 (ths is required as input)

'myllys'

Myllys M. and Simojoki, A. (1996), Table 2 pooled

'myllys_sphagnum'

Myllys M. and Simojoki, A. (1996), Table 2 Sphagnum

'myllys_carex'

Myllys M. and Simojoki, A. (1996), Table 2 Carex

'kellner'

Kellner E., Lundin L.C. (2001), Table 2 Pooled data

'kellner_h2'

Kellner E., Lundin L.C. (2001), Table 2 H2

'kellner_h3'

Kellner E., Lundin L.C. (2001), Table 2 H3

'kellner_h4'

Kellner E., Lundin L.C. (2001), Table 2 H4

'beckwith'

Beckwith C.W. and Baird A.J. (2001), eq. 1

'yoshikawa_deadmoss'

from Tabel 1 in Nagare et al. (2001)

'yoshikawa_livemoss'

from Tabel 1 in Nagare et al. (2001)

'nagare'

Nagare et al. (2011), combined from Table 4

'oleszczuk'

from Table 1 in Oleszczuk et al. (2004)

'gs3'

Meter group, eq. 7

Value

data.table with columns DK, SWC and FUN.

References

Beckwith C.W., Baird A.J. (2001): Effect of biogenic gas bubbles on water flow through poorly decomposed blanket peat. Water Resour. Res., 37(3), 551-558.

Decagon Device (2016): GS3 Water Content, EC an Temperature Sensors, Operators maual , Decagon Device, Inc 2365 NE Hopkins Court Pullman WA 99163.

Jacobsen, O.H., Schjonning, P. (1993): A laboratory calibration of time domain reflectometry for soil water measurement including effects of bulk density and texture. Journal of Hydrology, 151(2-4), 147-157.

Kellner E., Lundin L.C. (2001): Calibration of Time Domain Reflectometry for Water Content in Peat Soil, Uppsala University, Dept. of Earth Sciences/Hydrology,SE-752 36 Uppsala, Sweden. Hydrology Research, 32(4-5), 315-332.

Malicki, M.A., Plagge, R., Roth, C.H. (1996): Improving the calibration of dielectric TDR soil moisture determination taking into account the solid soil. European Journal of Soil Science, 47:357-366.

Meter group: Operator manual GS3 (http://library.metergroup.com/Manuals/20429_GS3_Web.pdf)

Myllys M., Simojoki, A. (1996): Calibration of time domain reflectometry (TDR) for soil moisture measuremnts in cultivated peat soils, Agricultural Research centre of Finland, Institut of Cropand Soil Science, University of helsinki, Department of Applied Chemistry and Mircrobiology.

Nagare, R.M., Schincariol, R. A., Quinton, W.L., Hayashi, M. (2011): Laboratory calibration of time domain reflectometry to determine moisture content in undisturbed peat samples. European journal of soil science, 62(4), 505-515.

Oleszczuk R., Brandyk T., and Szatylowicz J., 1998: Possibilities of TDR method application to measure moisture content of peat-muck soil (in Polish). Zesz. Prob. Post. Nauk Roln., 458, 263-274.

Oleszczuk, R., Brandyk, T., Gnatowski, T., & Szatylowicz, J. (2004). Calibration of TDR for moisture determination in peat deposits. International agrophysics, 18(2).

Pepin, S., Plamondon, A.P., and Stein, J. (1992): Peat water-content measurement using time domain reflectrometry, Can. J. of Forest Res., Vol. 22, pp. 534-540

Roth C.H., M.A. Malicki, R. Plagge (1992): Empirical evaluation of the relationship between soil dielectric constant and volumetric water content as the basis for calibration soil moisture measurements by TDR; Institute of Ecology, Technical University of Berlin, Berlin, Germany and *Polish Academy of sciences, Institute of Agrophysics, ul. Doswiadczalna 4, 20-236 Lublin, Poland; Journal of Soil Science, 1992, 43, 1-13.

Topp, G.C., Davis, J.L., Annan, A.P. (1980): Electromagnetic determination of soil water content: Measurements in coaxial transmission lines. Water resources research, 16(3), 574-582.

Yoshikawa, K., Overduin, P., Harden, J. (2004): Moisture content measurements of moss (Sphagnum spp.) using commercial sensors. Permafrost Periglac, 15, 309-318.

---

Fit soil hydraulic properties

Description

Estimate parameter for soil water retention (SWC) and/or unsaturated hydraulic conductivity function (Ku) using Shuffled Complex Evolution (SCE) optimisation. Parameter can be estimated for van Genuchten-Mualem (vg or vgm) or Peters-Durner-Iden (PDI) parameterisation of the soil hydraulic properties.

Usage

fitSHP(
  obs = list(th = NULL, K = NULL),
  suc = list(th = NULL, K = NULL),
  par = NULL,
  lower = NULL,
  upper = NULL,
  FUN.shp = "vg",
  modality = "uni",
  par.shp = NULL,
  fit = "both",
  weighting = "var",
  log = c("alfa", "n", "ks"),
  control = list(ncomplex = 15, reltol = 1e-07, tolsteps = 7),
  suc.negativ = FALSE,
  integral = FALSE,
  L = NULL,
  log_Ku = TRUE,
  print.info = TRUE
)

Arguments

obs	list with named observations (th for water content and K for unsaturated hydraulic conductivity data)
suc	list of named suctions corresponding to th and/or K
par	a numeric vector of initial parameter values (see also SCEoptim). If missing default values are set.
lower	lower bounds on the parameters. Should be the same length as par and as upper, or length 1 if a bound applies to all parameters. If missing default values are set.
upper	upper bounds on the parameters. Should be the same length as par and as lower, or length 1 if a bound applies to all parameters. If missing default values are set.
FUN.shp	Funktion for soil hydraulic properties (vG, PDI or bc) (see SWC or Ku)
modality	pore size distribution ('uni' or 'bi')
par.shp	fixed parameter value named in list or vector
fit	fit parameter for 'SWC', 'Ku' or 'both' simultaneous.
weighting	weighting between SWC and Ku. Used if fit == both ('var', 'norm' or '2step').
log	names of parameter in list or vector which should be logarithmized during optimization
control	a list of options as in optim(), see SCEoptim
suc.negativ	set TRUE if suction/pressure heads are negative and FALSE if positive
integral	th as point value vs. suc(h) (FALSE) or th as mean water content over the column divided by the height (L) vs. suc(h) (TRUE) (see details).
L	sample height [cm]. Only needed for integral == TRUE
log_Ku	logarithmize Ku in the objective function and for weighting (TRUE).
print.info	print information about default values for par, lower, and upper if missing or fitting accuracy (TRUE or FALSE)

Details

weigthing:

var: th and K are weighted in the objective fuction by the measurement variance
norm: th and K are normed in objective fuction
stepwise: the parameter for th are fitted first and the remaining parameter for K afterwards (2step works aswell)

log:

The use of log is suggested for paramter 'alfa', 'n' and 'ks' for modality == 'uni'. For modality 'bi' additional 'alfa2' and 'n2' and for Fun.shp == 'pdi' additional 'omega'. Parameter in output ($par) are not returned logarithmized.
Delfault paramter values for par, lower and upper are logarithmized automatatically
If not the default values for par, lower and upper are taken, parameter which are named in 'log' must be scaled by the user in par, lower and upper.

integral:

The "integral" method is suggested from Peters and Durner (2008, 2015) to fit parameter on data from experiments were water contents are measured as mean water contents (e.g. simplified evaporation method or multi-step outflow experiments). Under the assumption that the water content is distributed linear over the column, the measured mean water content of the column is the integral over the whole column divided by the column length (L). Under hydraulic equilibrium this is equal to the integral of the retention function over the matric heads from the lower boundary to the upper boundary of the column divided by the height of the column (Peters 2008, 2015).

integral == TRUE can be very slow.

Value

"fitSHP" class

Author(s)

Ullrich Dettmann

References

Peters, A., & Durner, W. (2008). Simplified evaporation method for determining soil hydraulic properties. Journal of Hydrology, 356(1), 147-162.

Peters and Durner (2015). SHYPFIT 2.0 User’s Manual

Peters, A., Iden, S. C., & Durner, W. (2015). Revisiting the simplified evaporation method: Identification of hydraulic functions considering vapor, film and corner flow. Journal of Hydrology, 527, 531-542.

See Also

SCEoptim, SWC, Ku

Examples

## Not run: 
data('dataSHP')
# -------------------------------------------------------------------
# fit Soil Hydraulic Properties (SHP)
# -------------------------------------------------------------------
ans <- fitSHP(obs         = list(th = dataSHP$th, K = dataSHP$Ku),
             suc          = list(th = dataSHP$suc, K = dataSHP$suc),
             FUN.shp      = 'vg',
             modality     = 'uni',
             par.shp      =  NULL,
             fit          = 'both',
             weighting    = 'var',
             log          = c('alfa', 'n', 'ks'),
             control      = list(ncomplex = 15, reltol = 1e-07,tolsteps = 7),
             suc.negativ  = TRUE,
             integral     = FALSE,
             L            = 0,
             print.info   = TRUE
)
ans$par
plot(ans)
# --------------------------------------------------------------------
# bimodal van Genuchten-Mualem
ans <- fitSHP(obs         = list(th = dataSHP$th, K = dataSHP$Ku),
             suc          = list(th = dataSHP$suc, K = dataSHP$suc),
             FUN.shp      = 'vg',
             modality     = 'bi',
             par.shp      =  c(),
             fit          = 'both',
             weighting    = 'var',
             log          = c('alfa', 'n', 'ks', 'alfa2', 'n2'),
             suc.negativ  = TRUE,
             integral     = FALSE,
             L            = 0,
             print.info   = TRUE,
             control      = list(ncomplex = 15, reltol = 1e-07,tolsteps = 7)
)
ans$par
plot(ans)

## End(Not run)

---

Relative capillary conductivity

Description

Relative capillary conductivity based on Mualem's conductivity model for unimodal or bimodal van Genuchten-Mualem.

Usage

Kcap(suc, par.shp, suc.negativ = TRUE, modality = "uni")

Arguments

suc	Suction/pressure heads. Negative if suc.negativ = TRUE
par.shp	named parameter in list or vector
suc.negativ	set TRUE if suction/pressure heads are negative and FALSE if positive
modality	pore size distributions ('uni' or 'bi')

Details

par.shp:

alfa [1/L]: van Genuchten shape parameter
n [-]: van Genuchten shape parameter
m [-]: shape parameter (m = 1-(1/n) if missing)
tau [-]: tortuosity and connectivity parameter (minimum -1 or -2 for the PDI model; for details see Peters (2014))
h0 [L]: suction at water content of 0 (i.e. oven dryness) (h0 = 10^6.8 if missing, corresponding to oven dryness at 105°C (Schneider and Goss, 2012))

par.shp: additional parameter for bimodal (modality == 'bi')

w2 [-]: weigthing between pore space distribution
alfa2 [1/L]: van Genuchten parameter alfa for second pore space distribution
n2 [-]: van Genuchten parameter n for second pore space distribution

References

Peters, A. (2014). Reply to comment by S. Iden and W. Durner on Simple consistent models for water retention and hydraulic conductivity in the complete moisture range. Water Resour. Res. 50, 7535–7539.

Van Genuchten, M. T. (1980). A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil science society of America journal, 44(5), 892-898.

Mualem, Y. (1976). A new model for predicting the hydraulic conductivity of unsaturated porous media. Water resources research, 12(3), 513-522.

Schneider, M., & Goss, K. U. (2012). Prediction of the water sorption isotherm in air dry soils. Geoderma, 170, 64-69.

See Also

Ku

---

Relative film conductivity

Description

Relative film conductivity described by Peters (2013).

Usage

Kfilm(suc, par.shp, modality = "uni", suc.negativ = TRUE)

Arguments

suc	Suction/pressure heads. Negative if suc.negativ = TRUE
par.shp	named parameter in list or vector
modality	pore size distribution ('uni' or 'bi')
suc.negativ	set TRUE if suction/pressure heads are negative and FALSE if positive

Details

par.shp:

ths [-]: saturated water content
thr [-]: residual water content
alfa [1/L]: van Genuchten shape parameter
n [-]: van Genuchten shape parameter
h0 [L]: suction at water content of 0 (i.e. oven dryness) (h0 = 10^6.8 if missing, corresponding to oven dryness at 105°C (Schneider and Goss, 2012))
a: slope at the log scale (a = -1.5 if missing as suggested by Tokunaga (2009) and Peters (2013))

par.shp: additional parameter for bimodal (modality == 'bi')

alfa2 [1/L]: van Genuchten parameter alfa for second pore space distribution
n2 [-]: van Genuchten parameter n for second pore space distribution

References

Peters, A. (2013). Simple consistent models for water retention and hydraulic conductivity in the complete moisture range. Water Resour. Res. 49, 6765–6780. physics-a review. Vadose Zone J. http://dx.doi.org/10.2136/vzj2012.0163.

Tokunaga, T. K. (2009). Hydraulic properties of adsorbed water films in unsaturated porous media. Water resources research, 45(6).

Schneider, M., & Goss, K. U. (2012). Prediction of the water sorption isotherm in air dry soils. Geoderma, 170, 64-69.

See Also

Ku

---

Unsaturated hydraulic conductivity

Description

Calculates unsaturated hydraulic conductivity for a given suction for unimodal or bimodal van Genuchten-Mualem (vg/vgm), Peters-Durner-Iden (PDI) and Brooks and Corey (bc) (only unimodal) parameterisation.

Usage

Ku(suc, FUN.shp = "vG", par.shp, modality = "uni", suc.negativ = TRUE)

Arguments

suc	Suction/pressure heads. Negative if suc.negativ = TRUE
FUN.shp	Funktion for soil hydraulic properties (vGM or PDI) (see details)
par.shp	named parameter in list or vector
modality	pore size distribution ('uni' or 'bi')
suc.negativ	set TRUE if suction/pressure heads are negative and FALSE if positive

Details

FUN.shp:

vGM: van Genuchten-Mualem (uni or bimodal) ('vg' works aswell)
PDI: Peters-Durner-Iden with van Genuchtens saturation function (uni or bimodal)
bc: Brooks and Corey (unimodal)

par.shp (vG and PDI):

ths [-]: saturated water content
thr [-]: residual water content
alfa [1/L]: van Genuchten shape parameter
n [-]: van Genuchten shape parameter
m [-]: shape parameter (m = 1-(1/n) if missing)
Ks [L/time]: saturated hydraulic conductivity
tau [-]: tortuosity and connectivity parameter (minimum -1 or -2 for the PDI model; see Peters (2014) for details)

par.shp (additional parameter for 'PDI'):

omega: weighting between relative capillary and film conductivity
h0 [L]: suction at water content of 0 (i.e. oven dryness) (h0 = 10^6.8 if missing, corresponding to oven dryness at 105°C (Schneider and Goss, 2012))
a: slope at the log scale (a = -1.5 if missing as suggested by Tokunaga (2009) and Peters (2013))

par.shp (additional parameter for bimodal (modality = 'bi')):

w2 [-]: weigthing between pore space distributions
alfa2 [1/L]: van Genuchten parameter alfa for second pore space distribution
n2 [-]: van Genuchten parameter n for second pore space distribution

par.shp (BC):

ths [-]: saturated water content
thr [-]: residual water content
alfa [1/L]: inverse of the air-entry value or bubbling pressure
lambda [-]: pore size distribution index
tau [-]: tortuosity and connectivity parameter (minimum -1 or -2 for the PDI model; see Peters (2014) for details)

most input works for upper- and lowercase letters

Value

unsaturated hydraulic conductivity (ku)

Author(s)

Ullrich Dettmann

References

Van Genuchten, M. T. (1980). A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil science society of America journal, 44(5), 892-898.

Mualem, Y. (1976). A new model for predicting the hydraulic conductivity of unsaturated porous media. Water resources research, 12(3), 513-522.

Peters, A. (2013). Simple consistent models for water retention and hydraulic conductivity in the complete moisture range. Water Resour. Res. 49, 6765–6780. physics-a review. Vadose Zone J. http://dx.doi.org/10.2136/vzj2012.0163.

Iden, S., Durner, W. (2014). Comment to Simple consistent models for water retention and hydraulic conductivity in the complete moisture range by A. Peters. Water Resour. Res. 50, 7530–7534.

Peters, A. (2014). Reply to comment by S. Iden and W. Durner on Simple consistent models for water retention and hydraulic conductivity in the complete moisture range. Water Resour. Res. 50, 7535–7539.

Tokunaga, T. K. (2009), Hydraulic properties of adsorbed water films in unsaturated porous media, Water Resour. Res., 45, W06415, doi: 10.1029/2009WR007734.

Priesack, E., Durner, W., 2006. Closed-form expression for the multi-modal unsaturated conductivity function. Vadose Zone J. 5, 121–124.

Durner, W. (1994). Hydraulic conductivity estimation for soils with heterogeneous pore structure. Water Resources Research, 30(2), 211-223.

Schneider, M., & Goss, K. U. (2012). Prediction of the water sorption isotherm in air dry soils. Geoderma, 170, 64-69.

Brooks, R.H., and A.T. Corey (1964): Hydraulic properties of porous media. Hydrol. Paper 3. Colorado State Univ., Fort Collins, CO, USA.

See Also

SWC and Sat

Examples

# --------------------------------------------
#  Unimodal van Genuchten
# --------------------------------------------
Ku(suc = seq(1, 1000, by = 1), FUN.shp = 'vGM',
   par.shp = list(Ks = 10, ths = 0.5, thr = 0, alfa = 0.02, n = 1.5, tau = 0.5),
   modality = 'uni', suc.negativ = FALSE)
# --------------------------------------------
#  Bimodal van Genuchten
# --------------------------------------------
Ku(suc = seq(1, 1000, by = 1), FUN.shp = 'vGM',
   par.shp = list(Ks = 10, ths = 0.5, thr = 0, alfa = 0.02,
   n = 1.5, tau = 0.5, w2 = 0.1, alfa2 = 0.1, n2 = 3),
   modality = 'bi', suc.negativ = FALSE)
# --------------------------------------------
#  Unimodal Peters-Durner-Iden (PDI)
# --------------------------------------------
Ku(suc = seq(1, 1000, by = 1), FUN.shp = 'PDI', modality = 'uni',
   par.shp = list(Ks = 10, ths = 0.5, thr = 0, alfa = 0.02, n = 1.5, tau = 0.5, omega = 0.001),
   suc.negativ = FALSE)
# --------------------------------------------
#  Brooks and Corey (BC) (only unimodal)
# --------------------------------------------
Ku(suc = seq(1, 1000, by = 1), FUN.shp = 'bc', modality = 'uni',
   par.shp = list(ths = 0.4, thr = 0, lambda =  0.211, alfa = 0.1, tau = 0.5, ks = 10),
   suc.negativ = FALSE)
# --------------------------------------------

---

Nash-Sutcliffe efficiency (NSE)

Description

Nash-Sutcliffe efficiency (NSE)

Usage

NSE(obs, sim)

Arguments

obs	measured values
sim	predicted values

References

Nash, J. E., and J.V. Sutcliffe (1970): River flow forecasting through conceptual models. 1. a discussion of principles. Journal of Hydrology 10, 282–290.

---

Plot dataSEM

Description

Creates plot of object with class 'dataSEM'. If input x is provided as list with more than one elements, the output plot is a grid with multiple plots.

Usage

## S3 method for class 'dataSEM'
plot(
  x,
  ts = "ts",
  tens.up = "tens.up",
  tens.low = "tens.low",
  weight = "weight",
  plot.tens = TRUE,
  plot.weight = TRUE,
  plot.legend = TRUE,
  xlab = "timestamp",
  plot.title,
  color.tens = c("#00FFFF", "#008B8B"),
  color.weight = "#EC382B",
  ...
)

Arguments

x	object of class dataSEM (see details)
ts	character specifying the column containing the time stamp (format must be numeric or POSIXct)
tens.up	character specifying the column containing the measurements of the upper tensiometer
tens.low	character specifying the column containing the measurements of the lower tensiometer
weight	character specifying the column containing the weight
plot.tens	plot tensiometer values (TRUE/FALSE)
plot.weight	plot weight values (TRUE/FALSE)
plot.legend	plot legend (TRUE/FALSE)
xlab	lable for the x axis
plot.title	character spezifying plot title. If empty no title will be added.
color.tens	colors of the plotted tensiometer values
color.weight	color of the plotted weight values
...	Graphical arguments (see par). If plot.tens = T and plot.weight = T, lty only works for tensiometer values.

Details

Object x can be:
- class(x): "dataSEM" "data.frame"
- class(x): "dataSEM" "data.table"
- class(x): "dataSEM" (if x is a list)

If x is a list with more than 1 elements, the output plot is a grid with mutliple plots. Columns and row number can be adjusted with grafical argument mfrow (see par)

If x has the wrong class, the class can be set with:
class(x) <- c('dataSEM', class(x)) (if x has the class data.frame or data.table) and
class(x) <- 'dataSEM' (if x has the class list).

Author(s)

Ullrich Dettmann

---

Plot fitSHP object

Description

Creates plot of fitSHP object with measured and fitted SWC, KU or both depending on fitSHP object

Usage

## S3 method for class 'fitSHP'
plot(x, ...)

Arguments

x	object of class fitSHP
...	arguments for plot

---

Predict values using fitSHP object

Description

Predicts values using fitSHP object with calibrated paramter of SWC, KU or both depending on the fitSHP object

Usage

## S3 method for class 'fitSHP'
predict(object, suc = NULL, length.out = 100, suc.negativ = FALSE, ...)

Arguments

object	object of class fitSHP
suc	Suction/pressure heads for the prediction of the soil hydraulic properties
length.out	output length if suc == NULL
suc.negativ	set TRUE if suction/pressure heads are negative and FALSE if positive
...	arguments for predict

---

Read Evaporation Experiment data from ku-pf Apparatur

Description

Reads multiple ku-pf Apparatur files from a directory and returns them as list of data.tables.

Usage

read.kupf(
  path,
  colnames.out = c("ts", "tens.up", "tens.low", "weight"),
  firstrow.char = "Date/Time\tTension top\tTension bottom\tWeight",
  format.time_stamp = "%d.%m.%Y %H:%M:%S",
  tz.time_stamp = "GMT",
  ...
)

Arguments

path	path to ku-pf files (character)
colnames.out	colnames of output (default: c('ts', 'tens.up', 'tens.low', 'weight'))
firstrow.char	character in first row of ku-pf files (default: 'Date/Time Tension top Tension bottom Weight') (see details)
format.time_stamp	POSIXct format of the time stamp column (column 1, here named 'ts') (see strptime)
tz.time_stamp	time zone of the time stamp column (column 1, here named 'ts') (default: 'GMT') (see as.POSIXct)
...	arguments to list.files

Details

input file format:

The standard file format of ku-pf files looks like:

Date/Time Tension top Tension bottom Weight
kPa kPa g
01.11.2017 14:11:16 -0.48 -0.15 969.02
01.11.2017 14:21:16 -0.47 -0.14 969.00
01.11.2017 14:31:16 -0.46 -0.13 968.98

If the first row of the ku-pf files differs to the expression used here ('Date/Time Tension top Tension bottom Weight"), it can be set with firstrow.char.

sample_info:

File names are added as attribut to the output (attr(out, 'sample_info')).

The ku-pf software gives the possibility to add sample spezific information in the first row of the file. Depending on the input the ku-pf files than look:

sample_name;project
Date/Time Tension top Tension bottom Weight
kPa kPa g
01.11.2017 14:11:16 -0.48 -0.15 969.02
01.11.2017 14:21:16 -0.47 -0.14 969.00
01.11.2017 14:31:16 -0.46 -0.13 968.98

- For this case the first line is added as attribute to the output (attr(out, 'sample_info')$info)

Value

list of the class dataSEM containing data.tables as list elements.

Author(s)

Ullrich Dettmann

---

Root mean square error (RMSE)

Description

Calculate Root mean square error (RMSE)

Usage

RMSE(obs, sim, na.rm = FALSE)

Arguments

obs	measured values
sim	predicted values
na.rm	logical. Should missing values be removed?

---

Relative saturation function

Description

Relative saturation function for adsorptive water storage described by a piecwise linear function (Iden and Durner, 2014).

Usage

Sad(suc, par.shp, modality = c("uni"), suc.negativ = TRUE)

Arguments

suc	Suction/pressure heads. Negative if suc.negativ = TRUE
par.shp	named parameter of soil hydraulic properties in list or vector (see details)
modality	pore size distribution ('uni' or 'bi')
suc.negativ	set TRUE if suction/pressure heads are negative and FALSE if positive

Details

par.shp:

ths [-]: saturated water content
thr [-]: residual water content
alfa [1/L]: van Genuchten shape parameter
n [-]: van Genuchten shape parameter
h0 [L]: suction at water content of 0 (i.e. oven dryness) (h0 = 10^6.8 if missing, corresponding to oven dryness at 105°C (Schneider and Goss, 2012))

par.shp (additional for bimodal (modality = 'bi')):

alfa2 [1/L]: van Genuchten parameter alfa for second pore space distribution
n2 [-]: van Genuchten parameter n for second pore space distribution

Author(s)

Ullrich Dettmann

References

Iden, S., Durner, W. (2014). Comment to Simple consistent models for water retention and hydraulic conductivity in the complete moisture range by A. Peters. Water Resour. Res. 50, 7530–7534.

Schneider, M., & Goss, K. U. (2012). Prediction of the water sorption isotherm in air dry soils. Geoderma, 170, 64-69.

---

Capillary saturation function

Description

Capillary saturation function of van Genuchten (unimodal or bimodal pore space distributions) and Brooks and Corey (unimodal pore space distribution).

Usage

Sat(suc, par.shp, modality = c("uni"), FUN.shp = "vg", suc.negativ = TRUE)

Arguments

suc	Suction/pressure heads. Negative if suc.negativ = TRUE
par.shp	named parameter in list or vector
modality	pore size distribution ('uni' or 'bi')
FUN.shp	Funktion for soil hydraulic properties (vG or bc) (see details)
suc.negativ	set TRUE if suction/pressure heads are negative and FALSE if positive

Details

FUN.shp:

vG: van Genuchten (uni or bimodal) (vGM is working aswell)
bc: Brooks and Corey (uni)

par.shp (van Genuchten):

alfa [1/L]: van Genuchten shape parameter
n [-]: van Genuchten shape parameter
m [-]: shape parameter (m = 1-(1/n) if missing)

par.shp (additional for bimodal (modality = 'bi')):

w2 [-]: weigthing between pore space distribution
alfa2 [1/L]: van Genuchten parameter alfa for second pore space distribution
n2 [-]: van Genuchten parameter n for second pore space distribution

par.shp (Brooks and Corey):

alfa [1/L]: inverse of the air-entry value or bubbling pressure
lambda [-]: pore size distribution index

References

Van Genuchten, M. T. (1980). A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil science society of America journal, 44(5), 892-898.

Durner, W. (1994). Hydraulic conductivity estimation for soils with heterogeneous pore structure. Water Resources Research, 30(2), 211-223.

Brooks, R.H., and A.T. Corey (1964): Hydraulic properties of porous media. Hydrol. Paper 3. Colorado State Univ., Fort Collins, CO, USA.

---

Capillary saturation function

Description

Capillary saturation function of van Genuchten for unimodal or bimodal pore space distributions.

Usage

Sat_old(suc, par.shp, modality = c("uni"), suc.negativ = TRUE)

Arguments

suc	Suction/pressure heads. Negative if suc.negativ = TRUE
par.shp	named parameter in list or vector
modality	pore size distribution ('uni' or 'bi')
suc.negativ	set TRUE if suction/pressure heads are negative and FALSE if positive

Details

par.shp:

alfa [1/L]: van Genuchten shape parameter
n [-]: van Genuchten shape parameter
m [-]: shape parameter (m = 1-(1/n) if missing)

par.shp (additional for bimodal (modality = 'bi')):

w2 [-]: weigthing between pore space distribution
alfa2 [1/L]: van Genuchten parameter alfa for second pore space distribution
n2 [-]: van Genuchten parameter n for second pore space distribution

References

Van Genuchten, M. T. (1980). A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil science society of America journal, 44(5), 892-898.

Durner, W. (1994). Hydraulic conductivity estimation for soils with heterogeneous pore structure. Water Resources Research, 30(2), 211-223.

---

Rescaled capillary saturation function

Description

Rescaled capillary saturation function by Iden and Durner (2014)

Usage

Scap(suc, par.shp, modality = c("uni"), suc.negativ = FALSE)

Arguments

suc	Suction/pressure heads. Negative if suc.negativ = TRUE
par.shp	named parameter in list or vector
modality	pore size distribution ('uni' or 'bi')
suc.negativ	set TRUE if suction/pressure heads are negative and FALSE if positive

Details

par.shp:

alfa [1/L]: van Genuchten shape parameter
n [-]: van Genuchten shape parameter
m [-]: shape parameter (m = 1-(1/n) if missing)
h0 [L]: suction at water content of 0 (i.e. oven dryness) (h0 = 10^6.8 if missing, corresponding to oven dryness at 105°C (Schneider and Goss, 2012))

par.shp (additional for bimodal (modality = 'bi') pore size distribution:)

w2 [-]: weigthing between pore space distribution
alfa2 [1/L]: van Genuchten parameter alfa for second pore space distribution
n2 [-]: van Genuchten parameter n for second pore space distribution
m2 [-]: shape parameter (m = 1-(1/n2) if missing)

Scap(h) = (Gamma(h)- Gamma(h0))/(1 - Gamma(h0))
Gamma descripes the capillary saturation function. Here the saturation function of van Genuchten is used:
gamma(h) = (1/(1 + -suc * alfa)^n)^m (see also Sat)

References

Iden, S., Durner, W. (2014). Comment to Simple consistent models for water retention and hydraulic conductivity in the complete moisture range by A. Peters. Water Resour. Res. 50, 7530–7534.

Schneider, M., & Goss, K. U. (2012). Prediction of the water sorption isotherm in air dry soils. Geoderma, 170, 64-69.

---

Shuffled Complex Evolution (SCE) optimisation.

Description

Shuffled Complex Evolution (SCE) optimisation. Designed to have a similar interface to the standard optim function.
The function is copied from the hydromad package (https://github.com/floybix/hydromad/)

Usage

SCEoptim(FUN, par, lower = -Inf, upper = Inf, control = list(), ...)

Arguments

FUN	function to optimise (to minimise by default), or the name of one. This should return a scalar numeric value.
par	a numeric vector of initial parameter values.
lower	lower bounds on the parameters. Should be the same length as par and as upper, or length 1 if a bound applies to all parameters.
upper	upper bounds on the parameters. Should be the same length as par and as lower, or length 1 if a bound applies to all parameters.
control	a list of options as in optim(), see Details.
...	further arguments passed to FUN

Details

This is an evolutionary algorithm combined with a simplex algorithm.

Options can be given in the list control, in the same way as with optim:

ncomplex

number of complexes. Defaults to 5.

cce.iter

number of iteration in inner loop (CCE algorithm). Defaults to NA, in which case it is taken as 2 * NDIM + 1, as recommended by Duan et al (1994).

fnscale

function scaling factor (set to -1 for a maximisation problem). By default it is a minimisation problem.

elitism

influences sampling of parents from each complex. Duan et al (1992) describe a 'trapezoidal' (i.e. linear weighting) scheme, which corresponds to elitism = 1. Higher values give more weight towards the better parameter sets. Defaults to 1.

initsample

sampling scheme for initial values: "latin" (hypercube) or "random". Defaults to "latin".

reltol

reltol is the convergence threshold: relative improvement factor required in an SCE iteration (in same sense as optim), and defaults to 1e-5.

tolsteps

tolsteps is the number of iterations where the improvement is within reltol required to confirm convergence. This defaults to 20.

maxit

maximum number of iterations. Defaults to 10000.

maxeval

maximum number of function evaluations. Defaults to Inf.

maxtime

maximum duration of optimization in seconds. Defaults to Inf.

returnpop

whether to return populations (parameter sets) from all iterations. Defaults to FALSE.

trace

an integer specifying the level of user feedback. Defaults to 0.

REPORT

number of iterations between reports when trace >= 1. Defaults to 1.

Value

a list of class "SCEoptim".

par	optimal parameter set.
value	value of objective function at optimal point.
convergence	code, where 0 indicates successful covergence.
message	(non-)convergence message.
counts	number of function evaluations.
iterations	number of iterations of the CCE algorithm.
time	number of seconds taken.
POP.FIT.ALL	objective function values from each iteration in a matrix.
BESTMEM.ALL	best parameter set from each iteration in a matrix.
POP.ALL	if (control$returnpop = TRUE), the parameter sets from each iteration are returned in a three dimensional array.
control	the list of options settings in effect.

Author(s)

This code is copied from the hydromad package

https://github.com/floybix/hydromad/
http://hydromad.catchment.org/

and written from Felix Andrews [email protected]

who adapted, and substantially revised it, from Brecht Donckels' MATLAB code, which was in turn adapted from Qingyun Duan's MATLAB code:

References

Qingyun Duan, Soroosh Sorooshian and Vijai Gupta (1992). Effective and Efficient Global Optimization for Conceptual Rainfall-Runoff Models Water Resources Research 28(4), pp. 1015-1031.

Qingyun Duan, Soroosh Sorooshian and Vijai Gupta (1994). Optimal use of the SCE-UA global optimization method for calibrating watershed models, Journal of Hydrology 158, pp. 265-284.

See Also

optim, DEoptim package, rgenoud package

Examples

## reproduced from help("optim")

## Rosenbrock Banana function
Rosenbrock <- function(x){
  x1 <- x[1]
  x2 <- x[2]
  100 * (x2 - x1 * x1)^2 + (1 - x1)^2
}
#lower <- c(-10,-10)
#upper <- -lower
ans <- SCEoptim(Rosenbrock, c(-1.2,1), control = list(trace = 1))
str(ans)

## 'Wild' function, global minimum at about -15.81515
Wild <- function(x)
  10*sin(0.3*x)*sin(1.3*x^2) + 0.00001*x^4 + 0.2*x+80
ans <- SCEoptim(Wild, 0, lower = -50, upper = 50,
                control = list(trace = 1))
ans$par

---

Simplified evaporation method (SEM)

Description

Determines unsaturated hydraulic conductivity and water retention characteristics from laboratory evaporation experiments.

Usage

SEM(
  suc.up,
  suc.low,
  weight = NULL,
  t,
  ths = NULL,
  r = 3.6,
  L = 6,
  z1 = 1.5,
  z2 = 4.5,
  sd.tens = 0.2,
  suc.negativ = TRUE,
  suc.out = "weighted"
)

Arguments

suc.up	a numeric vector containing the measured suctions [cm] of the upper tensiometer
suc.low	a numeric vector containing the measured suctions [cm] of the lower tensiometer
weight	a numeric vector containing the measured weights [g]
t	time in seconds [s]
ths	saturated water content (optional) for the calulation of the soil water contents (th)
r	sample radius [cm]
L	sample height [cm]
z1	depth of upper tensiometer [cm]
z2	depth of lower tensiometer [cm]
sd.tens	measurement accuracy of tensiometer [cm]
suc.negativ	set TRUE if suction/tensiometer values are negative and FALSE if positive
suc.out	'weighted' (default), arithmetic ('ari') or geometric ('geo') mean of the tensiometer readings (see Peters (2015) for details)

Details

sd.tens:

At the beginning of the experiment when gradients of the hydraulic head are small, hydraulic conductivities cannot be calculated. Following Peters and Durner (2008) hydraulic conductivities calculated from gradients smaller than (6*sd.tens)/(z2-z1) are set to NA.

Value

data.frame

Ki: unsaturated hydraulic conductivity [cm/day]
th: water content (th) is returned if ths is provided as input
suc: suction, either (1) weighted between arithmetic and geometric mean (default), (2) the arithmetic mean or (3) the geometric mean (see Peters 2015)

Author(s)

Ullrich Dettmann

References

Wind, G. P. (1966). Capillary conductivity data estimated by a simple method (No. 80). [sn].

Peters, A., Iden, S. C., & Durner, W. (2015). Revisiting the simplified evaporation method: Identification of hydraulic functions considering vapor, film and corner flow. Journal of Hydrology, 527, 531-542.

Peters, A., & Durner, W. (2008). Simplified evaporation method for determining soil hydraulic properties. Journal of Hydrology, 356(1), 147-162.

Schindler, U., 1980. Ein Schnellverfahren zur Messung der Wasserleitfähigkeit im teilgesättigten Boden an Stechzylinderproben. Arch. Acker- Pflanzenbau Bodenkd. 24, 1–7.

Examples

# ----------------------------------------------------------------------------
# Calculate hydraulic properties with the 'Simplified Evaporation Method' (SEM)
# ----------------------------------------------------------------------------
data('dataSEM')
ths <- 0.7  # define saturated water content (ths) (optional)
shp <- SEM(suc.up     = dataSEM$tens.up,
          suc.low     = dataSEM$tens.low,
          weight      = dataSEM$weight,
          t           = dataSEM$ts*60*60,
          r           = 3.6, # radius of sample
          L           = 6,   # height of sample
          z1          = 1.5, # depth of upper tensiometer [cm]
          z2          = 4.5, # depth of lower tensiometer [cm]
          sd.tens     = 0.1,  # tensiometer accuracy (see ?SEM)
          ths         = ths,
          suc.negativ = TRUE,
          suc.out     = 'weighted'
)

---

Soil water content

Description

Calculates the volumetric soil water content for a corresponding suction/pressure head (th(suc)) for unimodal or bimodal van Genuchten (vG), Peters-Durner-Iden (PDI) and Brooks and Corey (bc) (only unimodal) parameterisation.

Usage

SWC(
  suc,
  par.shp = c(ths = 0.9, thr = 0, alfa = 0.02, n = 2),
  FUN.shp = "vg",
  modality = "uni",
  suc.negativ = TRUE
)

Arguments

suc	Suction/pressure heads. Negative if suc.negativ = TRUE
par.shp	named parameter in list or vector
FUN.shp	Funktion for soil hydraulic properties (vG, PDI or bc) (see details)
modality	pore size distribution ('uni' or 'bi')
suc.negativ	set TRUE if suction/pressure heads are negative and FALSE if positive

Details

FUN.shp:

vG: van Genuchten (uni or bimodal) (vGM is working aswell)
PDI: Peters-Durner-Iden with saturation function of van Genuchten (uni or bimodal)
bc: Brooks and Corey (unimodal)

par.shp (vG and PDI):

ths [-]: saturated water content
thr [-]: residual water content
alfa [1/L]: van Genuchten shape parameter
n [-]: van Genuchten shape parameter
m [-]: shape parameter (m = 1-(1/n) if missing)

par.shp (additional for 'PDI'):

h0 [L]: suction at water content of 0 (i.e. oven dryness) (h0 = 10^6.8 if missing, corresponding to oven dryness at 105°C (Schneider and Goss, 2012))

par.shp (additional for bimodal (modality = 'bi')):

w2 [-]: weigthing between pore space distributions
alfa2 [1/L]: van Genuchten parameter alfa for second pore space distribution
n2 [-]: van Genuchten parameter n for second pore space distribution
m2 [-]: shape parameter (m2 = 1-(1/n2) if missing)

par.shp (BC):

ths [-]: saturated water content
thr [-]: residual water content
alfa [1/L]: inverse of the air-entry value or bubbling pressure
lambda [-]: pore size distribution index

PDI:
theta(h) = (ths - thr) * Scap(h) + thr * Sad(h)
Scap: Rescaled capillary saturation function
Sad: Relative saturation function for adsorbed water

input for FUN.shp and modality works for upper- and lowercase letters

Value

volumetric water content theta (th) [L³/L³]

Author(s)

Ullrich Dettmann

References

Van Genuchten, M. T. (1980). A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil science society of America journal, 44(5), 892-898.

Durner, W. (1994). Hydraulic conductivity estimation for soils with heterogeneous pore structure. Water Resources Research, 30(2), 211-223.

Peters, A. (2013). Simple consistent models for water retention and hydraulic conductivity in the complete moisture range. Water Resour. Res. 49, 6765–6780. physics-a review. Vadose Zone J. http://dx.doi.org/10.2136/vzj2012.0163.

Iden, S., Durner, W. (2014). Comment to Simple consistent models for water retention and hydraulic conductivity in the complete moisture range by A. Peters. Water Resour. Res. 50, 7530–7534.

Peters, A. (2014). Reply to comment by S. Iden and W. Durner on Simple consistent models for water retention and hydraulic conductivity in the complete moisture range. Water Resour. Res. 50, 7535–7539.

Schneider, M., & Goss, K. U. (2012). Prediction of the water sorption isotherm in air dry soils. Geoderma, 170, 64-69.

Brooks, R.H., and A.T. Corey (1964): Hydraulic properties of porous media. Hydrol. Paper 3. Colorado State Univ., Fort Collins, CO, USA.

See Also

Ku Sat

Examples

# --------------------------------------------
#  Unimodal van Genuchten
# --------------------------------------------
SWC(suc = seq(1, 1000, by = 1), par.shp = c(ths = 0.4, thr = 0, alfa = 0.02, n = 1.5),
FUN.shp = c('vG'), modality = 'uni', suc.negativ = FALSE)
# --------------------------------------------
#  Bimodal van Genuchten
# --------------------------------------------
SWC(suc = seq(1, 1000, by = 1),
par.shp = c(ths = 0.4, thr = 0, alfa = 0.02, n = 2, w2 = 0.2, alfa2 = 1, n2 = 10),
FUN.shp  = c('vG'), modality = c('bi'), suc.negativ = FALSE)
# --------------------------------------------
#  Unimodal PDI
# --------------------------------------------
SWC(suc = seq(1, 1000, by = 1), par.shp = list(ths = 0.4, thr = 0, n = 1.6, alfa = 0.02),
FUN.shp = c('pdi'), modality = c('uni'), suc.negativ = FALSE)
# --------------------------------------------
#  Brooks and Corey (BC) (only unimodal)
SWC(suc = seq(1, 1000, by = 1), par.shp = list(ths = 0.4, thr = 0, lambda =  0.211, alfa = 0.1),
FUN.shp = c('bc'), modality = c('uni'), suc.negativ = FALSE)
# --------------------------------------------

---