locsc2stg              package:missreg              R Documentation

_L_i_n_e_a_r _r_e_g_r_e_s_s_i_o_n _w_i_t_h _l_o_c_a_t_i_o_n-_s_c_a_l_e _m_o_d_e_l _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 location-scale model of the form 'Y = eta1 + exp(eta2)*error'
     to data with a single continuous Y-variable and two-phase
     missingness structure,  using the linear predictors 'eta1' and
     'eta2' for specification of the location and scale respectively.

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

     locsc2stg(formula1, formula2, yCuts=NULL, weights=NULL, 
               xstrata=NULL, data=list(), obstype.name="obstype",  
               method="direct", fit=TRUE, errdistrn="logistic", 
               errmodpars=6, xs.includes=FALSE, compactX=FALSE, 
               compactY=TRUE, straty.maxnvals=20, start=NULL, 
               Qstart=NULL, deltastart=NULL, int.rescale=TRUE,
               control=mlefn.control(...), 
               control.inner=mlefn.control.inner(...), ...)

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

formula1: A symbolic description of the location model to be fitted 
          (eta1).

formula2: A symbolic description of the log-scale model to be fitted 
          (eta2). '~1' will fit a constant.

   yCuts: Cutpoints used to define Y-strata. Critical when 
          'method="ycutmeth"'. Also required when 'method="direct"' 
          but the starting values are not provided (See Details for
          more  descriptions).

 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 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' and 'obstype.name'.

  method: Two methods are implemented: '"ycutmeth"' and  '"direct"'
          (see Details for more descriptions).

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

errdistrn: A specification for the error distribution. Three choices
          are provided: standard logistic ('"logistic"'), standard
          normal ('"normal"') or student's-t distribution ('"t"').  The
          default is '"logistic"'.

errmodpars: Set parameter values for the error distribution. The
          default is 6 for student's-t distribution.

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

compactX: If 'TRUE', compress X matrix to distinct values with counts 
          before model fitting. This is only applicable to
          'method="direct"'.

compactY: If TRUE, limit the Y-values observed at the first phase
          ('obstype="strata"') to limited numbers of equally spaced 
          possible values. This is only applicable to
          'method="direct"'. 

straty.maxnvals: If 'compactY=TRUE', specify the number of equally 
          spaced possible values spanning the range of Y observed as
          '"strata"'.  The default is 20.

   start: Starting values for the regression parameters. Can be
          compusory if the program cannot produce a valid starting
          value at some situations.

  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.

deltastart: An optional starting matrix for Pr(X=xk|Xstratum=j). This
          is only applicable to 'method="direct"'.

int.rescale: If 'TRUE', all X-variables will be standardised first 
          before fitted in the model.

 control: Specify control parameters for the iterations in '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 location-scale models to continuous Y using
     different error  distributions with various types of observations
     collected at different two-phase  sampling schemes. More detailed
     descriptions of this function can be found in  "Description of the
     'missreg' Library" (Wild and Jiang).




      Two methods are implemented with either Y being categorical 
     ('"ycutmeth"') or at a continuous scale ('"direct"'). The argument
      'yCuts' is critical to the first approach but only required for
     the second  approach when a starting value is needed. If 'yCuts'
     is a vector, it defines  the Y-strata with intervals (-infty,
     'yCuts', infty). If 'yCuts'  is a matrix, the number of columns
     indicates the number of strata used and you can define different
     cutpoints for each stratum. If you want to have differing  numbers
     of cutpoints for different X-strata, pad out the bottom of any
     column  that is not full with NAs.

_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.

yCutsKey: Specify the cutoff intervals for defined Y-strata within 
          each X-stratum.

     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.

  fitted: The fitted values of Y obtained from the model.

     cov: The asymptotic covariance matrix (inverse of the informnation
          matrix).

     cor: The asymptotic correlation matrix.

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

deltamat: The estimated 'delta' matrix from the last iteration. 
           This is only applicable to 'method="direct"'.

_N_o_t_e:

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

     data(lowbirth.ls)
     lowbirth.ls$sex.age <- interaction(lowbirth.ls$sex,lowbirth.ls$gest)
     yCuts <- matrix(c(2550,2650,2740,2840,2900,3010,3030,3140),nrow=1)

     z1 <- locsc2stg(birthwt ~ gest + mumht + bmi+ethnicdb+hyper+smoke, ~1,
                     yCuts=yCuts, xstrata=c("sex.age"), data=lowbirth.ls, 
                     obstype.name=c("instudy"), xs.includes=FALSE, 
                     method="ycutmeth")
     summary(z1)

     z2 <- locsc2stg(birthwt ~ gest + mumht + bmi+ethnicdb+hyper+smoke,~1,
                     xstrata=c("sex.age"),data=lowbirth.ls, 
                     obstype.name=c("instudy"), xs.includes=FALSE, 
                     method="direct", start=z1$coefficients, compactX=TRUE,
                     compactY=TRUE, straty.maxnvals=20)
     summary(z2)

     z2 <- locsc2stg(birthwt ~ gest + mumht + bmi+ethnicdb+hyper+smoke,~1,
                     yCuts=yCuts, xstrata=c("sex.age"), data=lowbirth.ls, 
                     obstype.name=c("instudy"), xs.includes=FALSE, 
                     method="direct", start=z1$coefficients, Qstart=z1$Qmat, 
                     compactX=TRUE, compactY=TRUE, straty.maxnvals=20, 
                     control.inner=mlefn.control.inner(n.earlyit=3))
     summary(z2)

     z3 <- locsc2stg(birthwt ~ gest + mumht + bmi+ethnicdb+hyper+smoke,~1,
                     xstrata=c("sex.age"),data=lowbirth.ls, 
                     obstype.name=c("instudy"), xs.includes=FALSE, 
                     method="direct", start=z2$coefficients, 
                     deltastart=z2$deltamat, compactX=TRUE,
                     compactY=TRUE, straty.maxnvals=100)
     summary(z3)

