vcov {soilhypfit}

vcov Method for Class fit_wrc_hcc

Description

This page documents the method vcov for the class fit_wrc_hcc and its coef method. vcov extracts the covariance matrices of the nonlinear parameters \widehat{\boldsymbol{\nu}} estimated by maximum likelihood or maximum posterior density.

Usage

## S3 method for class 'fit_wrc_hcc'
vcov(object, subset = NULL, grad_eps,
    bound_eps = sqrt(.Machine$double.eps), ...)

## S3 method for class 'vcov_fit_wrc_hcc'
coef(object, se = TRUE, correlation = se,
    status = FALSE, ...)

Arguments

object

either an object of class fit_wrc_hcc for vcov or an object of class vcov_fit_wrc_hcc for coef.

subset

an integer, character or logical vector to the choose the soil samples for which covariance matrices should be extracted. Defaults to NULL, which extracts the covariances for all soil samples.

grad_eps

a numeric scalar defining a critical magnitude of the moduli of scaled gradient components so that they are considered to be approximately equal to zero, see Details.

bound_eps

a numeric scalar defining the critical difference between parameter estimates and the boundaries of the parameter space so that the estimates are considered to be identical to the boundary values, see Details.

se

a logical scalar to control whether standard errors of the estimated nonlinear parameters \widehat{\boldsymbol{\nu}} should be returned (TRUE, default) or variances (FALSE).

correlation

a logical scalar to control whether correlations (TRUE, default) or covariances (FALSE) of the esitmated nonlinear parameters \widehat{\boldsymbol{\nu}} should be returned.

status

a logical scalar to control whether diagnostics should be returned along with the results.

...

additional arguments passed to methods, currently not used.

Details

The function vcov extracts (co-)variances of the nonlinear parameters from the inverse Hessian matrix of the objective function at the solution \widehat{\boldsymbol{\nu}} for mpd and ml estimates, see soilhypfitIntro and Stewart and Sørensen (1981).

vcov checks whether the gradient at the solution is approximately equal to zero and issues a warning if this is not the case. This is controlled by the argument grad_eps which is the tolerable largest modulus of the scaled gradient (= gradient divided by the absolute value of objective function) at the solution. The function control_fit_wrc_hcc selects a default value for grad_eps in the dependence of the chosen optimisation approach (argument settings of control_fit_wrc_hcc).

vcov sets covariances equal to NA if the parameter estimates differ less than bound_eps from the boundaries of the parameter space as defined by param_boundf.

Value

The method vcov returns an object of of class vcov_fit_wrc_hcc, which is a list of covariance matrices of the estimated nonlinear parameters for the soil samples. The attribute status of the matrices qualifies the covariances.

The coef method for class vcov_fit_wrc_hcc extracts the entries of the covariances matrices, optionally computes standard errors and correlation coefficients and returns the results in a dataframe.

Author(s)

Andreas Papritz [e-mail].

References

Stewart, W.E. and Sørensen, J.P. (1981) Bayesian estimation of common parameters from multiresponse data with missing observations. Technometrics, 23, 131–141,
doi:10.1080/00401706.1981.10486255.

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;

soilhypfitmethods for common S3 methods for class fit_wrc_hcc;

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,
  control = control_fit_wrc_hcc(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))