rclusbin               package:missreg               R Documentation

_R_a_n_d_o_m _i_n_t_e_r_c_e_p_t _m_o_d_e_l _f_o_r _c_l_u_s_t_e_r_e_d _b_i_n_a_r_y _d_a_t_a

_D_e_s_c_r_i_p_t_i_o_n:

     Fits random intercept models to clustered binary data with the
     two-phase missingness structure.

_U_s_a_g_e:

     rclusbin(formula, weights = NULL, ClusInd = NULL, IntraClus = NULL, 
              xstrata = NULL, ystrata = NULL, obstype.name = "obstype", 
              data, NMat = NULL, xs.includes = FALSE, MaxInClus = NULL, 
              rmsingletons = FALSE, retrosamp = "proband", gamma = NULL, 
              fit = TRUE, linkname = "logit", start = NULL, Qstart = NULL, 
              sigma = NULL, control = mlefn.control(...), 
              control.inner = mlefn.control.inner(...), ...)

_A_r_g_u_m_e_n_t_s:

 formula: A symbolic description of the model to be fitted.

 weights: An optional vector of weights to be used in the fitting
          process. Should be 'NULL' or a numeric vector. 

           It provides weights at the individual level when there  are
          clusters of size greater than one. When all clusters are of
          size one, it provides weights at cluster=individual level.

 ClusInd: A vector specifying cluster membership. Can be  'NULL' if all
          clusters are of size one.

IntraClus: A vector specifying intra-cluster sequence of individual
          subjects in a cluster. The one with the smallest i.d. is 
          treated as the proband who were originally sampled into a
          study.

 xstrata: Specify names of the stratification variables to be used,
          e.g. '"vname"' or 'c("vname1","vname2",...)'. Strata are
          defined by cross-classifiction of all levels. 

            This function only deals with the situation when clusters
          are  defined within xstrata.

 ystrata: Specify name of the variable defing the Y-strata. Compulsory
          when gamma probabilities are used (see Details for more 
          descriptions).

obstype.name: Name of the variable specifying labels for observations
          by sampling and variable type: '"uncond"', '"retro"',
          '"xonly"', '"y|x"' or '"strata"'. 

    data: A data frame containing all the variables required for
          analysis, including those for 'xstrata', 'ystrata' and 
          'obstype.name'.

    NMat: Population counts in a matrix form with rows and columns 
          corresponding to Y-strata and X-strata respectively.  Should
          not be provided when there is any observation of the type
          '"strata"'.

xs.includes: 'TRUE' if 'weights' specified for obervations labelled as
          "strata" include those observed at the second phase (i.e.
          '"retro"' or '"uncond"' observations).

MaxInClus: A value specifying the maximum number of individuals allowed
          in a cluster. Set to 'NULL' if there is no limit.

rmsingletons: If 'TRUE', remove clusters of size one.

retrosamp: Three restrospective sampling schemes can be applied based
          on the Y-status of all subjects in the same cluster:
          '"proband"', '"allcontrol"' and '"gamma"' (see Details for
          more descriptions). The default is '"proband"'.

   gamma: A vector of length 2 specifying the probabilities that
          individuals  belong to 'Y=1' based on their cluster status
          (see Details for  more descriptions). 

     fit: If 'FALSE', only stratum report will be generated without 
          model fitting.

linkname: A specification for the model link function. Three choices
          are provide: '"logit"', '"probit"' or "cloglog". The default
          is '"logit"'. 

   start: Starting values for the regression parameters. The first
          'p'-coefficients are parameters for X-variables. The last
          parameter is for the random intercept term and normally
          denoted as 'w=log(sigma)'. The program cannot provide
          starting values for all data strctures so will force you to
          use this whenever it is necessary. 

  Qstart: An optional starting matrix for Pr(Ystratum=i|Xstratum=j).
          Can be compulsory if the program cannot produce a valid
          starting value at some situations. 

   sigma: An optional starting value for 'sigma'. The default value
          (when set to 'NULL') is 0.5.

 control: Specify control parameters for the iterations in 'mlefn'
          call.

control.inner: Specify control parameters for inner iterations nested
          within 'mlefn' call. 

     ...: Further arguments passed to or from related function. 

_D_e_t_a_i_l_s:

     This function fits binary regression models with a random
     intercept of the form 'a_i=e^{w*eps_i}' where 'w=log(sigma)' and
     'eps_i' is standard normal for each cluster,  along with a linear
     predictor 'eta_{ij}=x_{ij}^T*beta' for the subject 'j' in the
     'i^th'  cluster. 

      The function can be applied to both prospective and retrospective
     data with   various types of observations collected at different
     two-phase sampling schemes.  Three retrospective samplings are
     considered with the Y-strata defined as: (1) the case-control
     status of the proband only ('"proband"');  (2) the case-cotnrol
     status of all members in the same cluster ('"allcontrol"').  If
     any one of the members are cases, the cluster belongs to
     Y-strata=1 and  otherwise Y-strata=0; (3) the case-control status
     of all members in the same cluster plus the gamma probabilities
     ('"gamma"'). The conditional probability of Y-strata=1 depends  on
     'sum_j{Y_j}=1' (with 'gamma_1' probability) or 'sum_j{Y_j}>1' 
     (with 'gamma_2' probability). Here 'Y_j' indicates case-control
     status  (1 for a case and 0 for a control) of the 'j^{th}'
     individual in a cluster.

_V_a_l_u_e:

missReport: Matrix containing information on deleted records with
          missing observations. 

StrReport: Cross tabulation of counts for different levels of 'obstype'
          and Y-strata by X-strata.

xStrReport: Cross tabulation of counts for 'obstype' by X-strata when
          'obstype="xonly"'.

    xkey: Specify detailed classification for each of the X-strata.

    ykey: Specify the Y variable and its level that the model is
          constructed for.

     fit: 'TRUE' or 'FALSE' as its argument.

   error: The error messages returned by 'mlefn' call. Non-zero values
          indicate an unsuccessful fit.

coefficients: The coefficients matrix with estimates, standard errors,
          z values and associated p-values.

   loglk: Log-likelihood returned from final 'mlefn' call.

   score: Score vector returned from final 'mlefn' call.

     inf: Observed information matrix returned from final 'mlefn' call.

     cov: The asymptotic covariance matrix (inverse of the information
          matrix.

     cor: The asymptotic correlation matrix.

    Qmat: The estimated Pr(Ystratum=i|Xstratum=j) from the last
          iteration.

  gamma0: The estimated 'gamma_1' from the data.

     ...

_N_o_t_e:

     The function 'summary.rclusbin' provides a complete summary of the
     regression results including the Wald tests and a regression
     panel. All related output functions ('print.rclusbin',
     'summary.rclusbin' and 'print.summary.rclusbin' don't have help
     files provided at the moment.

_A_u_t_h_o_r(_s):

     Chris Wild, Yannan Jiang

_R_e_f_e_r_e_n_c_e_s:

     Description of the 'missreg' Library, Wild and Jiang, 2007.

_S_e_e _A_l_s_o:

     'bin2stg'; 'mlefn'

_E_x_a_m_p_l_e_s:

     ##### PROSPECTIVE #####
     data(leprosypros)
     leprosypros$age.trans <- 100*(leprosypros$age+7.5)^(-2)
     leprosypros$obstype <- rep("uncond", dim(leprosypros)[1])
     z1 <- rclusbin(leprosy~age.trans + scar, weights=counts, data=leprosypros, 
                    linkname="logit", sigma=2.5)
     summary(z1)

     ##### RETROSPECTIVE #####
     data(brainpairs)
     brainpairs$obstype <- rep("retro", dim(brainpairs)[1])
     z2 <- rclusbin(bt ~ ep + ca, ClusInd=id, IntraClus=relid, data=brainpairs)
     summary(z2)

     data(rdat00)
     z3 <- rclusbin(y~x, ClusInd=cluster, data=rdat00, retrosamp="allcontrol")
     summary(z3)

