soilhypfitS3methods {soilhypfit}

Common S3 Methods for Class fit_wrc_hcc

Description

This page documents the methods coef, summary, print, plot and lines for the class fit_wrc_hcc.

Usage

## S3 method for class 'fit_wrc_hcc'
coef(object, what = c("all", "nonlinear", "linear"),
    subset = NULL, residual_se = FALSE, se = FALSE, gof = FALSE, lc = FALSE,
    e0 = FALSE, bound = lc, ...)

## S3 method for class 'fit_wrc_hcc'
summary(object, what = c("all", "nonlinear", "linear"),
    subset = NULL, gof = TRUE, lc = TRUE, ...)

## S3 method for class 'fit_wrc_hcc'
print(x, ...)

## S3 method for class 'fit_wrc_hcc'
plot(x, what = c("wrc", "hcc"), y = NULL,
    subset = NULL, ylim_wc = NULL, ylim_hc = NULL,
    head_saturation = 0.01,
    beside = identical(sum(par("mfrow")), 2L), pch = 1, col_points = "black",
    col_line_x = "blue", lty_x = "solid",
    col_line_y = "orange", lty_y = "dashed",
    xlab_wc = "head [m]", ylab_wc = "water content [-]",
    xlab_hc = "head [m]", ylab_hc = "hyd. conductivity [m/d]",
    draw_legend = TRUE, draw_parameter = FALSE, cex_legend = 0.7, ...)

## S3 method for class 'fit_wrc_hcc'
lines(x, what = c("wrc", "hcc"), id = 1,
    head_saturation = 0.01, ...)

Arguments

object, x, y

an object of class fit_wrc_hcc, see fit_wrc_hcc.

what

character keyword indicating the type of parameters to return (coef) or the type of data to plot.

subset

an integer, character or logical vector to the choose the soil samples for which data and model curves are displayed or extracted. Defaults to NULL which displays results for all soil samples.

residual_se

a logical scalar to control whether residual standard errors (= standard deviations of residuals) should be returned, see Details.

se

a logical scalar to control whether standard errors of the nonlinear parameters \boldsymbol{\nu}^\mathrm{} should be returned, see Details and vcov.fit_wrc_hcc.

gof

a logical scalar to control whether goodness-of-fit statistic should be returned.

lc

a logical scalar to control whether the characteristic evaporative length should be returned, see evaporative-length.

e0

a logical scalar to control whether the evaporation rate should be returned. This is only effective for constrained estimation, see evaporative-length.

bound

a logical scalar to control whether the lower and upper bounds of the ratio L_\mathrm{c}/L_\mathrm{t} should be returned. This is only effective for constrained estimation, see evaporative-length.

ylim_wc

optional numeric vector of length 2 to set the range of water content values displayed on the y-axis (default NULL for automatic axis scales).

ylim_hc

optional numeric vector of length 2 to set the range of hydraulic conductivity values displayed on the y-axis (default NULL for automatic axis scales).

head_saturation

head value (unit m) assigned to zero head values in plots with logarithmic head scale.

beside

a logical scalar controlling whether water retention curves and hydraulic conductivity functions of a sample should be plotted side by side.

pch

plotting ‘character’, i.e., symbol to use for the measurements, see points.

col_points

color code or name for symbol colors for the measurements, see par.

col_line_x

color code or name for the line representing the fitted model x, see par.

lty_x

type of line representing the fitted model x, see par.

col_line_y

color code or name for the line representing the fitted model y, see par.

lty_y

type of line representing the fitted model y, see par.

xlab_wc

a character string with the annotation for the x-axis of a water retention curve.

ylab_wc

a character string with the annotation for the y-axis of a water retention curve.

xlab_hc

a character string with the annotation for the x-axis of a hydraulic conductivity function.

ylab_hc

a character string with the annotation for the y-axis of a hydraulic conductivity function.

draw_legend

a logical scalar controlling whether a legend with the values of the arguments x and y and the residual sums of squares is drawn if y is non-NULL.

draw_parameter

a logical scalar controlling whether the parameters are drawn (default FALSE).

cex_legend

a character expansion factor for annotations by legend.

id

a character string or integer scalar to select the sample for which to plot the modelled water retention curve or hydraulic conductivity function.

...

additional arguments passed to methods.

Details

Residual standard errors, standard errors of the nonlinear parameters and confidence intervals based on the asymptotic normal distribution are computed only for mpd and ml estimates, see
soilhypfitIntro, control_fit_wrc_hcc and vcov.

The plot method for class fit_wrc_hcc displays for each sample the measurements of the water retention curve and/or the hydraulic conductivity function, along with the fitted model curve(s). Optionally, the curves of a second model fit (specified by the argument y) can be plotted for each sample.

The lines method adds the curve of a fitted model to an existing plot.

Value

The method coef returns a dataframe with the estimated parameters (and optionally standard errors), optionally the value of the objective function along with convergence code and/or information on the characteristic evaporative length.

The method summary generates a list (of class summary.fit_wrc_hcc) with the following components:

data

a named integer vector with the total number of samples (nsamp) and the number of samples with only water retention (nwrc), only hydraulic conductivity (nhcc) and both type of measurements (nwrchcc).

control

a list with a subset (settings, nloptr, sce, approximation_alpha_k0, param_bound, param_tf) of the components of object[["control"]], see fit_wrc_hcc and control_fit_wrc_hcc.

result

a dataframe with the estimated parameters and optionally the residual sum of squares along with convergence code and/or information on the characteristic evaporative length.

call

the call component of object.

Note that only a print method is available for class summary.fit_wrc_hcc.

Author(s)

Andreas Papritz [e-mail].

See Also

soilhypfitIntro for a description of the models and a brief summary of the parameter estimation approach;

fit_wrc_hcc for (constrained) estimation of parameters of models for soil water retention and hydraulic conductivity data;

control_fit_wrc_hcc for options to control fit_wrc_hcc;

vcov for computing (co-)variances of the estimated nonlinear parameters;

prfloglik_sample for profile loglikelihood computations;

wc_model and hc_model for currently implemented models for soil water retention curves and hydraulic conductivity functions;

evaporative-length for physically constraining parameter estimates of soil hydraulic material functions.

Examples

# use of \donttest{} because execution time exceeds 5 seconds

data(sim_wrc_hcc)

# define number of cores for parallel computations
if(interactive()) ncpu <- parallel::detectCores() - 1L else ncpu <- 1L

# estimate parameters for 3 samples by unconstrained, global optimisation
# algorithm NLOPT_GN_MLSL
# sample 1: use only conductivity data
# sample 2: use only water content data
# sample 3: use both types of data
rfit_uglob <- fit_wrc_hcc(
  wrc_formula = wc ~ head | id, hcc_formula = hc ~ head | id,
  wrc_subset = id != 1, hcc_subset = id != 2,
  data = sim_wrc_hcc, fit_param = default_fit_param(tau = TRUE),
  control = control_fit_wrc_hcc(param_bound = param_boundf(
      alpha = c(0.00001, 50), n = c(1.0001, 7), tau = c(-1, 5)
    ), pcmp = control_pcmp(ncores = ncpu)))
print(rfit_uglob)
summary(rfit_uglob)
coef(rfit_uglob, what = "nonlinear")
coef(rfit_uglob, what = "linear", gof = TRUE)
coef(vcov(rfit_uglob), status = TRUE, se = FALSE)
op <- par(mfrow = c(3, 2))
plot(rfit_uglob)
on.exit(par(op))