

   BBiinnaarryy RRaannddoomm EEffffeeccttss MMooddeell wwiitthh TTwwoo LLeevveellss ooff NNeessttiinngg

        binnest(response, totals=NULL, nest=NULL, ccov=NULL, tvcov=NULL,
             mu=~1, re1=~1, re2=~1, preg=NULL, pre1=NULL, pre2=NULL,
             binom.mix=c(10,10), binom.prob=c(0.5,0.5), fcalls=900,
             eps=0.01, print.level=0)

   AArrgguummeennttss::

   response: A list of three column matrices with counts, cor-
             responding totals (not necessary if the response
             is binary), and (second-level) nesting indicator
             for each individual, one matrix or dataframe of
             such counts, or an object of class, response (cre-
             ated by `restovec') or repeated (created by
             `rmna').

     totals: If `response' is a matrix or dataframe, a corre-
             sponding matrix or dataframe of totals (not neces-
             sary if the response is binary). Ignored other-
             wise.

       nest: If `response' is a matrix or dataframe, a corre-
             sponding matrix or dataframe of nesting indica-
             tors. Ignored otherwise.

       ccov: If `response' is a matrix, dataframe, list, or
             object of class, `response', a matrix of time-con-
             stant covariates or an object of class, `tccov'
             (created by `tcctomat'). All of these covariates
             are used in the fixed effects part of the model.
             Ignored if response has class, `repeated'.

      tvcov: If `response' is a matrix, dataframe, list, or
             object of class, `response', an object of class,
             `tvcov' (created by `tvctomat'). All of these
             covariates are used in the fixed effects part of
             the model. Ignored if response has class,
             `repeated'.

         mu: If `response' has class, `repeated', a formula
             beginning with ~, specifying a linear regression
             function for the fixed effects, in the Wilkinson
             and Rogers notation, containing selected covari-
             ates in the response object. (A logit link is
             assumed.)

        re1: If `response' has class, `repeated', a formula
             beginning with ~, specifying a linear regression
             function for the variance of the first level of
             nesting, in the Wilkinson and Rogers notation,
             containing selected covariates in the response
             object. If NULL, a random effect is not fitted at
             this level. (A log link is assumed.)

        re2: If `response' has class, `repeated', a formula
             beginning with ~, specifying a linear regression
             function for the variance of the second level of
             nesting, in the Wilkinson and Rogers notation,
             containing selected covariates in the response
             object. If NULL, a random effect is not fitted at
             this level. (A log link is assumed.)

       preg: Initial parameter estimates for the fixed effect
             regression model: either the model specified by
             `mu' or else the intercept plus one for each
             covariate in `ccov' and `tvcov'.

       pre1: Initial parameter estimates for the first level of
             nesting variance model: either the model specified
             by `re1' or just the intercept. If NULL, a random
             effect is not fitted at this level.

       pre2: Initial parameter estimates for the second level
             of nesting variance model: either the model speci-
             fied by `re1' or just the intercept. If NULL, a
             random effect is not fitted at this level.

   binom.mix: A vector of two values giving the totals for the
             binomial distributions used as the mixing distri-
             butions at the two levels of nesting.

   binom.prob: A vector of two values giving the probabilities
             in the binomial distributions used as the mixing
             distributions at the two levels of nesting. If
             they are 0.5, the mixing distributions approximate
             normal mixing distributions; otherwise, they are
             skewed.

     fcalls: Number of function calls allowed.

        eps: Convergence criterion.

   print.level: If 1, the iterations are printed out.

   DDeessccrriippttiioonn::

        `binnest' is designed to handle binary and binomial
        data with two levels of nesting. The first level is the
        individual and the second will consist of clusters
        within individuals.

        The variance components at the two levels can only
        depend on the covariates if `response' has class,
        `repeated'.

   VVaalluuee::

        A list of classes `binnest' is returned.

   AAuutthhoorr((ss))::

        T.R. Ten Have and J.K. Lindsey

   SSeeee AAllssoo::

        `gar', `read.list', `restovec', `rmna', `tcctomat',
        `tvctomat'.

   EExxaammpplleess::

        y <- rbind(matrix(rbinom(20,1,0.6), ncol=4),
             matrix(rbinom(20,1,0.4), ncol=4))
        resp <- restovec(y, nest=1:4, times=F)
        ccov <- tcctomat(c(rep(0,5),rep(1,5)), name="treatment")
        reps <- rmna(resp, ccov=ccov)
        # two random effects
        binnest(reps, mu=~treatment, preg=c(1,0), pre1=1, pre2=1)
        # first level random effect only
        binnest(reps, mu=~treatment, preg=c(1,-1), pre1=1)
        # second level random effect only
        binnest(reps, mu=~treatment, preg=c(1,-1), pre2=1)

