confint.HLfit: Confidence intervals

Description

This function interfaces two procedures: a profile confidence interval procedure implemented for fixed-effects coefficients only; and a parametric bootstrap procedure that can be used to provide confidence interval for any parameter, whether a canonical parameter of the model or any function of one or several such parameters. The bootstrap is performed if the parm argument is a function or a quoted expression or if the boot_args argument is a list. The profile confidence interval is computed if neither of these conditions is true. In that case parm must be the name(s) of some fixed-effect coefficient, and the (p_v approximation of the) profile likelihood ratio for the given parameter is used to define the interval, where the profiling is over all other fitted parameters, including other fixed-effects coefficients, as well as variances of random effects and spatial correlations if these were fitted.

Of related interest, see numInfo which evaluates numerically the information matrix for given sets of canonical model parameters, from which asymptotic confidence intervals can be deduced.

Usage

# S3 method for HLfit
confint(object, parm, level=0.95, verbose=TRUE, 
                          boot_args=NULL, format="default", ...)

Value

The format of the value varies, but in all cases distinguished below, one or more tables are included, as a table attribute, in the format of the stats::confint result, to facilitate consistent extraction of results. By default confint returns invisibly the full values described below, but if format="stats", only the table attribute is returned.

If a profile CI has been computed for a single parameter, a list is returned including the confidence interval as shown by verbose=TRUE, and the fits lowerfit and upperfit giving the profile fits at the confidence bounds. This list bears the table attribute.

If a profile CI has been computed for several parameters, a structured list, named according to the parameter names, of such single-parameter results is returned, and a single table attribute for all parameters is attached to the upper level of the list.

If a bootstrap was performed, for a single parameter the result of the boot.ci call is returned, to which a table attribute is added. This table is now a list of tables for the different bootstrap CI types (default being normal, percent, and basic), each such table in the format of the stats::confint results. For several parameters, a named list of boot.ci results is returned, its names being the parameter names, and the table attribute is attached to the upper level of the list.

The boot.ci return value for each parameter includes the call to boot.ci. This call is typically shown including a long t vector, which makes a bulky display. spaMM hacks the printing to abbreviate long ts.

Arguments

object: An object of class HLfit, as returned by the fitting functions in spaMM. This includes objects also inheriting from class pois4mlogit.
parm: character vector, integer vector, or function, or a quoted expression. If character, the name(s) of parameter(s) to be fitted; if integer, their position in the fixef(object) vector. Valid names are those of this vector. If a function, it must return a (vector of) parameter estimate(s), from a fit object as single argument. If a quoted expression, it must likewise extract parameter estimate(s) from a fit object; this expression must refer to the fitted object as ‘hlfit’ (see Examples).
level: The coverage of the interval.
verbose: whether to print the interval or not. As the function returns its more extensive results invisibly, this printing is the only visible output. In some cases, this argument may also control the verbosity of fits performed by confint to find the bound of the intervals: see verbose for details.
boot_args: NULL or a list of arguments passed to functions spaMM_boot and boot.ci. It must contain element nsim (for spaMM_boot). The type argument of boot.ci can only be given as element ci_type, to avoid conflict with the type argument of spaMM_boot.
format: Only effective non-default value is "stats" to return results in the format of the stats::confint result (see Value).
...: Additional arguments, which may be ignored and have no currently suggested use, apart from any exception described in the Details (notably progress for pois4mlogit fits).

Details

The ... arguments may have an effect (1) in the basic LRT procedure, only when the input object inherits from class pois4mlogit (being a fit by the so-named function). In this case the ... are useful to pass a progress value down to the pois4mlogit function; (2) in the bootstrap procedure, where the ... are ultimately passed to the fitting procedure applied to each bootstrap sample (but there is no suggested use of this feature).

Examples

Run this code


data("wafers")
wfit <- HLfit(y ~X1+(1|batch), family=Gamma(log), data=wafers, method="ML")
confint(wfit,"X1")  # profile CI
if (spaMM.getOption("example_maxtime")>30) {
   
   # bootstrap CI induced by 'boot_args':
   confint(wfit,names(fixef(wfit)), boot_args=list(nsim=99, seed=123)) 
   
   # bootstrap CI induced by 'parm' being a function:
   confint(wfit,parm=function(v) fixef(v), 
           boot_args=list(nb_cores=10, nsim=199, seed=123))
   
   # Same effect if 'parm' is a quoted expression in terms of 'hlfit':
   confint(wfit,parm=quote(fixef(hlfit)), 
           boot_args=list(nb_cores=10, nsim=199, seed=123))
           
   # CI for the variance of the random effect:          
   ci <- confint(wfit,parm=function(fit){get_ranPars(fit)$lambda[1]}, 
        boot_args=list(nb_cores=10, nsim=199, seed=123))
   # The distribution of bootstrap replicates:
   plot(ecdf(ci$call$t))
   # We may be far from ideal condition for accuracy of bootstrap intervals;
   # for variances, a log transformation may sometimes help, but not here.
   
   # Passing arguments to child processes, as documented in help("spaMM_boot"):
   set.seed(123)
   rvar <- runif(nrow(wafers))
   wrfit <- fitme(y ~X1+(1|batch), family=Gamma(log), data=wafers, fixed=list(phi=rvar))
   confint(wrfit, parm = "(Intercept)", boot_args = list(nsim = 100, nb_cores = 2,
           fit_env = list(rvar=rvar)))
   
}