Movatterモバイル変換

geex: M-estimation API

Description

geex provides an extensible API for estimating parameters and their covariancefrom a set of estimating functions (M-estimation). M-estimation theory has along history [see reference in the M-estimation bibliography:https://bsaul.github.io/geex/articles/articles/mestimation_bib.html.For an excellent introduction, see the primer by L.A. Stefanski and D.D. Boos,"The Calculus of M-estimation" (The American Statistician (2002), 56(1), 29-38)(http://www.jstor.org/stable/3087324).

Details

M-estimation encompasses a broad swath of statistical estimators and ideas including:

• the empirical "sandwich" variance estimator

• generalized estimating equations (GEE)

• many maximum likelihood estimators

• robust regression

• and many more

geex can implement all of these using a user-defined estimating function.

To learn more about geex, see the package vignettes:browseVignettes(package = 'geex').

Goals

If you can specify a set of unbiased estimating equations, geex does the rest.The goals of geex are simply:

• To minimize the translational distance between a set of estimatingfunctions and R code;

• To return numerically accurate point and covariance estimates froma set of unbiased estimating functions.

geex does not, by itself, necessarily aim to be fast nor precise. Such goalsare left to the user to implement or confirm.

Author(s)

Maintainer: Bradley Saulbradleysaul@gmail.com

Other contributors:

• Brian Barkley [contributor]

References

Saul, Bradley C., and Michael G. Hudgens. (2020)."The Calculus of M-estimation in R with geex." Journal of Statistical Software 92(2), 1-15.doi:10.18637/jss.v092.i02.

See Also

Useful links:

• https://github.com/bsaul/geex

• https://bsaul.github.io/geex/

• Report bugs athttps://github.com/bsaul/geex/issues

approx_control S4 class

Description

EXPERIMENTAL. See example 7 invignette("01_additional_examples", package = "geex")for usage.

Slots

.FUN

a function which approximates anestFUN.

.options

a list of options passed to.FUN.

basic_control S4 class

Description

A general class for defining afunction, and the options passed to thefunction

Slots

.FUN

a function

.options

a list of options passed to.FUN

See Also

root_control-class,deriv_control-classapprox_control-class

Gets the parameter estimates from a geex object

Description

Gets the parameter estimates from a geex object

Usage

## S4 method for signature 'geex'coef(object)## S4 method for signature 'geex_summary'coef(object)

Arguments

Examples

ex_eeFUN <- function(data){ function(theta){   with(data,    c(Y1 - theta[1],     (Y1 - theta[1])^2 - theta[2] ))}}results <- m_estimate( estFUN = ex_eeFUN, data  = geexex, root_control = setup_root_control(start = c(1,1)))coef(results)

Compute the sum of a list of matrices to sum

Description

Compute the sum of a list of matrices to sum

Usage

compute_pairwise_sum_of_list(.l, .w = NULL, .wFUN = NULL, ...)

Arguments

Compute empirical sandwich covariate estimator

Description

Computes\Sigma = A^{-1} B (A^{-1})^T withprovidedA andB matrices.

Usage

compute_sigma(A, B, solver = solve)

Arguments

Value

thematrixAinv %*% B %*% t(Ainv)

Examples

A <- diag(2, nrow = 2, ncol = 2)B <- matrix(4, nrow = 2, ncol = 2)compute_sigma(A = A, B = B)

Compute the sum of a list of matrices to sum

Description

Compute the sum of a list of matrices to sum

Usage

compute_sum_of_list(.l, .w = numeric(0))

Arguments

Correct sandwich components

Description

Modifies the matrices in asandwich_components objectusing the function and options in acorrect_control object.The functioncorrection is a utility for creatingcorrect_control objects.

Usage

correct_by(.components, .correct_control)

Arguments

Details

See the finite sample corrections vignette for further examples.

Value

the result of.FUN in.correct_control.

See Also

fay_bias_correction andfay_df_correctionfor corrections provided bygeex

Examples

myee <- function(data){   function(theta){    c(data$Y1 - theta[1],     (data$Y1 - theta[1])^2 - theta[2])   } }mybasis <- create_basis(   estFUN = myee,   data   = geexex)mats <- estimate_sandwich_matrices(mybasis, .theta = c(5.04, 10.04))correct_by(mats,   .correct_control =  correction(fay_bias_correction, b = .75))

correct_control S4 class

Description

correct_control S4 class

Slots

.FUN

a function which "corrects" asandwich_componentsobject. Usually a small-sample correction

.options

a list of options passed to.FUN.

Creates a correct_control object

Description

Creates a correct_control object

Usage

correction(FUN, ...)

Arguments

Value

acorrect_control object

Examples

correction(FUN = fay_bias_correction, b = 0.75)

Creates a function that sums over psi functions

Description

From a list of\psi(O_i, \theta) for i = 1, ..., m,createsG_m = \sum_i \psi(O_i, \theta),calledGFUN. Here,\psi(O_i, \theta) is the*inner* part of anestFUN, in that the data is fixed andG_mis a function of\theta).

Usage

create_GFUN(object, ...)## S4 method for signature 'm_estimation_basis'create_GFUN(object)

Arguments

Value

a function

Examples

myee <- function(data){   function(theta){    c(data$Y1 - theta[1],     (data$Y1 - theta[1])^2 - theta[2])   } }mybasis <- create_basis(   estFUN = myee,   data   = geexex)f <- grab_GFUN(create_GFUN(mybasis))# Evaluate GFUN at mean and variance: should be close to zeron <- nrow(geexex)f(c(mean(geexex$Y1), var(geexex$Y1) * (n - 1)/n))

Creates an m_estimation_basis object

Description

Creates an m_estimation_basis object

Usage

create_basis(estFUN, data, units, outer_args, inner_args)

Arguments

Details

Eitherdata orsplit_data must be provided

Value

am_estimation_basis

Examples

myee <- function(data){   function(theta){    c(data$Y1 - theta[1],     (data$Y1 - theta[1])^2 - theta[2])   } }mybasis <- create_basis(   estFUN = myee,   data   = geexex)

Creates list of psi functions

Description

Creates the estimating function (\psi(O_i, \theta))for each unit. That is, this function evaluates the outer function inestFUN for each independent unit and a returns the inner function inestFUN.

Usage

create_psiFUN_list(object, ...)## S4 method for signature 'm_estimation_basis'create_psiFUN_list(object)

Arguments

Value

theobject with the.psiFUN_list slot populated.

Examples

myee <- function(data){   function(theta){    c(data$Y1 - theta[1],     (data$Y1 - theta[1])^2 - theta[2])   } }mybasis <- create_basis(   estFUN = myee,   data   = geexex)psi_list <- grab_psiFUN_list(create_psiFUN_list(mybasis))# A list of functionshead(psi_list)

deriv_control S4 class

Description

deriv_control S4 class

Slots

.FUN

a function which computes a numerical derivation. This functionsfirst argument must the function on which the derivative is being compute.Defaults tojacobian.

.options

a list of options passed to.FUN. Defaults tolist(method = 'Richardson')

Diagnose roots of estimating equations

Description

Computes the value of

G_m = sum_i psi(O_i, \hat{\theta})

, i.e., the estimatingequations attheta. Used to verify thatG_m = 0 (or close to 0).

Usage

diagnose_roots(GFUN, theta)

Arguments

Value

a numeric vector

Examples

myee <- function(data){   function(theta){    c(data$Y1 - theta[1],     (data$Y1 - theta[1])^2 - theta[2])   } }mest <- m_estimate(   estFUN = myee,   data   = geexex,   root_control = setup_root_control(start = c(1, 1)))f <- grab_GFUN(mest@basis)# Should be close to zerodiagnose_roots(GFUN = f, theta = roots(mest))

Estimate roots for a set of estimating equations

Description

Using therootFUN specified by the user (defaults tomultiroot),this function estimates the roots of the equations:

G_m = sum_i psi(O_i, \hat{\theta}) = 0

Usage

estimate_GFUN_roots(.basis)

Arguments

Details

This is primilary an internal function used withinm_estimate,but it is exported for use in debugging and development.

For an example of how to use a differentrootFUN,see the root solver vignette,vignette('geex_root_solvers', package = 'geex').

Value

the output of therootFUN function

Examples

myee <- function(data){  function(theta){    c(data$Y1 - theta[1],     (data$Y1 - theta[1])^2 - theta[2])   } }# Start with a basic basismybasis <- create_basis(  estFUN = myee,  data   = geexex)# Add a control for the root solvermycontrol <- new('geex_control', .root = setup_root_control(start = c(1, 1)))mybasis@.control <- mycontrol# Now estimate roots of GFUNroots <- estimate_GFUN_roots(mybasis)roots

Estimate component matrices of the empirical sandwich covariance estimator

Description

For a given set of estimating equations computes the 'meat' (B_min Stefanski and Boos notation) and 'bread' (A_m in Stefanski andBoos notation) matrices necessary to compute the covariance matrix.

Usage

estimate_sandwich_matrices(.basis, .theta)

Arguments

Details

For a set of estimating equations (\sum_i \psi(O_i, \theta) = 0),this function computes:

A_i = \partial \psi(O_i, \theta)/\partial \theta

A = \sum_i A_i

B_i = \psi(O_i, \theta)\psi(O_i, \theta)^T

B = \sum_i B_i

where all of the above are evaluated at\hat{\theta}. The partial derivatives inA_inumerically approximated by the function defined inderiv_control.

Note thatA = \sum_i A_i and not\sum_i A_i/m, and the same forB.

Value

asandwich_components object

References

Stefanski, L. A., & Boos, D. D. (2002). The calculus of m-estimation. The American Statistician, 56(1), 29-38.

Examples

myee <- function(data){  function(theta){    c(data$Y1 - theta[1],     (data$Y1 - theta[1])^2 - theta[2])   } }# Start with a basic basismybasis <- create_basis(  estFUN = myee,  data   = geexex)# Now estimate sandwich matricesestimate_sandwich_matrices( mybasis, c(mean(geexex$Y1), var(geexex$Y1)))

estimating_function S4 class

Description

estimating_function S4 class

Slots

.estFUN

the estimating function.

.outer_args

a namedlist of arguments passed to the outerfunction of.estFUN. Should *not* include thedata argument.

.inner_args

a namedlist of arguments passed to the innerfunction of.estFUN. Should *not* include thetheta argument.

Correct sandwich variance estimator byFay's bias correction

Description

Computes the bias corrected sandwich covariance matrix described in Fay andGraubard (2001). Seevignette("05_finite_sample_corrections", package = "geex")for further information.

Usage

fay_bias_correction(components, b = 0.75)

Arguments

Value

a corrected covariance matrix

References

Fay, M. P., & Graubard, B. I. (2001). Small-Sample adjustments forWald-type tests using sandwich estimators. Biometrics, 57(4), 1198-1206

Examples

# This example demonstrates usage of the corrections, not a meaningful applicationmyee <- function(data){ function(theta){   c(data$Y1 - theta[1],   (data$Y1 - theta[1])^2 - theta[2])  }}results <- m_estimate(   estFUN = myee,   data = geexex,   root_control = setup_root_control(start = c(1,1)),   corrections  = list(     bias_correction_.1 = correction(fay_bias_correction, b = .1),     bias_correction_.3 = correction(fay_bias_correction, b = .3))   )get_corrections(results)

Correct sandwich variance inference by Fay's degrees of freedom correction

Description

Computes the degrees of freedom correction described in Fay andGraubard (2001). Seevignette("05_finite_sample_corrections", package = "geex")for further information.

Usage

fay_df_correction(components, b = 0.75, L, version)

Arguments

Value

a scalar corresponding to the estimated degrees of freedom

References

Fay, M. P., & Graubard, B. I. (2001). Small-Sample adjustments forWald-type tests using sandwich estimators. Biometrics, 57(4), 1198-1206

Examples

# This example demonstrates usage of the corrections, not a meaningful applicationmyee <- function(data){ function(theta){   c(data$Y1 - theta[1],   (data$Y1 - theta[1])^2 - theta[2])  }}results <- m_estimate(   estFUN = myee,   data = geexex,   root_control = setup_root_control(start = c(1,1)),   corrections  = list(     df_correction1 = correction(fay_df_correction,                        b = .75, L = c(0, 1), version = 1 ),     df_correction2 = correction(fay_df_correction,                        b = .75, L = c(0, 1), version = 2 ))   )get_corrections(results)

geex S4 class

Description

geex S4 class

Slots

call

them_estimate call

basis

am_estimation_basis object

rootFUN_results

the results of call to the root finding algorithm function

sandwich_components

asandwich_components object

GFUN

thefunction of which the roots are computed.

corrections

alist of correction performed onsandwich_components

estimates

anumeric vector of parameter estimates

vcov

the empirical sandwich variancematrix

geex_control S4 class

Description

An object which control all thebasic_control objectsnecessary to perform M-estimation

Slots

.approx

anapprox_control object

.root

aroot_control object

.deriv

aderiv_control object

geex summary object

Description

geex summary object

Slots

estFUN

aestimating-function

outer_args

thelist arguments passed to them_estimate call

inner_args

thelist arguments passed to them_estimate call

data

thedata.frame passed to them_estimate call

weights

theweights passed to them_estimate call

nobs

the number of observational units used to compute the M-estimator

units

the name of the variable identifying the observational units

corrections

alist of correction performed onsandwich_components

estimates

anumeric vector of parameter estimates

vcov

the empirical sandwich variancematrix

Dataset used to illustrate Stefanski and Boos examples.

Description

The data used to illustrate examples 1-9 of Stefanski and Boos (2002).

Format

a dataset with 9 variables and 100 observations

• Y1 rnorm(mean = 5, sd = 4)

• Y2 rnorm(mean = 2, sd = 1)

• X1 rgamma(shape =5)

• Y3 2 + 3*X1 + 1*rnorm(0, 1)

• W1 X1 + 0.25 * rnorm(0, 1)

• Z1 2 + 1.5*X1 + 1*rnorm(0, 1)

• X2 0 for first 50 observation, 1 for rest

• Y4 0.1 + 0.1*X1 + 0.5*X2 + rnorm(0, 1)

• Y5 rbinom(prob = plogis(0.1 + 0.1*X1 + 0.5*X2))

References

Stefanski, L. A., & Boos, D. D. (2002). The calculus of m-estimation. The American Statistician, 56(1), 29-38.

Gets the corrections from a geex object

Description

Gets the corrections from a geex object

Usage

get_corrections(object, ...)## S4 method for signature 'geex'get_corrections(object)## S4 method for signature 'geex_summary'get_corrections(object)

Arguments

Examples

myee <- function(data){ function(theta){   c(data$Y1 - theta[1],   (data$Y1 - theta[1])^2 - theta[2])  }}results <- m_estimate(   estFUN = myee,   data = geexex,   root_control = setup_root_control(start = c(1,1)),   corrections  = list(     bias_correction_.1 = correction(fay_bias_correction, b = .1),     bias_correction_.3 = correction(fay_bias_correction, b = .3))   )get_corrections(results)

Grab something from an object

Description

Grab something from an object

Usage

grab(from, what, ...)

Arguments

Value

the value returns depends on the argumentwhat.

See Also

grab_response,grab_design_matrix,grab_response_formula,grab_fixed_formula,grab_design_levels

Gets the .psi_list slot in a m_estimation_basis

Description

Gets the .psi_list slot in a m_estimation_basis

Usage

grab_GFUN(object)## S4 method for signature 'm_estimation_basis'grab_GFUN(object)## S4 method for signature 'geex'grab_GFUN(object)

Arguments

Grabs the .A (bread matrix) slot

Description

Grabs the .A (bread matrix) slot

Usage

grab_bread(object)## S4 method for signature 'sandwich_components'grab_bread(object)

Arguments

Examples

myee <- function(data){ function(theta){   c(data$Y1 - theta[1],   (data$Y1 - theta[1])^2 - theta[2])  }}results <- m_estimate(   estFUN = myee,   data = geexex,   root_control = setup_root_control(start = c(1,1)))grab_bread(results@sandwich_components)

Gets the .A_i (list of bread matrices) slot

Description

Gets the .A_i (list of bread matrices) slot

Usage

grab_bread_list(object)## S4 method for signature 'sandwich_components'grab_bread_list(object)

Arguments

Examples

myee <- function(data){ function(theta){   c(data$Y1 - theta[1],   (data$Y1 - theta[1])^2 - theta[2])  }}results <- m_estimate(   estFUN = myee,   data = geexex,   root_control = setup_root_control(start = c(1,1)))head(grab_bread_list(results@sandwich_components))

Grab a list of the levels of factor variables in a model.

Description

Useful when splitting data later, used withgrab_design_matrixor especially when callinggrab_psiFUN from within an eeFun.

Usage

grab_design_levels(model)

Arguments

Value

A named list of character vectors that provides the fentire set oflevels that each factor predictor inmodel will take on. This ishopefully identical to what thexlev argument tolink[stats]{model.frame} desires. Whenmodel has no factorsas predictors, then an empty list is returned.

Examples

## Not run:   geex::grab_design_matrix(    data = data,    rhs_formula = geex::grab_fixed_formula(model),    xlev = geex::grab_design_levels(model)  )  ## Below is helpful within an eeFun.  geex::grab_psiFUN(    data = data,## Especially when this is a subset of the data    rhs_formula = geex::grab_fixed_formula(model),    xlev = geex::grab_design_levels(model)  )## End(Not run)

Grab a matrix of fixed effects from a model object

Description

Grab a matrix of fixed effects from a model object

Usage

grab_design_matrix(data, rhs_formula, ...)

Arguments

Value

amodel.matrix

Examples

# Create a "desigm" matrix for the first ten rows of iris datafit <- lm(Sepal.Width ~ Petal.Width, data = iris)grab_design_matrix(  data = iris[1:10, ],  grab_fixed_formula(fit))

Gets the .ee_i (observed estimating function) slot

Description

Gets the .ee_i (observed estimating function) slot

Usage

grab_ee_list(object)

Arguments

Examples

myee <- function(data){ function(theta){   c(data$Y1 - theta[1],   (data$Y1 - theta[1])^2 - theta[2])  }}results <- m_estimate(   estFUN = myee,   data = geexex,   root_control = setup_root_control(start = c(1,1)))grab_ee_list(results@sandwich_components)

Grab estimating functions from a model object

Description

Grab estimating functions from a model object

Usage

grab_estFUN(object)## S4 method for signature 'estimating_function'grab_estFUN(object)

Arguments

Grab the RHS formula from a model object

Description

Grab the RHS formula from a model object

Usage

grab_fixed_formula(model)

Arguments

Value

the right-hand side of a model'sformula object

Examples

fit <- lm(Sepal.Width ~ Petal.Width, data = iris)grab_fixed_formula(fit)

Gets the .B (meat matrix) slot

Description

Gets the .B (meat matrix) slot

Usage

grab_meat(object)## S4 method for signature 'sandwich_components'grab_meat(object)

Arguments

Examples

myee <- function(data){ function(theta){   c(data$Y1 - theta[1],   (data$Y1 - theta[1])^2 - theta[2])  }}results <- m_estimate(   estFUN = myee,   data = geexex,   root_control = setup_root_control(start = c(1,1)))grab_meat_list(results@sandwich_components)

Gets the .B_i (list of bread matrices) slot

Description

Gets the .B_i (list of bread matrices) slot

Usage

grab_meat_list(object)## S4 method for signature 'sandwich_components'grab_meat_list(object)## S4 method for signature 'sandwich_components'grab_ee_list(object)

Arguments

Examples

myee <- function(data){ function(theta){   c(data$Y1 - theta[1],   (data$Y1 - theta[1])^2 - theta[2])  }}results <- m_estimate(   estFUN = myee,   data = geexex,   root_control = setup_root_control(start = c(1,1)))head(grab_meat_list(results@sandwich_components))

Grab estimating functions from a model object

Description

Grab estimating functions from a model object

Usage

grab_psiFUN(object, ...)## S3 method for class 'glm'grab_psiFUN(object, data, ...)## S3 method for class 'geeglm'grab_psiFUN(object, data, ...)## S3 method for class 'merMod'grab_psiFUN(object, data, numderiv_opts = NULL, ...)

Arguments

Value

a function corresponding to the estimating equations of a model

Methods (by class)

• grab_psiFUN(glm): Create estimating equation function from aglm object

• grab_psiFUN(geeglm): Create estimating equation function from ageeglm object

• grab_psiFUN(merMod): Create estimating equation function from amerMod object

Examples

## Not run: library(geepack)library(lme4)data('ohio')glmfit  <- glm(resp ~ age, data = ohio,               family = binomial(link = "logit"))geefit  <- geeglm(resp ~ age, data = ohio, id = id,                  family = binomial(link = "logit"))glmmfit <- glmer(resp ~ age + (1|id), data = ohio,                 family = binomial(link = "logit"))example_ee <- function(data, model){ f <- grab_psiFUN(model, data) function(theta){  f(theta) }}m_estimate(  estFUN = example_ee,  data = ohio,  compute_roots = FALSE,  units = 'id',  roots = coef(glmfit),  outer_args = list(model = glmfit))m_estimate(  estFUN = example_ee,  data = ohio,  compute_roots = FALSE,  units = 'id',  roots = coef(geefit),  outer_args = list(model = geefit))m_estimate(  estFUN = example_ee,  data = ohio,  compute_roots = FALSE,  units = 'id',  roots = unlist(getME(glmmfit, c('beta', 'theta'))),  outer_args = list(model = glmmfit)) ## End(Not run)

Gets the .psi_list slot in a m_estimation_basis

Description

Gets the .psi_list slot in a m_estimation_basis

Usage

grab_psiFUN_list(object)## S4 method for signature 'm_estimation_basis'grab_psiFUN_list(object)## S4 method for signature 'geex'grab_psiFUN_list(object)

Arguments

Grab a vector of responses from a model object

Description

Grab a vector of responses from a model object

Usage

grab_response(data, formula)

Arguments

Value

amodel.response

Examples

# Grab vector of responses for the first ten rows of iris datafit <- lm(Sepal.Width ~ Petal.Width, data = iris)grab_response(  data = iris[1:10, ],  formula(fit))

Grab the LHS formula from a model object

Description

Grab the LHS formula from a model object

Usage

grab_response_formula(model)

Arguments

Value

the left-hand side of a model'sformula object

Examples

fit <- lm(Sepal.Width ~ Petal.Width, data = iris)grab_response_formula(fit)

Estimate parameters and their covariance from a set of estimating equations

Description

M-estimation theory provides a framework for asympotic properties of estimatorsthat are solutions to estimating equations. Many R packages implement specificapplications of estimating equations.geex aims to be provide a more generalframework that any modelling method can use to compute point and variance estimatesfor parameters that are solutions to estimating equations of the form:

\sum_i \psi(O_i, \hat{\theta}) = 0

Usage

m_estimate(  estFUN,  data,  units = character(0),  weights = numeric(0),  outer_args = list(),  inner_args = list(),  roots = NULL,  compute_roots = TRUE,  compute_vcov = TRUE,  Asolver = solve,  corrections,  deriv_control,  root_control,  approx_control)

Arguments

Details

The basic idea ofgeex is for the analyst to provide at leasttwo items:

• data

• estFUN: (the\psi function), a function that takes unit-leveldata and returns a function in terms of parameters (\theta)

With theestFUN,geex computes the roots of the estimating equationsand/or the empirical sandwich variance estimator.

The root finding algorithm defaults tomultiroot toestimate roots though the solver algorithm can be specified in therootFUNargument. Starting values formultiroot are passed via theroot_control argument. Seevignette("v03_root_solvers", package = "geex")for information on customizing the root solver function.

To compute only the covariance matrix, setcompute_roots = FALSE and passestimates of\theta via theroots argument.

M-estimation is often used for clustered data, and a variable by which to splitthe data.frame into independent units is specified by theunits argument.This argument defaults toNULL, in which case the number of units equalsthe number of rows in the data.frame.

For information on the finite-sample corrections, refer to the finite samplecorrection API vignette:vignette("v05_finite_sample_corrections", package = "geex")

Value

ageex object

Writing an estFUN

Description

AnestFUN is a function representing\psi.geex worksby breaking\psi into two parts:

• the "outer" part of theestFUN which manipulatesdata andouter_args and returns an

• "inner" function oftheta andinner_args. Internally, this"inner" function is calledpsiFUN.

In pseudo-code this looks like:

function(data, <<outer_args>>){  O <- manipulate(data, <<outer_args>>)  function(theta, <<inner_args>>){    map(O, to = theta, and = <<inner_args>>)  }}

See the examples below or the package vignettes to see anestFUNin action.

Importantly, thedata used in anestFUN is *unit* level data,which may be single rows in a data.frame or block of rows for clustered data.

Additional arguments

Additional arguments may be passed to both the inner and outer function of theestFUN. Elements in anouter_args list are passed to the outerfunction; any elements of theinner_args list are passed to the innerfunction. For an example, see the finite sample correction vignette [vignette("v05_finite_sample_corrections", package = "geex")].

Setting up root_control

To estimate roots of the estimating functions,geex uses therootSolvemultiroot function by default, which requires startingvalues. Theroot_control argument expects aroot_controlobject, which the utility functionsetup_root_control aids increating. For example,setup_root_control(start = 4) creates aroot_control setting the starting value to 4. In general,the dimension ofstart must the same astheta in the innerestFUN.

Using weights

In some situations, use of weights can massively speed computations. Refertovignette("v04_weights", package = "geex") for an example.

References

Stefanski, L. A., & Boos, D. D. (2002). The calculus of M-estimation.The American Statistician, 56(1), 29-38.

Examples

# Estimate the mean and variance of Y1 in the geexex datasetex_eeFUN <- function(data){ function(theta){   with(data,    c(Y1 - theta[1],     (Y1 - theta[1])^2 - theta[2] ))}}m_estimate( estFUN = ex_eeFUN, data  = geexex, root_control = setup_root_control(start = c(1,1)))# compare to the mean() and variance() functionsmean(geexex$Y1)n <- nrow(geexex)var(geexex$Y1) * (n - 1)/n# A simple linear model for regressing X1 and X2 on Y4lm_eefun <- function(data){ X <- cbind(1, data$X1, data$X2) Y <- data$Y4 function(theta){    t(X) %*% (Y - X %*% theta)   } }m_estimate( estFUN = lm_eefun, data  = geexex, root_control = setup_root_control(start = c(0, 0, 0)))# Compare to lm() resultssummary(lm(Y4 ~ X1 + X2, data = geexex))

m_estimation_basis S4 class

Description

m_estimation_basis S4 class

Slots

.data

the analysis data.frame

.units

an (optional) character string identifying the variable in.data which splits the data into indepedent units

.weights

a numeric vector of weights used in weighting the estimatingfunctions

.psiFUN_list

a list ofpsiFUNs created bycreate_psiFUN_list

.GFUN

a function created bycreate_GFUN

.control

ageex_control object

Extract the number observations

Description

Extract the number observations

Usage

## S4 method for signature 'geex'nobs(object)## S4 method for signature 'geex_summary'nobs(object)

Arguments

Examples

library(geepack)data('ohio')glmfit  <- glm(resp ~ age, data = ohio,              family = binomial(link = "logit"))example_ee <- function(data, model){  f <- grab_psiFUN(model, data)  function(theta){    f(theta)  }}z  <- m_estimate(  estFUN = example_ee,  data = ohio,  compute_roots = FALSE,  units = 'id',  roots = coef(glmfit),  outer_args = list(model = glmfit))nobs(z)

root_control S4 class

Description

root_control S4 class

Slots

.FUN

a root finding function whose first argument must be namedf.

.options

a list of options passed to.FUN.

.object_name

a character string identifying the object containing theroots in the output of.FUN.

Gets the parameter estimates matrix from a geex object

Description

Gets the parameter estimates matrix from a geex object

Usage

roots(object, ...)## S4 method for signature 'geex'roots(object)## S4 method for signature 'geex_summary'roots(object)

Arguments

Examples

ex_eeFUN <- function(data){ function(theta){   with(data,    c(Y1 - theta[1],     (Y1 - theta[1])^2 - theta[2] ))}}results <- m_estimate( estFUN = ex_eeFUN, data  = geexex, root_control = setup_root_control(start = c(1,1)))roots(results)

sandwich_components S4 class

Description

sandwich_components S4 class

Slots

.A

the "bread" matrix

.A_i

a list of "bread" matrices per unit

.B

the "meat" matrix

.B_i

a list of "meat" matrices per unit

.ee_i

a list of observed estimating function values per unit

Setup an approx_control object

Description

Setup an approx_control object

Usage

setup_approx_control(FUN, ...)

Arguments

Value

aapprox_control object

Examples

# For usage, see example 7 invignette("01_additional_examples", package = "geex")

Setup a basic_control object

Description

Setup a basic_control object

Usage

setup_control(type, FUN, ...)

Arguments

Value

abasic_control object

See Also

setup_root_control,setup_deriv_control,setup_approx_control

Setup a deriv_control object

Description

Setup a deriv_control object

Usage

setup_deriv_control(FUN, ...)

Arguments

Value

aderiv_control object

Examples

setup_deriv_control() # defaultsetup_deriv_control(method = "simple") # will speed up computations

Setup a root_control object

Description

Setup a root_control object

Usage

setup_root_control(FUN, roots_name, ...)

Arguments

Value

aroot_control object

Examples

# Setup the defaultsetup_root_control(start = c(3, 5, 6))# Also setup the defaultsetup_root_control(FUN = rootSolve::multiroot,                   start = c(3, 5, 6))# Or use uniroot()setup_root_control(FUN = stats::uniroot,                   interval = c(0, 1))

Show (print) the S4 geex classes

Description

m_estimation_basis, orgeex object

Usage

show(object)## S4 method for signature 'sandwich_components'show(object)## S4 method for signature 'm_estimation_basis'show(object)## S4 method for signature 'geex'show(object)## S4 method for signature 'geex_summary'show(object)

Arguments

Object Summaries

Description

Object Summaries

Usage

## S4 method for signature 'geex'summary(object, keep_data = TRUE, keep_args = TRUE)

Arguments

Examples

library(geepack)data('ohio')glmfit  <- glm(resp ~ age, data = ohio,              family = binomial(link = "logit"))example_ee <- function(data, model){  f <- grab_psiFUN(model, data)  function(theta){    f(theta)  }}z  <- m_estimate(estFUN = example_ee,data = ohio,compute_roots = FALSE,units = 'id',roots = coef(glmfit),outer_args = list(model = glmfit))object.size(z)object.size(summary(z))object.size(summary(z, keep_data = FALSE))object.size(summary(z, keep_data = FALSE, keep_args = FALSE))

Gets the variance-covariance matrix from a geex object

Description

Gets the variance-covariance matrix from a geex object

Usage

## S4 method for signature 'geex'vcov(object)## S4 method for signature 'geex_summary'vcov(object)

Arguments

Examples

ex_eeFUN <- function(data){ function(theta){   with(data,    c(Y1 - theta[1],     (Y1 - theta[1])^2 - theta[2] ))}}results <- m_estimate( estFUN = ex_eeFUN, data  = geexex, root_control = setup_root_control(start = c(1,1)))vcov(results)

Extract Model weights

Description

Extract Model weights

Usage

## S4 method for signature 'geex'weights(object)## S4 method for signature 'geex_summary'weights(object)

Arguments