apaformat: apa format

#' @title apa.regression.lm
#'
#' @description APA formated interpretation of \code{\link[stats]{lm}}
#'
#' @export
#' 
#' @param model \code{\link[stats]{lm}} to be formatted
#' @param ci \code{\link[stats]{confint}} or similar (optional)
#' @return the formatted \code{\link[base]{data.frame}}
#'
#' @author Mark Newman, \email{mark@trinetteandmark.com}
#' @keywords regression 
#' @family regression
#' 
#' @details
#'   Pulls out the estimates, confidence interval, statistic, and p-value of the model; formats the estimates, confidence interval, p-values; calculates \eqn{r = \sqrt{t^2/(t^2+df)}}; and produces a table.
#'
#' @examples
#'   \dontshow{
#'     library(apaformat)
#'     library(knitr)}
#'   x = testdata.apa.regression.lm
#'   model = lm(Response ~ Treatment, data = x)
#'   ci = confint(model)
#'   tab = apa.regression(model, ci)
#'   kable(tab, caption = 'Regression coefficients with 95% CI', booktabs = TRUE)
#'   
apa.regression.lm = function(model, ci = NULL) {

  stopifnot(class(model) == "lm")

  cf = stats::coef(summary(model))
  df = model$df.residual
  
  est = round(cf[,1], 3)
  cif = NULL
  if(!is.null(ci)) { cif = apa.confint(ci) }
  t = apa.tstat(cf[,3], df)
  r = sprintf("(r = %.3f)", round(sqrt(cf[,3]^2/(cf[,3]^2 + df)), 3))       
  pv = apa.pvalue(cf[,4])

  tab = cbind(est, cif, t, r, pv)
  colnames(tab) = c("Estimate", if(!is.null(cif)) { colnames(cif) }, "t-test", "r", "p-value")

  return(tab)
}