oglmx {oglmx}

Fit Ordered Generalized Linear Model.

Description

oglmx is used to estimate models for which the outcome variable is discrete and the mean and/or variance of the underlying latent variable can be modelled as a linear combination of explanatory variables. Standard models such as probit, logit, ordered probit and ordered logit are included in the diverse set of models estimated by the function.

Usage

oglmx(formulaMEAN, formulaSD=NULL, data, start=NULL, weights=NULL,
      link="probit", constantMEAN=TRUE, constantSD=TRUE, beta=NULL,
      delta=NULL, threshparam=NULL, analhessian=TRUE, 
      sdmodel=expression(exp(z)), SameModelMEANSD=FALSE, na.action,
      savemodelframe=TRUE, Force=FALSE, robust=FALSE)
      
oglmx.fit(outcomeMatrix, X, Z, w, beta, delta, threshparam, link, start,
          sdmodel, optmeth="maxLik", analhessian, robust)

Arguments

formulaMEAN

an object of class formula: a symbolic description of the model used to explain the mean of the latent variable. The response variable should be a numeric vector or factor variable such that the numerical assignments for the levels of the factor have ordinal meaning.

formulaSD

either NULL or an object of class formula: a symbolic description of the model used to explain the variance of the latent variable.

data

a data frame containing the variables in the model.

start

either NULL or a numeric vector specifying start values for each of the estimated parameters, passed to the maximisation routine.

weights

either NULL or a numeric vector of length equal to the number of rows in the data frame. Used to apply weighted maximum likelihood estimation.

link

specifies a link function for the model to be estimated, accepted values are "probit", "logit", "cauchit", "loglog" and "cloglog"

constantMEAN

logical. Should an intercept be included in the model of the mean of the latent variable? Can be overwritten and set to FALSE using the formulaMEAN argument by writing 0 + as the first element of the equation.

constantSD

logical. Should an intercept be included in the model of the variance of the latent variable? Can be overwritten and set to FALSE using the formulaSD argument by writing 0 + as the first element of the equation.

beta

NULL or numeric vector. Used to prespecify elements of the parameter vector for the equation of the mean of the latent variable. Vector should be of length one or of length equal to the number of explanatory variables in the mean equation. If of length one the value is presumed to correspond to the constant if a constant is included or the first element of the parameter vector. If of length greater than one then NA should be entered for elements of the vector to be estimated.

delta

NULL or numeric vector. Used to prespecify elements of the parameter vector for the equation of the variance of the latent variable. Vector should be of length one or of length equal to the number of explanatory variables in the variance equation. If of length one the value is presumed to correspond to the constant if a constant is included or the first element of the parameter vector. If of length greater than one then NA should be entered for elements of the vector to be estimated.

threshparam

NULL or numeric vector. Used to prespecify the threshold parameters of the model. Vector should be of length equal to the number of outcomes minus one. NA should be entered for threshold parameters to be estimated by the model.

analhessian

logical. Indicates whether the analytic Hessian should be calculated and used, default is TRUE, if set to FALSE a finite-difference approximation of the Hessian is used.

sdmodel

object of mode “expression”. The expression defines function that transforms the linear model for the standard deviation into the standard deviation. The expression should be written as a function of variable z. The default value is expression(exp(z)).

SameModelMEANSD

logical. Indicates whether the matrix used to model the mean of the latent variable is identical to that used to model the variance. If formulaSD=NULL and SameModelMEANSD=TRUE a model with heteroskedasticity is estimated. If SameModelMEANSD=FALSE and formulaSD==formulaMEAN value is overridden. Used to reduce memory requirements when models are identical.

na.action

a function which indicates what should happen when the data contain NAs. The default is set by the na.action setting of options, and is na.fail if that is unset. The factory-fresh default is na.omit. Another possible value is NULL, no action. Value na.exclude can be useful.

savemodelframe

logical. Indicates whether the model frame(s) should be saved for future use. Default is FALSE. Should be set to TRUE if intending to estimate Average Marginal Effects.

Force

logical. If set to FALSE (the default) the function stops if the response variable has more than twenty categories. Should be changed to TRUE if a model with more than twenty categories is desired.

robust

logical. If set to TRUE the outer product or BHHH estimate of the meat in the sandwich of the variance-covariance matrix is calculated. If calculated standard errors will be calculated using the sandwich estimator by default when calling summary.

outcomeMatrix, X, Z

X is a data matrix for the right hand side of the mean equation, outcomeMatrix is a matrix that indicates the outcome variable and Z is a data matrix for the variance equation.

w

w specifies a vector of weights for the oglmx.fit function.

optmeth

optmeth specifies a method for the maximisation of the likelihood, currently "maxLik" is the only available option.

Value

An object of class "oglmx" with the following components:

link

link function used in the estimated model.

sdmodel

Expression for the model for the standard deviation, default is exp(z).

call

the call used to generate the results.

factorvars

vector listing factor variables included in the model

Outcomes

numeric vector listing the values of the different outcomes.

NoVarModData

dataframe. Contains data required to estimate the no information model used in calculation of McFadden's R-squared measure.

NOutcomes

the number of distinct outcomes in the response variable.

Hetero

logical. If TRUE indicates that the estimated model includes a model for the variance of the error term, i.e. heteroskedasticity.

formula

two element list. Each element is an object of type formula related to the mean and standard deviation equation respectively.

modelframes

If savemodelframe set to FALSE then returns NULL, otherwise returns a list with two elements, the model frames for the mean and variance equations.

BothEq

Omitted in the case of a homoskedastic model. Dataframe listing variables that are contained in both the mean and variance equations.

varMeans

a list containing two numeric vectors. The vectors list the mean values of the variables in the mean and variance equation respectively. Stored for use in a call of margins.oglmx to obtain marginal effects at means.

varBinary

a list containing two numeric vectors. The vectors indicate whether the variables in the mean and variance equations are binary indicators. Stored for use in a call of margins.oglmx to obtain marginal effects at means.

loglikelihood

log-likelihood for the estimated model. Includes as attributes the log-likelihood for the constant only model and the number of observations.

coefficients

vector of estimated parameters.

gradient

numeric vector, the value of the gradient of the log-likelihood function at the obtained parameter vector. Should be approximately equal to zero.

no.iterations

number of iterations of maximisation algorithm.

returnCode

code returned by the maxLik optimisation routine. For details of meaning see maxNR.

hessian

hessian matrix of the log-likelihood function evaluated at the obtained parameter vector.

allparams

a list containing three numeric vectors, the vectors contain the parameters from the mean equation, the variance equation and the threshold parameters respectively. Includes the prespecified and estimated parameters together.

Est.Parameters

list containing three logical vectors. Indicates which parameters in the parameter vectors were estimated.

BHHHhessian

Omitted if robust = FALSE and weights were not included. The BHHH variance-covariance estimate.

Author(s)

Nathan Carroll, [e-mail]

References

Cameron, A. C. & Trivedi, P. K. (2005) Microeconometrics : methods and applications Cambridge University Press

Wooldridge, J. M. (2002) Econometric analysis of cross section and panel data The MIT Press

See Also

maxLik, margins.oglmx, polr.

Examples

# create random sample, three variables, two binary.
set.seed(242)
n<-250
x1<-sample(c(0,1),n,replace=TRUE,prob=c(0.75,0.25))
x2<-vector("numeric",n)
x2[x1==0]<-sample(c(0,1),n-sum(x1==1),replace=TRUE,prob=c(2/3,1/3))
z<-rnorm(n,0.5)
# create latent outcome variable
latenty<-0.5+1.5*x1-0.5*x2+0.5*z+rnorm(n,sd=exp(0.5*x1-0.5*x2))
# observed y has four possible values: -1,0,1,2
# threshold values are: -0.5, 0.5, 1.5.
y<-vector("numeric",n)
y[latenty< -0.5]<--1
y[latenty>= -0.5 & latenty<0.5]<- 0
y[latenty>= 0.5 & latenty<1.5]<- 1
y[latenty>= 1.5]<- 2
dataset<-data.frame(y,x1,x2)
# estimate standard ordered probit
results.oprob<-oglmx(y ~ x1 + x2 + z, data=dataset,link="probit",constantMEAN=FALSE,
                     constantSD=FALSE,delta=0,threshparam=NULL)
coef(results.oprob) # extract estimated coefficients
summary(results.oprob)
# calculate marginal effects at means
margins.oglmx(results.oprob)
# estimate ordered probit with heteroskedasticity
results.oprobhet<-oglmx(y ~ x1 + x2 + z, ~ x1 + x2, data=dataset, link="probit",
                     constantMEAN=FALSE, constantSD=FALSE,threshparam=NULL)
summary(results.oprobhet)
library("lmtest")
# likelihood ratio test to compare model with and without heteroskedasticity.
lrtest(results.oprob,results.oprobhet)
# calculate marginal effects at means.
margins.oglmx(results.oprobhet)
# scale of parameter values is meaningless. Suppose instead two of the 
# three threshold values were known, then can include constants in the 
# mean and standard deviation equation and the scale is meaningful.
results.oprobhet1<-oglmx(y ~ x1 + x2 + z, ~ x1 + x2, data=dataset, link="probit",
                        constantMEAN=TRUE, constantSD=TRUE,threshparam=c(-0.5,0.5,NA))
summary(results.oprobhet1)
margins.oglmx(results.oprobhet1)
# marginal effects are identical to results.oprobithet, but using the true thresholds
# means the estimated parameters are on the same scale as underlying data.
# can choose any two of the threshold values and get broadly the same result.
results.oprobhet2<-oglmx(y ~ x1 + x2 + z, ~ x1 + x2, data=dataset, link="probit",
                         constantMEAN=TRUE, constantSD=TRUE,threshparam=c(-0.5,NA,1.5))
summary(results.oprobhet2)
margins.oglmx(results.oprobhet2)
# marginal effects are again identical. Parameter estimates do change.