bivbin2stg              package:missreg              R Documentation

_B_i_v_a_r_i_a_t_e _b_i_n_a_r_y _r_e_g_r_e_s_s_i_o_n _f_o_r _t_w_o-_p_h_a_s_e _s_a_m_p_l_e_d _d_a_t_a

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

     Fits bivariate binary regression models to data with two
     correlated binary Y-variables and two-phase missingness structure.

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

     bivbin2stg(formula1, formula2, formula3, weights = NULL, 
                xstrata = NULL, obstype.name = "obstype", data, 
                fit = TRUE, xs.includes = FALSE, y1samp = TRUE, 
                method = "palmgren", start = NULL, Qstart = NULL, 
                off.set = NULL, control = mlefn.control(...), 
                control.inner = mlefn.control.inner(...), ...)

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

formula1: A symbolic description of the model to be fitted for Y1,  the
          binary response defining the case-control status of subjects.
          When the 'spml2' method is considered, it provides model
          formula for Y1|Y2 where Y2 is another binary response of
          interest  normally observed at the second phase.

formula2: A symbolic description of the model to be fitted for Y2,  the
          second binary response of interest correlated with Y1.

formula3: A symbolic description of the model to be fitted quantifying 
          the association between Y1 and Y2. '~1' will fit a constant
          model. This model is not required when the 'spml2' method is
          considered.

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

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

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

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

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

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

  y1samp: 'TRUE' if Y-strata are defined by the case-control
          information of Y1  in the population.   'FALSE' if Y-strata
          are defined by both Y1 and Y2 with either  "all controls"
          (Y1=0 and Y2=0) or not (Y1=1 or Y2=1).

  method: Four methods are implemented: '"palmgren"', '"bahadur"', 
          '"copula"' and '"spml2"' (see Details for more descriptions).
           Note that the last method is not available when
          'y1samp=FALSE'.

   start: Starting values for the regression parameters in Y1-model,
          Y2-model  and the association model when applicable.

  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.

 off.set: Specify an 'a priori' known component to be included in the
          predictors. Should be 'NULL' or a numeric vector.

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

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

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

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

     This function fits bivariate binary regresison to two correlated
     binary outcomes Y1 and  Y2 using several models with various types
     observations collected at differnt two-phase sampling schemes.  

      The joint distribution of Y1 and Y2 given X can be modelled using
     the marginal  distributions of Pr(Y1|X) and Pr(Y2|X) along with an
     association model between Y1 and Y2. Currently implemented models
     for this approach include the Palmgren, Bahadur  and Copula
     models. When we are only interested in Pr(Y2|X), another
     semiparametric  approach (called 'spml2' method) can be used in
     terms of a conditional factorisation  Pr(Y1|Y2, X)*Pr(Y2|X) both
     treated parametrically.  

      More detailed descriptions of this function can be found in
     "Description of the  'missreg' Library" (Wild and Jiang).

_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-values by X-strata.

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

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

    ykey: Specify the Y-variables that the model is being 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. Will report separately for
          each marginal model  used.

   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.

fitted.Y2: The fitted values of Y2 obtained by transforming the linear
          predictors by the inverse of the link function. Note that all
          methods we have implemented  evaluate Pr(Y2|X) which is
          normally the model of interest.

     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.

     ...

_N_o_t_e:

     The function 'summary.bivbin2stg' provides a complete summary of
     the regression results including the Wald tests and a regression
     model. All related output functions ('print.bivbin2stg',
     'summary.bivbin2stg' and 'print.summary.bivbin2stg' 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'

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

     ### SAMPLING ON CASE-CONTROL INFORMATION OF Y1 ONLY ###
     data(cotdeath)
     z1 <- bivbin2stg(y1~x, y2~x, ~x, weights=wts, data=cotdeath, 
                       xs.includes=TRUE, method="palmgren")
     summary(z1)

     z2 <- bivbin2stg(y1~x, y2~x, ~x, weights=wts, data=cotdeath, 
                       xs.includes=TRUE, method="bahadur")
     summary(z2)
      
     z3 <- bivbin2stg(y1~x, y2~x, ~x, weights=wts, data=cotdeath, 
                       xs.includes=TRUE, method="copula")
     summary(z3)

     z4 <- bivbin2stg(y1~x*y2, y2~x, weights=wts, data=cotdeath, 
                       xs.includes=TRUE, method="spml2")
     summary(z4)

     data(infarct)
     z5 <- bivbin2stg(sgagp~ethnic+smoked+hyper+mumwt+mumwtc2+agepreg,
                     anyinf~smoked+hyper+age1st, ~age1st, weights=count,
                     xstrata=c("sex", "gest"), obstype.name="instudy",
                     data=infarct, xs.includes=TRUE, method="palmgren")
     summary(z5)

     ### SAMPLING ON ALL CONTROLS (Y1=0 AND Y2=0) OR NOT ###
     data(dat00)
     z6 <- bivbin2stg(y1~x, y2~x, ~x, weights=wts, data=dat00, y1samp=FALSE, 
                      xstrata="v", xs.includes=FALSE, method="palmgren")
     summary(z6)

