Multinomial Regression Tanh Estimator Gauss-Newton Optimizationpackage:multinomRobR Documentation

_M_u_l_t_i_n_o_m_i_a_l _R_e_g_r_e_s_s_i_o_n _H_y_p_e_r_b_o_l_i_c _T_a_n_g_e_n_e_t (_T_a_n_h) _E_s_t_i_m_a_t_o_r _G_a_u_s_s-_N_e_w_t_o_n _O_p_t_i_m_i_z_a_t_i_o_n

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

     'mGNtanh' uses Gauss-Newton optimization to compute the hyperbolic
     tangent (tanh) estimator for the overdispersed multinomial
     regression model for grouped count data.  This function is not
     meant to be called directly by the user.  It is called by
     'multinomRob', which constructs the various arguments.

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

     mGNtanh(bstart, sigma2, resstart, Y, Ypos, Xarray, xvec, tvec,
                    jacstack, itmax = 100, print.level = 0)

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

  bstart: Vector of starting values for the coefficient parameters.

  sigma2: Value of the dispersion parameter (variance).  The estimator
          does not update this value.

resstart: Array of initial orthogonalized (but not standardized)
          residuals.

       Y: Matrix (observations by alternatives) of outcome counts.
          Values must be nonnegative.  Missing data ('NA' values) are
          not allowed.

    Ypos: Matrix indicating which elements of Y are counts to be
          analyzed (TRUE) and which are values to be skipped (FALSE). 
          This allows the set of outcome alternatives to vary over
          observations.

  Xarray: Array of regressors.  dim(Xarray) = c(observations,
          parameters, alternatives).

    xvec: Matrix (parameters by alternatives) that represents the model
          structure. It has a 1 for an estimated parameter, an integer
          greater than 1 for an estimated parameter constrained equal
          to another estimated parameter (all parameters constrained to
          be equal to one another have the same integer value in xvec)
          and a 0 otherwize.

    tvec: Starting values for the regression coefficient parameters, as
          a matrix (parameters by alternatives).  Parameters that are
          involved in equality constraints are repeated in tvec.

jacstack: Array of regressors used to facilitate computing the gradient
          and the hessian matrix. dim(jacstack) = c(observations,
          unique parameters, alternatives).

   itmax: Maximum number of Gauss-Newton stages.  Each stage does at
          most 100 Gauss-Newton steps.

print.level: Specify 0 for minimal printing (error messages only) or 2
          to print details about the tanh computations.

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

     The tanh estimator is a redescending M-estimator.  Given an
     estimate of the scale of the overdispersion, the tanh estimator
     estimates the coefficient parameters of the linear predictors of
     the multinomial regression model.

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

     mGNtanh returns a list of 16 objects.  The returned objects are:

coefficients: The tanh coefficient estimates in matrix format.  The
          matrix has one column for each outcome alternative.  The
          label for each row of the matrix gives the names of the
          regressors to which the coefficient values in the row apply. 
          The regressor names in each label are separated by a forward
          slash (/), and 'NA' is used to denote that no regressor is
          associated with the corresponding value in the matrix.  The
          value 0 is used in the matrix to fill in for values that do
          not correspond to a regressor.

coeffvec: A vector containing the tanh coefficient estimates.

dispersion: Value of the dispersion parameter (variance).  This is the
          value specified in the argument 'sigma2' in the call to the
          function.

       w: Vector of weights based on the tanh estimator's 'psi'
          function for each observation.

     psi: Vector of values of the tanh estimator's 'psi' function for
          each observation.

       A: The outer product of the gradient (expected information)
          divided by the moment estimate of the dispersion.

       B: The inverse of the hessian matrix (observed formation).

  covmat: Sandwich estimate of the asymptotic covariance of the tanh
          coefficient estimates.

   iters: Number of Gauss-Newton iterations.

   error: Error code: 0,    no errors; 2,   'sum(w) < nobs*(ncats-1)/2'
          (weights are too small); 32,  Hessian not positive definite
          in the final Newton step.

  GNlist: List reporting final results of the Gauss-Newton
          optimization.  Elements: 'coefficients', vector of
          coefficient parameters (same as 'coeffvec' value in list
          returned by mGNtanh);  'tvec', matrix of coefficient
          parameters (same as 'coefficients' value in list returned by
          mGNtanh); 'formation', inverse Hessian matrix;  'score',
          score (or gradient element) matrix;  'LLvals', list
          containing weighted ('LLvals$LL') and unweighted
          ('LLvals$LLu') log-likelihood values; 'convflag', TRUE/FALSE
          convergence flag;  'iters', number of iterations done in
          final Gauss-Newton stage;  'posdef', TRUE if Hessian is
          positive definite.

tanhsigma2: The tanh overdispersion parameter estimate, which is a
          weighted moment estimate of the dispersion:  weighted mean
          sum of squared orthogonalized residuals (adjusted for
          effective sample size after weighting and degrees of freedom
          lost to estimated coefficients).

       Y: The same 'Y' matrix that was supplied as input, except
          modified by  having done 'Y[!Ypos] <- 0'.

    Ypos: The same 'Ypos' matrix that was supplied as input.

 probmat: The matrix of predicted probabilities for each category for
          each observation based on the coefficient estimates.

jacstack: The same 'jacstack' that was supplied as an input argument.

  Xarray: The same 'Xarray' that was supplied as an input argument.

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

     Walter R. Mebane, Jr., Cornell University, wrm1@cornell.edu, <URL:
     http://macht.arts.cornell.edu/wrm1/> 

     Jasjeet S. Sekhon, UC Berkeley, sekhon@berkeley.edu, <URL:
     http://sekhon.polisci.berkeley.edu/>

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

     Walter R. Mebane, Jr. and  Jasjeet Singh Sekhon. 2004.  ``Robust
     Estimation and Outlier Detection for Overdispersed Multinomial
     Models of Count Data.''  _American Journal of Political Science_
     48 (April): 391-410 . <URL:
     http://macht.arts.cornell.edu/wrm1/multinom.pdf>

     For the most current code and related material see <URL:
     http://sekhon.polisci.berkeley.edu/robust/>

