Skip to contents

format model parameters in APA style

Source: R/tables.R
apa_parameters.Rd

format model parameters in APA style

Usage

apa_parameters(
  fit,
  predictor_parameters = c("Coefficient", "SE", "Std_Coefficient", "t", "df_error", "p"),
  starred = NULL,
  bolded = NULL,
  column_formats = NULL,
  t_with_df = TRUE,
  ...
)

# S3 method for class 'lm'
apa_parameters(
  fit,
  predictor_parameters = c("Parameter", "Coefficient", "SE", "Std_Coefficient", "t",
    "df_error", "p"),
  starred = NA,
  bolded = NA,
  column_formats = NULL,
  t_with_df = TRUE,
  ...
)

# S3 method for class 'glm'
apa_parameters(
  fit,
  predictor_parameters = c("Parameter", "Coefficient", "SE", "Exp_Coefficient", "t", "z",
    "df_error", "p"),
  starred = NA,
  bolded = NA,
  column_formats = NULL,
  t_with_df = TRUE,
  exponentiate = NULL,
  ...
)

# S3 method for class 'polr'
apa_parameters(
  fit,
  predictor_parameters = c("Parameter", "Coefficient", "SE", "Exp_Coefficient", "z", "p"),
  starred = NA,
  bolded = NA,
  column_formats = NULL,
  t_with_df = TRUE,
  exponentiate = NULL,
  thresholds = TRUE,
  ...
)

# S3 method for class 'clm'
apa_parameters(
  fit,
  predictor_parameters = c("Parameter", "Coefficient", "SE", "Exp_Coefficient", "z", "p"),
  starred = NA,
  bolded = NA,
  column_formats = NULL,
  t_with_df = TRUE,
  exponentiate = NULL,
  thresholds = TRUE,
  ...
)

# S3 method for class 'merMod'
apa_parameters(
  fit,
  predictor_parameters = c("Parameter", "Coefficient", "SE", "Exp_Coefficient", "t", "z",
    "df_error", "p"),
  starred = NA,
  bolded = NA,
  column_formats = NULL,
  t_with_df = TRUE,
  exponentiate = NULL,
  random = TRUE,
  ...
)

# S3 method for class 'list'
apa_parameters(
  fit,
  predictor_parameters = NULL,
  starred = "deltaR2",
  bolded = NA,
  column_formats = NULL,
  t_with_df = TRUE,
  performance_parameters = c("R2", "deltaR2"),
  ...
)

Arguments

fit

model fit object

predictor_parameters

predictor parameters to display. If named vector, column names will be vector names. Columns not present in the model output (e.g., t for a model tested with z) are silently dropped. For lists of models, NULL (default) uses the default for each model's class. Add "CI" to show confidence intervals as [LL, UL] (headed, e.g., "95% CI"), and, for glm, polr, and clm models, "Exp_CI" to show confidence intervals of exponentiated coefficients (headed, e.g., "95% CI for OR"). Confidence intervals are not shown by default.

starred

columns to star with significant p_values

bolded

columns to bold, if significant

column_formats

column_formats object to format columns. If NULL, the default column_formats is used.

t_with_df

if TRUE, the t column will be displayed with degrees of freedom in parentheses. If FALSE, only the t value is displayed.

...

arguments passed to methods. For lm, glm, polr, and clm models, further arguments are passed to parameters::model_parameters(). For example, vcov = "HC3" gives heteroskedasticity-consistent (robust) standard errors, and the test statistics, p-values, and confidence intervals are based on them. ci = .90 sets the confidence level.

exponentiate

if NULL (default), exponentiated coefficients are added when the model's link function is logit or log (i.e., odds ratios, risk ratios, or incidence rate ratios). If TRUE, exponentiated coefficients are always added. If FALSE, they are never added.

thresholds

for ordinal models, if TRUE (default), threshold (cutpoint) rows are displayed below the predictors.

random

for mixed models, if TRUE (default), random-effect standard deviations and correlations (and the residual standard deviation, for linear mixed models) are displayed below the fixed effects.

performance_parameters

for lists of models, model comparison metrics passed to apa_performance_comparison(). If NULL, no metrics are added. By default, R2 and deltaR2; for lists of mixed models (lme4), the default also includes the conditional R^2^ and its change (R2_conditional, deltaR2_conditional), and R2 is the marginal R^2^.

Value

tibble

Details

For glm objects (including MASS::glm.nb), the test statistic is z for families with a fixed dispersion parameter (binomial, Poisson, negative binomial) and t for families with an estimated dispersion parameter (Gaussian, Gamma, inverse Gaussian, quasi families). Whichever statistic applies is displayed. The exponentiated coefficient column (Exp_Coefficient) is labeled OR for logit links, IRR for log links in count models (Poisson, quasi-Poisson, negative binomial), RR for log links in binomial models, and Exp(B) otherwise.

For ordinal regression models (MASS::polr and ordinal::clm), coefficients are tested with Wald z tests. (parameters reports t for polr, but the test is asymptotically normal, and clm reports z for the same model.) With a logit link, exponentiated coefficients are cumulative odds ratios, labeled OR. Threshold rows show only the estimate, its standard error, and its confidence interval, because their exponentiated values are not odds ratios, and testing whether a threshold equals 0 is not meaningful. Confidence intervals ("CI", "Exp_CI") are Wald z intervals, consistent with the z tests.

For mixed models fit with lme4 (lmer and glmer), fixed effects are displayed as for lm and glm models. For linear mixed models, t tests and confidence intervals use Kenward–Roger degrees of freedom by default (ci_method = "kenward", which requires the pbkrtest package); pass another ci_method (e.g., "satterthwaite", which requires lmerTest, or "wald") to change this. When the degrees of freedom differ across fixed effects, they are shown in a df column rather than in the t column header. Random-effect rows show only the estimated standard deviation (SD) or correlation (r), labeled by grouping factor.

Examples

lm(mpg ~ cyl + wt, data = mtcars) |>
   apa_parameters() |>
   apa_flextable()

Variable
B
SE
β
t(29)
p
Constant
39.69
1.71
 .00
23.14
<.001
Cyl
−1.51
0.41
−.45
−3.64
 .001
Wt
−3.19
0.76
−.52
−4.22
<.001

# Confidence intervals with robust (HC3) standard errors
lm(mpg ~ cyl + wt, data = mtcars) |>
   apa_parameters(
     predictor_parameters = c("Parameter", "Coefficient", "SE", "CI", "t", "df_error", "p"),
     vcov = "HC3"
   ) |>
   apa_flextable()
#> Warning: restarting interrupted promise evaluation
#> Error: Sorry, ‘model_parameters()’ failed with the following error (possible
#>   class ‘lm’ not supported):
#> 
#>   Package `sandwich` required to get robust standard errors. Please
#>   install it by running `install.packages("sandwich")`.
glm(am ~ wt + hp, data = mtcars, family = binomial) |>
   apa_parameters() |>
   apa_flextable()

Variable
B
SE
OR
z
p
Constant
18.87
7.44
1.56×108 
 2.53
.01 
Wt
−8.08
3.07
3.09×10−4
−2.63
.008
Hp
 0.04
0.02
1.04     
 2.04
.04 
MASS::polr(poverty ~ gender + age, data = carData::WVS, Hess = TRUE) |>
   apa_parameters()
#> # A tibble: 4 × 6
#>   Variable                 `*B*` `*SE*` `*OR*` `*z*`  `*p*`  
#>   <chr>                    <chr> <chr>  <chr>  <chr>  <chr>  
#> 1 Gender–Male              0.15  0.05   "1.17" "2.96" " .003"
#> 2 Age                      0.01  0.00   "1.01" "8.59" "<.001"
#> 3 Too Little | About Right 0.68  0.08   ""     ""     ""     
#> 4 About Right | Too Much   2.41  0.09   ""     ""     ""     
if (requireNamespace("lme4", quietly = TRUE) &&
    requireNamespace("pbkrtest", quietly = TRUE)) {
  lme4::lmer(Reaction ~ Days + (Days | Subject), data = lme4::sleepstudy) |>
    apa_parameters()
}
#> # A tibble: 6 × 5
#>   Variable                      `*B*`  `*SE*` `*t*(17)` `*p*`  
#>   <chr>                         <chr>  <chr>  <chr>     <chr>  
#> 1 Constant                      251.41 "6.82" "36.84"   "<.001"
#> 2 Days                           10.47 "1.55" " 6.77"   "<.001"
#> 3 Subject: *SD* (Constant)       24.74 ""     ""        ""     
#> 4 Subject: *SD* (Days)            5.92 ""     ""        ""     
#> 5 Subject: *r* (Constant, Days)    .07 ""     ""        ""     
#> 6 Residual *SD*                  25.59 ""     ""        ""