outreg: Creates a publication quality result table for regression...

In rockchalk: Regression Estimation and Presentation

Creates a publication quality result table for regression models. Works with models fitted with lm, glm, as well as lme4.

Description

This provides "markup" that the user is will copy into a LaTeX document. As of rockchalk 1.8.4, can also create HTML markup. The rockchalk vignette demonstrates use of outreg in Sweave.

Usage

outreg(
  modelList,
  type = "latex",
  modelLabels = NULL,
  varLabels = NULL,
  tight = TRUE,
  centering = c("none", "siunitx", "dcolumn"),
  showAIC = FALSE,
  float = FALSE,
  request,
  runFuns,
  digits = 3,
  alpha = c(0.05, 0.01, 0.001),
  SElist = NULL,
  PVlist = NULL,
  Blist = NULL,
  title,
  label,
  gofNames,
  print.results = TRUE,
  browse = identical(type, "html") && interactive()
)

Arguments

modelList	A regression model or an R list of regression models. Default model names will be M1, M2, and so forth. User specified names are allowed, such as list("My Model" = m1, "Her Model" = m2). This is the currently recommended way to supply model lables. This is less error prone than the use of the modelLabels argument.
type	Default = "latex". The alternatives are "html" and "csv"
modelLabels	This is allowed, but discouraged. A vector of character string variables, one for each element in modelList. Will override the names in modelList.
varLabels	To beautify the parameter names printed. Must be a named vector in the format c(parmname = "displayName", parmname = "displayName"). Include as many parameters as desired, it is not necessary to supply new labels for all of the parameters.
tight	Table format. If TRUE, parameter estimates and standard errors are printed in a single column. If FALSE, parameter estimates and standard errors are printed side by side.
centering	Default is "none", but may be "siunitx" or "dcolumn". No centering has been the only way until this version. User feedback requested. Don't forget to insert usepackage statment in document preamble for siunitx or dcolumn. If user specifies centering=TRUE, the siunitx method will be used. The dcolumn approach assumes that the values reported in the column use fewer than 3 integer places and 3 decimal places. Additional room is allocated for the significance stars.
showAIC	This is a legacy argument, before the request argument was created. If TRUE, the AIC estimate is included with the diagnostic values. It has the same effect as described by request.
float	Default = FALSE. Include boilerplate for a LaTeX table float, with the tabular markup inside it. Not relevant if type = "html".
request	Extra information to be retrieved from the summary(model) and displayed. This must be a vector of named arguments, such as c(adj.r.squared = "adj $R^2$", fstatistic = "F"). The name must be a valid name of the output object, the value should be the label the user wants printed in the table. See details.
runFuns	A list of functions
digits	Default = 3. How many digits after decimal sign are to be displayed.
alpha	Default = c(0.05, 0.01, 0.001). I think stars are dumb, but enough people have asked me for more stars that I'm caving in.
SElist	Optional. Replacement standard errors. Must be a list of named vectors. outreg uses the R summary to retrieve standard errors, but one might instead want to use robust or bootstrapped standard errors. This argument may supply a new SE vector for each fitted regression model, but it is also allowed to supply the SE replacement for just one of the models. The format should be list("A Model Label" = c(0.1, 0.3, 0.4), "Another Model Label" = c(0.4, 0.2, 0.3). On the left, one must use the same names that are used in the modelList argument.
PVlist	Optional. A list of replacement "p values". It must be a list of named vectors, similar in format to SElist. The which the elements are the "p values" that the user wants to use for each model.
Blist	Optional. This is only needed in the rare case where a model's parameters cannot be discerned from its summary. List must have names for models, and vectors slope coefficient. See discussion of SElist and PVlist.
title	A LaTeX caption for the table. Not relevant if type = "html".
label	A string to be used as a LaTeX label in the table to be created. Not relevant if type = "html".
gofNames	Optional pretty names. R regression summaries use names like "sigma" or "r.squared" that we might want to revise for presentation. I prefer to refer to "sigma" as "RMSE", but perhaps you instead prefer something like gofnames = c("sigma" = "That Estimate I don't understand", "deviance" = "Another Mystery"). The words that you might replace are "sigma", "r.squared", "deviance", "adj.r.squared", "fstatistic".
print.results	Default TRUE, marked-up table will be displayed in session. If FALSE, same result is returned as an object.
browse	Display the regression model in a browse? Defaults to TRUE if type = "html"

Details

outreg returns a string vector. It is suggested that users should save the outreg result and then use cat to save it. That is myMod <- outreg(m1, ...) cat(myMod, file = "myMod.html") or cat(myMod, file = "myMod.tex". In version 1.8.66, we write the html file to a temporary location and display it in a web browser. Many word processors will not accept a cut-and paste transfer from the browser, they will, however, be able to open the html file itself and automatically re-format it in the native table format.

In version 1.8.111, an argument print.results was introduced. This is TRUE by default, so the marked-up table is printed into the session, and it is returned as well. If the function should run silently (as suggested in the last few versions), include print.results = TRUE.

The table includes a minimally sufficient (in my opinion) model summary. It offers parameter estimates, standard errors, and minimally sufficient goodness of fit. My tastes tend toward minimal tables, but users request more features, and outreg's interface hass been generalized to allow specialized requests. See request and runFuns arguments.

I don't want to write a separate table function for every different kind of regression model that exists (how exhausting). So I've tried to revise outreg() to work with regression functions that follow the standard R framework. It is known to work lm and glm, as well as merMod class from lme4, but it will try to interact with other kinds of regression models. Those models should have methods summary(), coef(), vcov() and nobs(). Package writes should provide those, its not my job.

Do you want "robust standard errors"? P values calculated according to some alternative logic? Go ahead, calculate them in your code, outreg will now accept them as arguments. As of Version 1.8.4, users can provide their own standard errors and/or p-values for each model. Thus, if a model answers in the usual way to the standard R request coef(summary(model)), outreg can work if users supply standard errors.

About the customizations request. The request argument supplies a list of names of summary output elements that are desired. The format is a pair, a value to be retrieved from summary(model), and a pretty name to be printed for it. With the lm() regression, for example, one might want the output of the F test and the adjusted R-square: Include request = c(adj.r.squared = "adj. $R^2$", "fstatistic" = "F"). The value on the left is the name of the desired information in the summary object, while the value on the right is any valid LaTeX (or HTML) markup that the user desires to display in the table. request terms that generate a single numerical value will generally work fine, while requests that ask for more structured information, such as the F test (including the 2 degrees of freedom values) may work (user feedback needed).

The runFuns argument is inspired by a user request: could this include the BIC or other summaries that can be easily calculated? Any R function, such as AIC or BIC, should work, as long as it returns a single value. This is a two-part specification, a function name and a pretty label to be used in printing. For example, runFuns = c("AIC" = "Akaike Criterion", "BIC" = "Schwartz Criterion", "logLik" = "LL").

About centering with dcolumn or siunitx. It appears now that results are better with siunitx but dcolumn is more familiar to users. The user has the duty to make sure that the document preamble includes the correct package, \usepackage{dcolumn} or \usepackage{siunitx}. In this version, I have eliminated the need for the user to specify document-wide settings for siunitx. All of the details are explicitly written in the header of each tabular. It is done that way to more easily allow user customizations.

Value

A character vector, one element per row of the regression table.

Note

There are many R packages that can be used to create LaTeX regression tables. memisc, texreg, apsrtable, xtables, and rms are some. This "outreg" version was in use in our labs before we were aware that those packages were in development. It is not intended as a competitor, it is just a slightly different version of the same that is more suited to our needs.

Author(s)

Paul E. Johnson [e-mail]

Examples

set.seed(2134234)
dat <- data.frame(x1 = rnorm(100), x2 = rnorm(100))
dat$y1 <- 30 + 5 * rnorm(100) + 3 * dat$x1 + 4 * dat$x2
dat$y2 <- rnorm(100) + 5 * dat$x2
m1 <- lm(y1 ~ x1, data = dat)
m2 <- lm(y1 ~ x2, data = dat)
m3 <- lm(y1 ~ x1 + x2, data = dat)
gm1 <- glm(y1 ~ x1, family = Gamma, data = dat)
outreg(m1, title = "My One Tightly Printed Regression", float = TRUE)
ex1 <- outreg(m1, title = "My One Tightly Printed Regression",
               float = TRUE, print.results = FALSE, centering = "siunitx")
## Show markup, Save to file with cat()
cat(ex1)
## cat(ex1, file = "ex1.tex")
 
ex2 <- outreg(list("Fingers" = m1), tight = FALSE, 
    title = "My Only Spread Out Regressions", float = TRUE,
    alpha = c(0.05, 0.01, 0.001)) 

ex3 <- outreg(list("Model A" = m1, "Model B label with Spaces" = m2),
    varLabels = list(x1 = "Billie"), 
    title = "My Two Linear Regressions", request = c(fstatistic = "F"),
    print.results = TRUE)
cat(ex3)

ex4 <- outreg(list("Model A" = m1, "Model B" = m2),
    modelLabels = c("Overrides ModelA", "Overrides ModelB"),
    varLabels = list(x1 = "Billie"),
    title = "Note modelLabels Overrides model names")
cat(ex4)
##'
ex5 <- outreg(list("Whichever" = m1, "Whatever" = m2),
    title = "Still have showAIC argument, as in previous versions",
    showAIC = TRUE, float = TRUE, centering = "siunitx")

ex5s <- outreg(list("Whichever" = m1, "Whatever" = m2),
    title = "Still have showAIC argument, as in previous versions",
    showAIC = TRUE, float = TRUE, centering = "siunitx")


## Launches HTML browse
ex5html <- outreg(list("Whichever" = m1, "Whatever" = m2),
    title = "Still have showAIC argument, as in previous versions",
    showAIC = TRUE, type = "html")
## Could instead, make a file:
## fn <- "some_name_you_choose.html"
## cat(ex5html, file = fn)
## browseURL(fn)
## Open that HTML file in LibreOffice or MS Word


ex6 <- outreg(list("Whatever" = m1, "Whatever" =m2),
    title = "Another way to get AIC output",
    runFuns = c("AIC" = "Akaike IC"))
cat(ex6)

ex7 <- outreg(list("Amod" = m1, "Bmod" = m2, "Gmod" = m3),
       title = "My Three Linear Regressions", float = FALSE)
cat(ex7)

## A new feature in 1.85 is ability to provide vectors of beta estimates
## standard errors, and p values if desired. 
## Suppose you have robust standard errors!
if (require(car)){
   newSE <- sqrt(diag(car::hccm(m3)))
   ex8 <- outreg(list("Model A" = m1, "Model B" = m2, "Model C" = m3, "Model C w Robust SE" = m3),
        SElist= list("Model C w Robust SE" = newSE))
   cat(ex8)
}

ex11 <- outreg(list("I Love Long Titles" = m1,
          "Prefer Brevity" = m2,
          "Short" = m3), tight = FALSE, float = FALSE)
cat(ex11)
##'
ex12 <- outreg(list("GLM" = gm1), float = TRUE)
cat(ex12)

ex13 <- outreg(list("OLS" = m1, "GLM" = gm1), float = TRUE,
        alpha = c(0.05, 0.01))
cat(ex13)
##'
ex14 <- outreg(list(OLS = m1, GLM = gm1), float = TRUE,
    request = c(fstatistic = "F"), runFuns = c("BIC" = "BIC"))
cat(ex14)
ex15 <- outreg(list(OLS = m1, GLM = gm1), float = TRUE,
    request = c(fstatistic = "F"), runFuns = c("BIC" = "BIC"),
    digits = 5, alpha = c(0.01))

ex16 <- outreg(list("OLS 1" = m1, "OLS 2" = m2,  GLM = gm1), float = TRUE,
    request = c(fstatistic = "F"),
    runFuns = c("BIC" = "BIC", logLik = "ll"),
    digits = 5, alpha = c(0.05, 0.01, 0.001))

ex17 <- outreg(list("Model A" = gm1, "Model B label with Spaces" = m2),
    request = c(fstatistic = "F"),
    runFuns = c("BIC" = "Schwarz IC", "AIC" = "Akaike IC",
    "nobs" = "N Again?"))

## Here's a fit example from lme4.
if (require(lme4) && require(car)){
  fm1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
  ex18 <- outreg(fm1)
  cat(ex18)
  ## Fit same with lm for comparison
  lm1 <- lm(Reaction ~ Days, sleepstudy)
  ## Get robust standard errors
  lm1rse <- sqrt(diag(car::hccm(lm1)))

  if(interactive()){
  ex19 <- outreg(list("Random Effects" = fm1, 
       "OLS" = lm1, "OLS Robust SE" = lm1),
       SElist = list("OLS Robust SE" = lm1rse), type = "html")
  }
  ## From the glmer examples
  gm2 <- glmer(cbind(incidence, size - incidence) ~ period + (1 | herd),
                   data = cbpp, family = binomial)
  lm2 <- lm(incidence/size ~ period,  data = cbpp)
  lm2rse <- sqrt(diag(car::hccm(lm2)))
  ## Lets see what MASS::rlm objects do? Mostly OK
  rlm2 <- MASS::rlm(incidence/size ~ period, data = cbpp)
  
  ex20 <- outreg(list("GLMER" = gm2, "lm" = lm2, "lm w/robust se" = lm2,
            "rlm" = rlm2), SElist = list("lm w/robust se" = lm2rse),
            type = "html")
   
}

rockchalk documentation built on Aug. 6, 2022, 5:05 p.m.