Package 'insight'

Description

Small helper that checks if all objects are supported (regression) model objects and of same class.

Usage

all_models_equal(..., verbose = FALSE)

all_models_same_class(..., verbose = FALSE)

Arguments

Value

A logical, TRUE if x are all supported model objects of same class.

Examples

data(mtcars)
data(sleepstudy, package = "lme4")

m1 <- lm(mpg ~ wt + cyl + vs, data = mtcars)
m2 <- lm(mpg ~ wt + cyl, data = mtcars)
m3 <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = sleepstudy)
m4 <- glm(formula = vs ~ wt, family = binomial(), data = mtcars)

all_models_same_class(m1, m2)
all_models_same_class(m1, m2, m3)
all_models_same_class(m1, m4, m2, m3, verbose = TRUE)
all_models_same_class(m1, m4, mtcars, m2, m3, verbose = TRUE)

Description

Function to export data frames into tables, which can be printed to the console, or displayed in markdown or HTML format (and thereby, exported to other formats like Word or PDF). The table width is automatically adjusted to fit into the width of the display device (e.g., width of console). Use the table_width argument to control this behaviour.

Usage

apply_table_theme(out, x, theme = "default", sub_header_positions = NULL)

export_table(
  x,
  sep = " | ",
  header = "-",
  cross = NULL,
  empty_line = NULL,
  digits = 2,
  protect_integers = TRUE,
  missing = "",
  width = NULL,
  format = NULL,
  title = NULL,
  caption = title,
  subtitle = NULL,
  footer = NULL,
  align = NULL,
  by = NULL,
  zap_small = FALSE,
  table_width = "auto",
  remove_duplicates = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

If format = "text" (or NULL), a formatted character string is returned. format = "markdown" (or "md") returns a character string of class knitr_kable, which renders nicely in markdown files. format = "html" returns an gt object (created by the gt package), which - by default - is displayed in the IDE's viewer pane or default browser. This object can be further modified with the various gt-functions.

Note

The values for caption, subtitle and footer can also be provided as attributes of x, e.g. if caption = NULL and x has attribute table_caption, the value for this attribute will be used as table caption. table_subtitle is the attribute for subtitle, and table_footer for footer.

See Also

Vignettes Formatting, printing and exporting tables and Formatting model parameters.

Examples

export_table(head(iris))
export_table(head(iris), cross = "+")
export_table(head(iris), sep = " ", header = "*", digits = 1)

# split longer tables
export_table(head(iris), table_width = 30)


# colored footers
data(iris)
x <- as.data.frame(iris[1:5, ])
attr(x, "table_footer") <- c("This is a yellow footer line.", "yellow")
export_table(x)

attr(x, "table_footer") <- list(
  c("\nA yellow line", "yellow"),
  c("\nAnd a red line", "red"),
  c("\nAnd a blue line", "blue")
)
export_table(x)

attr(x, "table_footer") <- list(
  c("Without the ", "yellow"),
  c("new-line character ", "red"),
  c("we can have multiple colors per line.", "blue")
)
export_table(x)


# column-width
d <- data.frame(
  x = c(1, 2, 3),
  y = c(100, 200, 300),
  z = c(10000, 20000, 30000)
)
export_table(d)
export_table(d, width = 8)
export_table(d, width = c(x = 5, z = 10))
export_table(d, width = c(x = 5, y = 5, z = 10), align = "lcr")

Description

Checking if needed package is installed

Usage

check_if_installed(
  package,
  reason = "for this function to work",
  stop = TRUE,
  minimum_version = NULL,
  quietly = FALSE,
  prompt = interactive(),
  ...
)

Arguments

Value

If stop = TRUE, and package is not yet installed, the function stops and throws an error. Else, a named logical vector is returned, indicating which of the packages are installed, and which not.

Examples

check_if_installed("insight")
try(check_if_installed("datawizard", stop = FALSE))
try(check_if_installed("rstanarm", stop = FALSE))
try(check_if_installed("nonexistent_package", stop = FALSE))
try(check_if_installed("insight", minimum_version = "99.8.7"))
try(check_if_installed(c("nonexistent", "also_not_here"), stop = FALSE))
try(check_if_installed(c("datawizard", "rstanarm"), stop = FALSE))
try(check_if_installed(c("datawizard", "rstanarm"),
  minimum_version = c(NA, "2.21.1"), stop = FALSE
))

Description

This function "cleans" names of model terms (or a character vector with such names) by removing patterns like log() or as.factor() etc.

Usage

clean_names(x, ...)

## S3 method for class 'character'
clean_names(x, include_names = FALSE, ...)

Arguments

Value

The "cleaned" variable names as character vector, i.e. pattern like s() for splines or log() are removed from the model terms.

Note

Typically, this method is intended to work on character vectors, in order to remove patterns that obscure the variable names. For convenience reasons it is also possible to call clean_names() also on a model object. If x is a regression model, this function is (almost) equal to calling find_variables(). The main difference is that clean_names() always returns a character vector, while find_variables() returns a list of character vectors, unless flatten = TRUE. See 'Examples'.

Examples

# example from ?stats::glm
counts <- c(18, 17, 15, 20, 10, 20, 25, 13, 12)
outcome <- as.numeric(gl(3, 1, 9))
treatment <- gl(3, 3)
m <- glm(counts ~ log(outcome) + as.factor(treatment), family = poisson())
clean_names(m)

# difference "clean_names()" and "find_variables()"
data(cbpp, package = "lme4")
m <- lme4::glmer(
  cbind(incidence, size - incidence) ~ period + (1 | herd),
  data = cbpp,
  family = binomial
)

clean_names(m)
find_variables(m)
find_variables(m, flatten = TRUE)

Description

This function "cleans" names of model parameters by removing patterns like "r_" or "b[]" (mostly applicable to Stan models) and adding columns with information to which group or component parameters belong (i.e. fixed or random, count or zero-inflated...)

The main purpose of this function is to easily filter and select model parameters, in particular of - but not limited to - posterior samples from Stan models, depending on certain characteristics. This might be useful when only selective results should be reported or results from all parameters should be filtered to return only certain results (see print_parameters()).

Usage

clean_parameters(x, ...)

Arguments

Details

The Effects column indicate if a parameter is a fixed or random effect. The Component can either be conditional or zero_inflated. For models with random effects, the Group column indicates the grouping factor of the random effects. For multivariate response models from brms or rstanarm, an additional Response column is included, to indicate which parameters belong to which response formula. Furthermore, Cleaned_Parameter column is returned that contains "human readable" parameter names (which are mostly identical to Parameter, except for for models from brms or rstanarm, or for specific terms like smooth- or spline-terms).

Value

A data frame with "cleaned" parameter names and information on effects, component and group where parameters belong to. To be consistent across different models, the returned data frame always has at least four columns Parameter, Effects, Component and Cleaned_Parameter. See 'Details'.

Examples

model <- download_model("brms_zi_2")
clean_parameters(model)

Description

Convenient function that formats columns in data frames with color codes, where the color is chosen based on certain conditions. Columns are then printed in color in the console.

Usage

color_if(
  x,
  columns,
  predicate = `>`,
  value = 0,
  color_if = "green",
  color_else = "red",
  digits = 2
)

colour_if(
  x,
  columns,
  predicate = `>`,
  value = 0,
  colour_if = "green",
  colour_else = "red",
  digits = 2
)

Arguments

Details

The predicate-function simply works like this: which(predicate(x[, columns], value))

Value

x, where columns matched by predicate are wrapped into color codes.

Examples

# all values in Sepal.Length larger than 5 in green, all remaining in red
x <- color_if(iris[1:10, ], columns = "Sepal.Length", predicate = `>`, value = 5)
x
cat(x$Sepal.Length)

# all levels "setosa" in Species in green, all remaining in red
x <- color_if(iris, columns = "Species", predicate = `==`, value = "setosa")
cat(x$Species)

# own function, argument "value" not needed here
p <- function(x, y) {
  x >= 4.9 & x <= 5.1
}
# all values in Sepal.Length between 4.9 and 5.1 in green, all remaining in red
x <- color_if(iris[1:10, ], columns = "Sepal.Length", predicate = p)
cat(x$Sepal.Length)

Description

Remove empty strings from character

Usage

compact_character(x)

Arguments

Value

A character or a character vector with empty strings removed.

Examples

compact_character(c("x", "y", NA))
compact_character(c("x", "NULL", "", "y"))

Description

Remove empty elements from lists

Usage

compact_list(x, remove_na = FALSE)

Arguments

Examples

compact_list(list(NULL, 1, c(NA, NA)))
compact_list(c(1, NA, NA))
compact_list(c(1, NA, NA), remove_na = TRUE)

Description

display() is a generic function to export data frames into various table formats (like plain text, markdown, ...). print_md() usually is a convenient wrapper for display(format = "markdown"). Similar, print_html() is a shortcut for display(format = "html"). See the documentation for the specific objects' classes.

Usage

display(object, ...)

print_md(x, ...)

print_html(x, ...)

## S3 method for class 'data.frame'
display(object, format = "markdown", ...)

## S3 method for class 'data.frame'
print_md(x, ...)

## S3 method for class 'data.frame'
print_html(x, ...)

Arguments

Value

Depending on format, either an object of class gt_tbl or a character vector of class knitr_kable.

Examples

display(iris[1:5, ], format = "html")

Description

Downloads pre-compiled models from the circus-repository. The circus-repository contains a variety of fitted models to help the systematic testing of other packages

Usage

download_model(
  name,
  url = "https://raw.github.com/easystats/circus/master/data/",
  extension = ".rda",
  verbose = TRUE
)

Arguments

Details

The code that generated the model is available at the https://easystats.github.io/circus/reference/index.html.

Value

A model from the circus-repository, or NULL if model could not be downloaded (e.g., due to server problems).

References

https://easystats.github.io/circus/

Examples

download_model("aov_1")
try(download_model("non_existent_model"))

Description

Provides information regarding the models entered in an ellipsis. It detects whether all are models, regressions, nested regressions etc., assigning different classes to the list of objects.

Usage

ellipsis_info(objects, ...)

## Default S3 method:
ellipsis_info(..., only_models = TRUE, verbose = TRUE)

Arguments

Value

The list with objects that were passed to the function, including additional information as attributes (e.g. if models have same response or are nested).

Examples

m1 <- lm(Sepal.Length ~ Petal.Width + Species, data = iris)
m2 <- lm(Sepal.Length ~ Species, data = iris)
m3 <- lm(Sepal.Length ~ Petal.Width, data = iris)
m4 <- lm(Sepal.Length ~ 1, data = iris)
m5 <- lm(Petal.Width ~ 1, data = iris)

objects <- ellipsis_info(m1, m2, m3, m4)
class(objects)

objects <- ellipsis_info(m1, m2, m4)
attributes(objects)$is_nested

objects <- ellipsis_info(m1, m2, m5)
attributes(objects)$same_response

Description

Returns information on the sampling or estimation algorithm as well as optimization functions, or for Bayesian model information on chains, iterations and warmup-samples.

Usage

find_algorithm(x, ...)

Arguments

Value

A list with elements depending on the model.

For frequentist models:

• algorithm, for instance "OLS" or "ML"

• optimizer, name of optimizing function, only applies to specific models (like gam)

For frequentist mixed models:

• algorithm, for instance "REML" or "ML"

• optimizer, name of optimizing function

For Bayesian models:

• algorithm, the algorithm

• chains, number of chains

• iterations, number of iterations per chain

• warmup, number of warmups per chain

Examples

data(sleepstudy, package = "lme4")
m <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = sleepstudy)
find_algorithm(m)



data(sleepstudy, package = "lme4")
m <- suppressWarnings(rstanarm::stan_lmer(
  Reaction ~ Days + (1 | Subject),
  data = sleepstudy,
  refresh = 0
))
find_algorithm(m)

Description

Returns the formula(s) for the different parts of a model (like fixed or random effects, zero-inflated component, ...). formula_ok() checks if a model formula has valid syntax regarding writing TRUE instead of T inside poly() and that no data names are used (i.e. no data$variable, but rather variable).

Usage

find_formula(x, ...)

formula_ok(
  x,
  checks = "all",
  action = "warning",
  prefix_msg = NULL,
  verbose = TRUE,
  ...
)

## Default S3 method:
find_formula(x, verbose = TRUE, ...)

## S3 method for class 'nestedLogit'
find_formula(x, dichotomies = FALSE, verbose = TRUE, ...)

Arguments

Value

A list of formulas that describe the model. For simple models, only one list-element, conditional, is returned. For more complex models, the returned list may have following elements:

• conditional, the "fixed effects" part from the model (in the context of fixed-effects or instrumental variable regression, also called regressors) . One exception are DirichletRegModel models from DirichletReg, which has two or three components, depending on model.

• random, the "random effects" part from the model (or the id for gee-models and similar)

• zero_inflated, the "fixed effects" part from the zero-inflation component of the model

• zero_inflated_random, the "random effects" part from the zero-inflation component of the model

• dispersion, the dispersion formula

• instruments, for fixed-effects or instrumental variable regressions like ivreg::ivreg(), lfe::felm() or plm::plm(), the instrumental variables

• cluster, for fixed-effects regressions like lfe::felm(), the cluster specification

• correlation, for models with correlation-component like nlme::gls(), the formula that describes the correlation structure

• scale, for distributional models such as mgcv::gaulss() family fitted with mgcv::gam(), the formula that describes the scale parameter

• slopes, for fixed-effects individual-slope models like feisr::feis(), the formula for the slope parameters

• precision, for DirichletRegModel models from DirichletReg, when parametrization (i.e. model) is "alternative".

Note

For models of class lme or gls the correlation-component is only returned, when it is explicitly defined as named argument (form), e.g. corAR1(form = ~1 | Mare)

Examples

data(mtcars)
m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
find_formula(m)

m <- lme4::lmer(Sepal.Length ~ Sepal.Width + (1 | Species), data = iris)
f <- find_formula(m)
f
format(f)

Description

Returns all lowest to highest order interaction terms from a model.

Usage

find_interactions(
  x,
  component = c("all", "conditional", "zi", "zero_inflated", "dispersion", "instruments"),
  flatten = FALSE
)

Arguments

Value

A list of character vectors that represent the interaction terms. Depending on component, the returned list has following elements (or NULL, if model has no interaction term):

• conditional, interaction terms that belong to the "fixed effects" terms from the model

• zero_inflated, interaction terms that belong to the "fixed effects" terms from the zero-inflation component of the model

• instruments, for fixed-effects regressions like ivreg, felm or plm, interaction terms that belong to the instrumental variables

Examples

data(mtcars)

m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
find_interactions(m)

m <- lm(mpg ~ wt * cyl + vs * hp * gear + carb, data = mtcars)
find_interactions(m)

Description

Returns a character vector with the name(s) of offset terms.

Usage

find_offset(x)

Arguments

Value

A character vector with the name(s) of offset terms.

Examples

# Generate some zero-inflated data
set.seed(123)
N <- 100 # Samples
x <- runif(N, 0, 10) # Predictor
off <- rgamma(N, 3, 2) # Offset variable
yhat <- -1 + x * 0.5 + log(off) # Prediction on log scale
dat <- data.frame(y = NA, x, logOff = log(off))
dat$y <- rpois(N, exp(yhat)) # Poisson process
dat$y <- ifelse(rbinom(N, 1, 0.3), 0, dat$y) # Zero-inflation process

m1 <- zeroinfl(y ~ offset(logOff) + x | 1, data = dat, dist = "poisson")
find_offset(m1)

m2 <- zeroinfl(y ~ x | 1, data = dat, offset = logOff, dist = "poisson")
find_offset(m2)

Description

Returns the names of model parameters, like they typically appear in the summary() output. For Bayesian models, the parameter names equal the column names of the posterior samples after coercion from as.data.frame(). See the documentation for your object's class:

• Bayesian models (rstanarm, brms, MCMCglmm, ...)

• Generalized additive models (mgcv, VGAM, ...)

• Marginal effects models (mfx)

• Estimated marginal means (emmeans)

• Mixed models (lme4, glmmTMB, GLMMadaptive, ...)

• Zero-inflated and hurdle models (pscl, ...)

• Models with special components (betareg, MuMIn, ...)

Usage

find_parameters(x, ...)

## Default S3 method:
find_parameters(x, flatten = FALSE, verbose = TRUE, ...)

Arguments

Value

A list of parameter names. For simple models, only one list-element, conditional, is returned.

Model components

Possible values for the component argument depend on the model class. Following are valid options:

• "all": returns all model components, applies to all models, but will only have an effect for models with more than just the conditional model component.

• "conditional": only returns the conditional component, i.e. "fixed effects" terms from the model. Will only have an effect for models with more than just the conditional model component.

• "smooth_terms": returns smooth terms, only applies to GAMs (or similar models that may contain smooth terms).

• "zero_inflated" (or "zi"): returns the zero-inflation component.

• "dispersion": returns the dispersion model component. This is common for models with zero-inflation or that can model the dispersion parameter.

• "instruments": for instrumental-variable or some fixed effects regression, returns the instruments.

• "nonlinear": for non-linear models (like models of class nlmerMod or nls), returns staring estimates for the nonlinear parameters.

• "correlation": for models with correlation-component, like gls, the variables used to describe the correlation structure are returned.

• "location": returns location parameters such as conditional, zero_inflated, smooth_terms, or instruments (everything that are fixed or random effects - depending on the effects argument - but no auxiliary parameters).

• "distributional" (or "auxiliary"): components like sigma, dispersion, beta or precision (and other auxiliary parameters) are returned.

Special models

Some model classes also allow rather uncommon options. These are:

• mhurdle: "infrequent_purchase", "ip", and "auxiliary"

• BGGM: "correlation" and "intercept"

• BFBayesFactor, glmx: "extra"

• averaging:"conditional" and "full"

• mjoint: "survival"

• mfx: "precision", "marginal"

• betareg, DirichletRegModel: "precision"

• mvord: "thresholds" and "correlation"

• clm2: "scale"

• selection: "selection", "outcome", and "auxiliary"

For models of class brmsfit (package brms), even more options are possible for the component argument, which are not all documented in detail here.

Parameters, Variables, Predictors and Terms

There are four functions that return information about the variables in a model: find_predictors(), find_variables(), find_terms() and find_parameters(). There are some differences between those functions, which are explained using following model. Note that some, but not all of those functions return information about the dependent and independent variables. In this example, we only show the differences for the independent variables.

model <- lm(mpg ~ factor(gear), data = mtcars)

• find_terms(model) returns the model terms, i.e. how the variables were used in the model, e.g. applying transformations like factor(), poly() etc. find_terms() may return a variable name multiple times in case of multiple transformations. The return value would be "factor(gear)".

• find_parameters(model) returns the names of the model parameters (coefficients). The return value would be "(Intercept)", "factor(gear)4" and "factor(gear)5".

• find_variables() returns the original variable names. find_variables() returns each variable name only once. The return value would be "gear".

• find_predictors() is comparable to find_variables() and also returns the original variable names, but excluded the dependent (response) variables. The return value would be "gear".

Examples

data(mtcars)
m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
find_parameters(m)

Description

Returns the names of model parameters, like they typically appear in the summary() output.

Usage

## S3 method for class 'averaging'
find_parameters(x, component = "conditional", flatten = FALSE, ...)

Arguments

Value

A list of parameter names. The returned list may have following elements, usually requested via the component argument:

• conditional, the "fixed effects" part from the model.

• full, parameters from the full model.

• precision for models of class betareg.

• survival for model of class mjoint.

• extra for models of class glmx.

Model components

Possible values for the component argument depend on the model class. Following are valid options:

• "all": returns all model components, applies to all models, but will only have an effect for models with more than just the conditional model component.

• "conditional": only returns the conditional component, i.e. "fixed effects" terms from the model. Will only have an effect for models with more than just the conditional model component.

• "smooth_terms": returns smooth terms, only applies to GAMs (or similar models that may contain smooth terms).

• "zero_inflated" (or "zi"): returns the zero-inflation component.

• "dispersion": returns the dispersion model component. This is common for models with zero-inflation or that can model the dispersion parameter.

• "instruments": for instrumental-variable or some fixed effects regression, returns the instruments.

• "nonlinear": for non-linear models (like models of class nlmerMod or nls), returns staring estimates for the nonlinear parameters.

• "correlation": for models with correlation-component, like gls, the variables used to describe the correlation structure are returned.

• "location": returns location parameters such as conditional, zero_inflated, smooth_terms, or instruments (everything that are fixed or random effects - depending on the effects argument - but no auxiliary parameters).

• "distributional" (or "auxiliary"): components like sigma, dispersion, beta or precision (and other auxiliary parameters) are returned.

Special models

Some model classes also allow rather uncommon options. These are:

• mhurdle: "infrequent_purchase", "ip", and "auxiliary"

• BGGM: "correlation" and "intercept"

• BFBayesFactor, glmx: "extra"

• averaging:"conditional" and "full"

• mjoint: "survival"

• mfx: "precision", "marginal"

• betareg, DirichletRegModel: "precision"

• mvord: "thresholds" and "correlation"

• clm2: "scale"

• selection: "selection", "outcome", and "auxiliary"

For models of class brmsfit (package brms), even more options are possible for the component argument, which are not all documented in detail here.

Examples

data("GasolineYield", package = "betareg")
m <- betareg::betareg(yield ~ batch + temp, data = GasolineYield)
find_parameters(m)
find_parameters(m, component = "precision")

Description

Returns the names of model parameters, like they typically appear in the summary() output.

Usage

## S3 method for class 'betamfx'
find_parameters(x, component = "all", flatten = FALSE, ...)

Arguments

Value

A list of parameter names. The returned list may have following elements:

• conditional, the "fixed effects" part from the model.

• marginal, the marginal effects.

• precision, the precision parameter.

Model components

Possible values for the component argument depend on the model class. Following are valid options:

• "all": returns all model components, applies to all models, but will only have an effect for models with more than just the conditional model component.

• "conditional": only returns the conditional component, i.e. "fixed effects" terms from the model. Will only have an effect for models with more than just the conditional model component.

• "smooth_terms": returns smooth terms, only applies to GAMs (or similar models that may contain smooth terms).

• "zero_inflated" (or "zi"): returns the zero-inflation component.

• "dispersion": returns the dispersion model component. This is common for models with zero-inflation or that can model the dispersion parameter.

• "instruments": for instrumental-variable or some fixed effects regression, returns the instruments.

• "nonlinear": for non-linear models (like models of class nlmerMod or nls), returns staring estimates for the nonlinear parameters.

• "correlation": for models with correlation-component, like gls, the variables used to describe the correlation structure are returned.

• "location": returns location parameters such as conditional, zero_inflated, smooth_terms, or instruments (everything that are fixed or random effects - depending on the effects argument - but no auxiliary parameters).

• "distributional" (or "auxiliary"): components like sigma, dispersion, beta or precision (and other auxiliary parameters) are returned.

Special models

Some model classes also allow rather uncommon options. These are:

• mhurdle: "infrequent_purchase", "ip", and "auxiliary"

• BGGM: "correlation" and "intercept"

• BFBayesFactor, glmx: "extra"

• averaging:"conditional" and "full"

• mjoint: "survival"

• mfx: "precision", "marginal"

• betareg, DirichletRegModel: "precision"

• mvord: "thresholds" and "correlation"

• clm2: "scale"

• selection: "selection", "outcome", and "auxiliary"

For models of class brmsfit (package brms), even more options are possible for the component argument, which are not all documented in detail here.

Examples

data(mtcars)
m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
find_parameters(m)

Description

Returns the names of model parameters, like they typically appear in the summary() output. For Bayesian models, the parameter names equal the column names of the posterior samples after coercion from as.data.frame().

Usage

## S3 method for class 'BGGM'
find_parameters(x, component = "correlation", flatten = FALSE, ...)

## S3 method for class 'brmsfit'
find_parameters(
  x,
  effects = "all",
  component = "all",
  flatten = FALSE,
  parameters = NULL,
  ...
)

Arguments

Value

A list of parameter names. For simple models, only one list-element, conditional, is returned. For more complex models, the returned list may have following elements:

• conditional, the "fixed effects" part from the model

• random, the "random effects" part from the model

• zero_inflated, the "fixed effects" part from the zero-inflation component of the model

• zero_inflated_random, the "random effects" part from the zero-inflation component of the model

• smooth_terms, the smooth parameters

Furthermore, some models, especially from brms, can also return auxiliary parameters. These may be one of the following:

• sigma, the residual standard deviation (auxiliary parameter)

• dispersion, the dispersion parameters (auxiliary parameter)

• beta, the beta parameter (auxiliary parameter)

• simplex, simplex parameters of monotonic effects (brms only)

• mix, mixture parameters (brms only)

• shiftprop, shifted proportion parameters (brms only)

Models of class BGGM additionally can return the elements correlation and intercept.

Models of class BFBayesFactor additionally can return the element extra.

Examples

data(mtcars)
m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
find_parameters(m)

Description

Returns the parameter names from a model.

Usage

## S3 method for class 'emmGrid'
find_parameters(x, flatten = FALSE, merge_parameters = FALSE, ...)

Arguments

Value

A list of parameter names. For simple models, only one list-element, conditional, is returned.

Examples

data(mtcars)
model <- lm(mpg ~ wt * factor(cyl), data = mtcars)
emm <- emmeans(model, c("wt", "cyl"))
find_parameters(emm)

Description

Returns the names of model parameters, like they typically appear in the summary() output.

Usage

## S3 method for class 'gamlss'
find_parameters(x, flatten = FALSE, ...)

## S3 method for class 'gam'
find_parameters(x, component = "all", flatten = FALSE, ...)

Arguments

Value

A list of parameter names. The returned list may have following elements:

• conditional, the "fixed effects" part from the model.

• smooth_terms, the smooth parameters.

Examples

data(mtcars)
m <- mgcv::gam(mpg ~ s(hp) + gear, data = mtcars)
find_parameters(m)

Description

Returns the names of model parameters, like they typically appear in the summary() output.

Usage

## S3 method for class 'glmmTMB'
find_parameters(x, effects = "all", component = "all", flatten = FALSE, ...)

Arguments

Value

A list of parameter names. The returned list may have following elements, usually returned based on the combination of the effects and component arguments:

• conditional, the "fixed effects" part from the model.

• random, the "random effects" part from the model.

• zero_inflated, the "fixed effects" part from the zero-inflation component of the model.

• zero_inflated_random, the "random effects" part from the zero-inflation component of the model.

• dispersion, the dispersion parameters (auxiliary parameter)

• dispersion_random, the "random effects" part from the dispersion parameters (auxiliary parameter)

• nonlinear, the parameters from the nonlinear formula.

Model components

Possible values for the component argument depend on the model class. Following are valid options:

• "all": returns all model components, applies to all models, but will only have an effect for models with more than just the conditional model component.

• "conditional": only returns the conditional component, i.e. "fixed effects" terms from the model. Will only have an effect for models with more than just the conditional model component.

• "smooth_terms": returns smooth terms, only applies to GAMs (or similar models that may contain smooth terms).

• "zero_inflated" (or "zi"): returns the zero-inflation component.

• "dispersion": returns the dispersion model component. This is common for models with zero-inflation or that can model the dispersion parameter.

• "instruments": for instrumental-variable or some fixed effects regression, returns the instruments.

• "nonlinear": for non-linear models (like models of class nlmerMod or nls), returns staring estimates for the nonlinear parameters.

• "correlation": for models with correlation-component, like gls, the variables used to describe the correlation structure are returned.

• "location": returns location parameters such as conditional, zero_inflated, smooth_terms, or instruments (everything that are fixed or random effects - depending on the effects argument - but no auxiliary parameters).

• "distributional" (or "auxiliary"): components like sigma, dispersion, beta or precision (and other auxiliary parameters) are returned.

Special models

Some model classes also allow rather uncommon options. These are:

• mhurdle: "infrequent_purchase", "ip", and "auxiliary"

• BGGM: "correlation" and "intercept"

• BFBayesFactor, glmx: "extra"

• averaging:"conditional" and "full"

• mjoint: "survival"

• mfx: "precision", "marginal"

• betareg, DirichletRegModel: "precision"

• mvord: "thresholds" and "correlation"

• clm2: "scale"

• selection: "selection", "outcome", and "auxiliary"

For models of class brmsfit (package brms), even more options are possible for the component argument, which are not all documented in detail here.

Examples

data(sleepstudy, package = "lme4")
m <- lme4::lmer(
  Reaction ~ Days + (1 + Days | Subject),
  data = sleepstudy
)
find_parameters(m)

Description

Returns the names of model parameters, like they typically appear in the summary() output.

Usage

## S3 method for class 'zeroinfl'
find_parameters(x, component = "all", flatten = FALSE, ...)

Arguments

Value

A list of parameter names. The returned list may have following elements:

• conditional, the "fixed effects" part from the model.

• zero_inflated, the "fixed effects" part from the zero-inflation component of the model.

• Special models are mhurdle, which also can have the components infrequent_purchase, ip, and auxiliary.

Model components

Possible values for the component argument depend on the model class. Following are valid options:

• "all": returns all model components, applies to all models, but will only have an effect for models with more than just the conditional model component.

• "conditional": only returns the conditional component, i.e. "fixed effects" terms from the model. Will only have an effect for models with more than just the conditional model component.

• "smooth_terms": returns smooth terms, only applies to GAMs (or similar models that may contain smooth terms).

• "zero_inflated" (or "zi"): returns the zero-inflation component.

• "dispersion": returns the dispersion model component. This is common for models with zero-inflation or that can model the dispersion parameter.

• "instruments": for instrumental-variable or some fixed effects regression, returns the instruments.

• "nonlinear": for non-linear models (like models of class nlmerMod or nls), returns staring estimates for the nonlinear parameters.

• "correlation": for models with correlation-component, like gls, the variables used to describe the correlation structure are returned.

• "location": returns location parameters such as conditional, zero_inflated, smooth_terms, or instruments (everything that are fixed or random effects - depending on the effects argument - but no auxiliary parameters).

• "distributional" (or "auxiliary"): components like sigma, dispersion, beta or precision (and other auxiliary parameters) are returned.

Special models

Some model classes also allow rather uncommon options. These are:

• mhurdle: "infrequent_purchase", "ip", and "auxiliary"

• BGGM: "correlation" and "intercept"

• BFBayesFactor, glmx: "extra"

• averaging:"conditional" and "full"

• mjoint: "survival"

• mfx: "precision", "marginal"

• betareg, DirichletRegModel: "precision"

• mvord: "thresholds" and "correlation"

• clm2: "scale"

• selection: "selection", "outcome", and "auxiliary"

For models of class brmsfit (package brms), even more options are possible for the component argument, which are not all documented in detail here.

Examples

data(bioChemists, package = "pscl")
m <- pscl::zeroinfl(
  art ~ fem + mar + kid5 + ment | kid5 + phd,
  data = bioChemists
)
find_parameters(m)

Description

Returns the names of the predictor variables for the different parts of a model (like fixed or random effects, zero-inflated component, ...). Unlike find_parameters(), the names from find_predictors() match the original variable names from the data that was used to fit the model.

Usage

find_predictors(x, ...)

## Default S3 method:
find_predictors(
  x,
  effects = "fixed",
  component = "all",
  flatten = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

A list of character vectors that represent the name(s) of the predictor variables. Depending on the combination of the arguments effects and component, the returned list can have following elements:

• conditional, the "fixed effects" terms from the model

• random, the "random effects" terms from the model

• zero_inflated, the "fixed effects" terms from the zero-inflation component of the model

• zero_inflated_random, the "random effects" terms from the zero-inflation component of the model

• dispersion, the dispersion terms

• instruments, for fixed-effects regressions like ivreg, felm or plm, the instrumental variables

• correlation, for models with correlation-component like gls, the variables used to describe the correlation structure

• nonlinear, for non-linear models (like models of class nlmerMod or nls), the staring estimates for the nonlinear parameters

• smooth_terms returns smooth terms, only applies to GAMs (or similar models that may contain smooth terms)

Model components

Possible values for the component argument depend on the model class. Following are valid options:

• "all": returns all model components, applies to all models, but will only have an effect for models with more than just the conditional model component.

• "conditional": only returns the conditional component, i.e. "fixed effects" terms from the model. Will only have an effect for models with more than just the conditional model component.

• "smooth_terms": returns smooth terms, only applies to GAMs (or similar models that may contain smooth terms).

• "zero_inflated" (or "zi"): returns the zero-inflation component.

• "dispersion": returns the dispersion model component. This is common for models with zero-inflation or that can model the dispersion parameter.

• "instruments": for instrumental-variable or some fixed effects regression, returns the instruments.

• "nonlinear": for non-linear models (like models of class nlmerMod or nls), returns staring estimates for the nonlinear parameters.

• "correlation": for models with correlation-component, like gls, the variables used to describe the correlation structure are returned.

• "location": returns location parameters such as conditional, zero_inflated, smooth_terms, or instruments (everything that are fixed or random effects - depending on the effects argument - but no auxiliary parameters).

• "distributional" (or "auxiliary"): components like sigma, dispersion, beta or precision (and other auxiliary parameters) are returned.

Special models

Some model classes also allow rather uncommon options. These are:

• mhurdle: "infrequent_purchase", "ip", and "auxiliary"

• BGGM: "correlation" and "intercept"

• BFBayesFactor, glmx: "extra"

• averaging:"conditional" and "full"

• mjoint: "survival"

• mfx: "precision", "marginal"

• betareg, DirichletRegModel: "precision"

• mvord: "thresholds" and "correlation"

• clm2: "scale"

• selection: "selection", "outcome", and "auxiliary"

For models of class brmsfit (package brms), even more options are possible for the component argument, which are not all documented in detail here.

Parameters, Variables, Predictors and Terms

There are four functions that return information about the variables in a model: find_predictors(), find_variables(), find_terms() and find_parameters(). There are some differences between those functions, which are explained using following model. Note that some, but not all of those functions return information about the dependent and independent variables. In this example, we only show the differences for the independent variables.

model <- lm(mpg ~ factor(gear), data = mtcars)

• find_terms(model) returns the model terms, i.e. how the variables were used in the model, e.g. applying transformations like factor(), poly() etc. find_terms() may return a variable name multiple times in case of multiple transformations. The return value would be "factor(gear)".

• find_parameters(model) returns the names of the model parameters (coefficients). The return value would be "(Intercept)", "factor(gear)4" and "factor(gear)5".

• find_variables() returns the original variable names. find_variables() returns each variable name only once. The return value would be "gear".

• find_predictors() is comparable to find_variables() and also returns the original variable names, but excluded the dependent (response) variables. The return value would be "gear".

Examples

data(mtcars)
m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
find_predictors(m)

Description

Return the name of the grouping factors from mixed effects models.

Usage

find_random(x, split_nested = FALSE, flatten = FALSE)

Arguments

Value

A list of character vectors that represent the name(s) of the random effects (grouping factors). Depending on the model, the returned list has following elements:

• random, the "random effects" terms from the conditional part of model

• zero_inflated_random, the "random effects" terms from the zero-inflation component of the model

Examples

data(sleepstudy, package = "lme4")
sleepstudy$mygrp <- sample(1:5, size = 180, replace = TRUE)
sleepstudy$mysubgrp <- NA
for (i in 1:5) {
  filter_group <- sleepstudy$mygrp == i
  sleepstudy$mysubgrp[filter_group] <-
    sample(1:30, size = sum(filter_group), replace = TRUE)
}

m <- lme4::lmer(
  Reaction ~ Days + (1 | mygrp / mysubgrp) + (1 | Subject),
  data = sleepstudy
)

find_random(m)
find_random(m, split_nested = TRUE)

Description

Return the name of the random slopes from mixed effects models.

Usage

find_random_slopes(x)

Arguments

Value

A list of character vectors with the name(s) of the random slopes, or NULL if model has no random slopes. Depending on the model, the returned list has following elements:

• random, the random slopes from the conditional part of model

• zero_inflated_random, the random slopes from the zero-inflation component of the model

Examples

data(sleepstudy, package = "lme4")
m <- lme4::lmer(Reaction ~ Days + (1 + Days | Subject), data = sleepstudy)
find_random_slopes(m)

Description

Returns the name(s) of the response variable(s) from a model object.

Usage

find_response(x, combine = TRUE, ...)

## S3 method for class 'mjoint'
find_response(
  x,
  combine = TRUE,
  component = c("conditional", "survival", "all"),
  ...
)

## S3 method for class 'joint'
find_response(
  x,
  combine = TRUE,
  component = c("conditional", "survival", "all"),
  ...
)

Arguments

Value

The name(s) of the response variable(s) from x as character vector, or NULL if response variable could not be found.

Examples

data(cbpp, package = "lme4")
cbpp$trials <- cbpp$size - cbpp$incidence
m <- glm(cbind(incidence, trials) ~ period, data = cbpp, family = binomial)

find_response(m, combine = TRUE)
find_response(m, combine = FALSE)

Description

Return the names of smooth terms from a model object.

Usage

find_smooth(x, flatten = FALSE)

Arguments

Value

A character vector with the name(s) of the smooth terms.

Examples

data(iris)
model <- mgcv::gam(Petal.Length ~ Petal.Width + s(Sepal.Length), data = iris)
find_smooth(model)

Description

Returns the statistic for a regression model (t-statistic, z-statistic, etc.).

Small helper that checks if a model is a regression model object and return the statistic used.

Usage

find_statistic(x, ...)

Arguments

Value

A character describing the type of statistic. If there is no statistic available with a distribution, NULL will be returned.

Examples

# regression model object
data(mtcars)
m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
find_statistic(m)

Description

Returns a list with the names of all terms, including response value and random effects, "as is". This means, on-the-fly tranformations or arithmetic expressions like log(), I(), as.factor() etc. are preserved.

Usage

find_terms(x, ...)

## Default S3 method:
find_terms(x, flatten = FALSE, as_term_labels = FALSE, verbose = TRUE, ...)

Arguments

Value

A list with (depending on the model) following elements (character vectors):

• response, the name of the response variable

• conditional, the names of the predictor variables from the conditional model (as opposed to the zero-inflated part of a model)

• random, the names of the random effects (grouping factors)

• zero_inflated, the names of the predictor variables from the zero-inflated part of the model

• zero_inflated_random, the names of the random effects (grouping factors)

• dispersion, the name of the dispersion terms

• instruments, the names of instrumental variables

Returns NULL if no terms could be found (for instance, due to problems in accessing the formula).

Parameters, Variables, Predictors and Terms

There are four functions that return information about the variables in a model: find_predictors(), find_variables(), find_terms() and find_parameters(). There are some differences between those functions, which are explained using following model. Note that some, but not all of those functions return information about the dependent and independent variables. In this example, we only show the differences for the independent variables.

model <- lm(mpg ~ factor(gear), data = mtcars)

• find_terms(model) returns the model terms, i.e. how the variables were used in the model, e.g. applying transformations like factor(), poly() etc. find_terms() may return a variable name multiple times in case of multiple transformations. The return value would be "factor(gear)".

• find_parameters(model) returns the names of the model parameters (coefficients). The return value would be "(Intercept)", "factor(gear)4" and "factor(gear)5".

• find_variables() returns the original variable names. find_variables() returns each variable name only once. The return value would be "gear".

• find_predictors() is comparable to find_variables() and also returns the original variable names, but excluded the dependent (response) variables. The return value would be "gear".

Note

The difference to find_variables() is that find_terms() may return a variable multiple times in case of multiple transformations (see examples below), while find_variables() returns each variable name only once.

Examples

data(sleepstudy, package = "lme4")
m <- suppressWarnings(lme4::lmer(
  log(Reaction) ~ Days + I(Days^2) + (1 + Days + exp(Days) | Subject),
  data = sleepstudy
))

find_terms(m)

# sometimes, it is necessary to retrieve terms from "term.labels" attribute
m <- lm(mpg ~ hp * (am + cyl), data = mtcars)
find_terms(m, as_term_labels = TRUE)

Description

This functions checks whether any transformation, such as log- or exp-transforming, was applied to the response variable (dependent variable) in a regression formula. Optionally, all model terms can also be checked for any such transformation. Currently, following patterns are detected: log, log1p, log2, log10, exp, expm1, sqrt, ⁠log(y+<number>)⁠, log-log, power (e.g. to 2nd power, like I(y^2)), inverse (like 1/y), scale (e.g., y/3), and box-cox (e-g-, (y^lambda - 1) / lambda).

Usage

find_transformation(x, ...)

## Default S3 method:
find_transformation(x, include_all = FALSE, ...)

Arguments

Value

A string, with the name of the function of the applied transformation. Returns "identity" for no transformation, and e.g. "log(y+3)" when a specific values was added to the response variables before log-transforming. For unknown transformations, returns NULL.

Examples

# identity, no transformation
model <- lm(Sepal.Length ~ Species, data = iris)
find_transformation(model)

# log-transformation
model <- lm(log(Sepal.Length) ~ Species, data = iris)
find_transformation(model)

# log+2
model <- lm(log(Sepal.Length + 2) ~ Species, data = iris)
find_transformation(model)

# find transformation for all model terms
model <- lm(mpg ~ log(wt) + I(gear^2) + exp(am), data = mtcars)
find_transformation(model, include_all = TRUE)

# inverse, response provided as character string
find_transformation("1 / y")

Description

Returns a list with the names of all variables, including response value and random effects.

Usage

find_variables(
  x,
  effects = "all",
  component = "all",
  flatten = FALSE,
  verbose = TRUE
)

Arguments

Value

A list with (depending on the model) following elements (character vectors):

• response, the name of the response variable

• conditional, the names of the predictor variables from the conditional model (as opposed to the zero-inflated part of a model)

• cluster, the names of cluster or grouping variables

• dispersion, the name of the dispersion terms

• instruments, the names of instrumental variables

• random, the names of the random effects (grouping factors)

• zero_inflated, the names of the predictor variables from the zero-inflated part of the model

• zero_inflated_random, the names of the random effects (grouping factors)

Model components

Possible values for the component argument depend on the model class. Following are valid options:

• "all": returns all model components, applies to all models, but will only have an effect for models with more than just the conditional model component.

• "conditional": only returns the conditional component, i.e. "fixed effects" terms from the model. Will only have an effect for models with more than just the conditional model component.

• "smooth_terms": returns smooth terms, only applies to GAMs (or similar models that may contain smooth terms).

• "zero_inflated" (or "zi"): returns the zero-inflation component.

• "dispersion": returns the dispersion model component. This is common for models with zero-inflation or that can model the dispersion parameter.

• "instruments": for instrumental-variable or some fixed effects regression, returns the instruments.

• "nonlinear": for non-linear models (like models of class nlmerMod or nls), returns staring estimates for the nonlinear parameters.

• "correlation": for models with correlation-component, like gls, the variables used to describe the correlation structure are returned.

• "location": returns location parameters such as conditional, zero_inflated, smooth_terms, or instruments (everything that are fixed or random effects - depending on the effects argument - but no auxiliary parameters).

• "distributional" (or "auxiliary"): components like sigma, dispersion, beta or precision (and other auxiliary parameters) are returned.

Special models

Some model classes also allow rather uncommon options. These are:

• mhurdle: "infrequent_purchase", "ip", and "auxiliary"

• BGGM: "correlation" and "intercept"

• BFBayesFactor, glmx: "extra"

• averaging:"conditional" and "full"

• mjoint: "survival"

• mfx: "precision", "marginal"

• betareg, DirichletRegModel: "precision"

• mvord: "thresholds" and "correlation"

• clm2: "scale"

• selection: "selection", "outcome", and "auxiliary"

For models of class brmsfit (package brms), even more options are possible for the component argument, which are not all documented in detail here.

Parameters, Variables, Predictors and Terms

There are four functions that return information about the variables in a model: find_predictors(), find_variables(), find_terms() and find_parameters(). There are some differences between those functions, which are explained using following model. Note that some, but not all of those functions return information about the dependent and independent variables. In this example, we only show the differences for the independent variables.

model <- lm(mpg ~ factor(gear), data = mtcars)

• find_terms(model) returns the model terms, i.e. how the variables were used in the model, e.g. applying transformations like factor(), poly() etc. find_terms() may return a variable name multiple times in case of multiple transformations. The return value would be "factor(gear)".

• find_parameters(model) returns the names of the model parameters (coefficients). The return value would be "(Intercept)", "factor(gear)4" and "factor(gear)5".

• find_variables() returns the original variable names. find_variables() returns each variable name only once. The return value would be "gear".

• find_predictors() is comparable to find_variables() and also returns the original variable names, but excluded the dependent (response) variables. The return value would be "gear".

Note

The difference to find_terms() is that find_variables() returns each variable name only once, while find_terms() may return a variable multiple times in case of transformations or when arithmetic expressions were used in the formula.

Examples

data(cbpp, package = "lme4")
data(sleepstudy, package = "lme4")
# some data preparation...
cbpp$trials <- cbpp$size - cbpp$incidence
sleepstudy$mygrp <- sample(1:5, size = 180, replace = TRUE)
sleepstudy$mysubgrp <- NA
for (i in 1:5) {
  filter_group <- sleepstudy$mygrp == i
  sleepstudy$mysubgrp[filter_group] <-
    sample(1:30, size = sum(filter_group), replace = TRUE)
}

m1 <- lme4::glmer(
  cbind(incidence, size - incidence) ~ period + (1 | herd),
  data = cbpp,
  family = binomial
)
find_variables(m1)

m2 <- lme4::lmer(
  Reaction ~ Days + (1 | mygrp / mysubgrp) + (1 | Subject),
  data = sleepstudy
)
find_variables(m2)
find_variables(m2, flatten = TRUE)

Description

Returns the name of the variable that describes the weights of a model.

Usage

find_weights(x, ...)

Arguments

Value

The name of the weighting variable as character vector, or NULL if no weights were specified.

Examples

data(mtcars)
mtcars$weight <- rnorm(nrow(mtcars), 1, .3)
m <- lm(mpg ~ wt + cyl + vs, data = mtcars, weights = weight)
find_weights(m)

Description

A sample data set, used in tests and some examples.

Description

Bayes Factor formatting

Usage

format_bf(
  bf,
  stars = FALSE,
  stars_only = FALSE,
  inferiority_star = "°",
  name = "BF",
  protect_ratio = FALSE,
  na_reference = NA,
  exact = FALSE
)

Arguments

Value

A formatted string.

Examples

bfs <- c(0.000045, 0.033, NA, 1557, 3.54)
format_bf(bfs)
format_bf(bfs, exact = TRUE, name = NULL)
format_bf(bfs, stars = TRUE)
format_bf(bfs, protect_ratio = TRUE)
format_bf(bfs, protect_ratio = TRUE, exact = TRUE)
format_bf(bfs, na_reference = 1)

Description

This function converts the first letter in a string into upper case.

Usage

format_capitalize(x, verbose = TRUE)

Arguments

Value

x, with first letter capitalized.

Examples

format_capitalize("hello")
format_capitalize(c("hello", "world"))
unique(format_capitalize(iris$Species))

Description

Confidence/Credible Interval (CI) Formatting

Usage

format_ci(CI_low, ...)

## S3 method for class 'numeric'
format_ci(
  CI_low,
  CI_high,
  ci = 0.95,
  digits = 2,
  brackets = TRUE,
  width = NULL,
  width_low = width,
  width_high = width,
  missing = "",
  zap_small = FALSE,
  ci_string = "CI",
  ...
)

Arguments

Value

A formatted string.

Examples

format_ci(1.20, 3.57, ci = 0.90)
format_ci(1.20, 3.57, ci = NULL)
format_ci(1.20, 3.57, ci = NULL, brackets = FALSE)
format_ci(1.20, 3.57, ci = NULL, brackets = c("(", ")"))
format_ci(c(1.205645, 23.4), c(3.57, -1.35), ci = 0.90)
format_ci(c(1.20, NA, NA), c(3.57, -1.35, NA), ci = 0.90)

# automatic alignment of width, useful for printing multiple CIs in columns
x <- format_ci(c(1.205, 23.4, 100.43), c(3.57, -13.35, 9.4))
cat(x, sep = "\n")

x <- format_ci(c(1.205, 23.4, 100.43), c(3.57, -13.35, 9.4), width = "auto")
cat(x, sep = "\n")

Description

Inserts line breaks into a longer message or warning string. Line length is adjusted to maximum length of the console, if the width can be accessed. By default, new lines are indented by two spaces.

format_alert() is a wrapper that combines formatting a string with a call to message(), warning() or stop(). By default, format_alert() creates a message(). format_warning() and format_error() change the default type of exception to warning() and stop(), respectively.

Usage

format_message(
  string,
  ...,
  line_length = 0.9 * getOption("width", 80),
  indent = "  "
)

format_alert(
  string,
  ...,
  line_length = 0.9 * getOption("width", 80),
  indent = "  ",
  type = "message",
  call = FALSE,
  immediate = FALSE
)

format_warning(..., immediate = FALSE)

format_error(...)

Arguments

Details

There is an experimental formatting feature implemented in this function. You can use following tags:

• ⁠{.b text}⁠ for bold formatting

• ⁠{.i text}⁠ to use italic font style

• ⁠{.url www.url.com}⁠ formats the string as URL (i.e., enclosing URL in < and >, blue color and italic font style)

• ⁠{.pkg packagename}⁠ formats the text in blue color.

This features has some limitations: it's hard to detect the exact length for each line when the string has multiple lines (after line breaks) and the string contains formatting tags. Thus, it can happen that lines are wrapped at an earlier length than expected. Furthermore, if you have multiple words in a format tag (⁠{.b one two three}⁠), a line break might occur inside this tag, and the formatting no longer works (messing up the message-string).

Value

For format_message(), a formatted string. For format_alert() and related functions, the requested exception, with the exception formatted using format_message().

Examples

msg <- format_message("Much too long string for just one line, I guess!",
  line_length = 15
)
message(msg)

msg <- format_message("Much too long string for just one line, I guess!",
  "First new line",
  "Second new line",
  "(both indented)",
  line_length = 30
)
message(msg)

msg <- format_message("Much too long string for just one line, I guess!",
  "First new line",
  "Second new line",
  "(not indented)",
  line_length = 30,
  indent = ""
)
message(msg)

# Caution, experimental! See 'Details'
msg <- format_message(
  "This is {.i italic}, visit {.url easystats.github.io/easystats}",
  line_length = 30
)
message(msg)


# message
format_alert("This is a message.")
format_alert("This is a warning.", type = "message")

# error
try(format_error("This is an error."))


# warning
format_warning("This is a warning.")

Description

Convert number to words

Usage

format_number(x, textual = TRUE, ...)

Arguments

Value

A formatted string.

Note

The code has been adapted from here https://github.com/ateucher/useful_code/blob/master/R/numbers2words.r

Examples

format_number(2)
format_number(45)
format_number(324.68765)

Description

Format p-values.

Usage

format_p(
  p,
  stars = FALSE,
  stars_only = FALSE,
  whitespace = TRUE,
  name = "p",
  missing = "",
  decimal_separator = NULL,
  digits = 3,
  ...
)

Arguments

Value

A formatted string.

Examples

format_p(c(.02, .065, 0, .23))
format_p(c(.02, .065, 0, .23), name = NULL)
format_p(c(.02, .065, 0, .23), stars_only = TRUE)

model <- lm(mpg ~ wt + cyl, data = mtcars)
p <- coef(summary(model))[, 4]
format_p(p, digits = "apa")
format_p(p, digits = "scientific")
format_p(p, digits = "scientific2")

Description

Probability of direction (pd) formatting

Usage

format_pd(pd, stars = FALSE, stars_only = FALSE, name = "pd")

Arguments

Value

A formatted string.

Examples

format_pd(0.12)
format_pd(c(0.12, 1, 0.9999, 0.98, 0.995, 0.96), name = NULL)
format_pd(c(0.12, 1, 0.9999, 0.98, 0.995, 0.96), stars = TRUE)

Description

Percentage in ROPE formatting

Usage

format_rope(rope_percentage, name = "in ROPE", digits = 2)

Arguments

Value

A formatted string.

Examples

format_rope(c(0.02, 0.12, 0.357, 0))
format_rope(c(0.02, 0.12, 0.357, 0), name = NULL)

Description

String Values Formatting

Usage

format_string(x, ...)

## S3 method for class 'character'
format_string(x, length = NULL, abbreviate = "...", ...)

Arguments

Value

A formatted string.

Examples

s <- "This can be considered as very long string!"
# string is shorter than max.length, so returned as is
format_string(s, 60)

# string is shortened to as many words that result in
# a string of maximum 20 chars
format_string(s, 20)

Description

This functions takes a data frame (usually with model parameters) as input and formats certain columns into a more readable layout (like collapsing separate columns for lower and upper confidence interval values). Furthermore, column names are formatted as well. Note that format_table() converts all columns into character vectors!

Usage

format_table(
  x,
  pretty_names = TRUE,
  stars = FALSE,
  digits = 2,
  ci_width = "auto",
  ci_brackets = TRUE,
  ci_digits = 2,
  p_digits = 3,
  rope_digits = 2,
  ic_digits = 1,
  zap_small = FALSE,
  preserve_attributes = FALSE,
  exact = TRUE,
  use_symbols = getOption("insight_use_symbols", FALSE),
  verbose = TRUE,
  ...
)

Arguments

Value

A data frame. Note that format_table() converts all columns into character vectors!

Note

options(insight_use_symbols = TRUE) overrides the use_symbols argument and always displays symbols, if possible.

See Also

Vignettes Formatting, printing and exporting tables and Formatting model parameters.

Examples

format_table(head(iris), digits = 1)

m <- lm(Sepal.Length ~ Species * Sepal.Width, data = iris)
x <- parameters::model_parameters(m)
as.data.frame(format_table(x))
as.data.frame(format_table(x, p_digits = "scientific"))


model <- rstanarm::stan_glm(
  Sepal.Length ~ Species,
  data = iris,
  refresh = 0,
  seed = 123
)
x <- parameters::model_parameters(model, ci = c(0.69, 0.89, 0.95))
as.data.frame(format_table(x))

Description

format_value() converts numeric values into formatted string values, where formatting can be something like rounding digits, scientific notation etc. format_percent() is a short-cut for format_value(as_percent = TRUE).

Usage

format_value(x, ...)

## S3 method for class 'data.frame'
format_value(
  x,
  digits = 2,
  protect_integers = FALSE,
  missing = "",
  width = NULL,
  as_percent = FALSE,
  zap_small = FALSE,
  lead_zero = TRUE,
  style_positive = "none",
  style_negative = "hyphen",
  decimal_point = getOption("OutDec"),
  ...
)

## S3 method for class 'numeric'
format_value(
  x,
  digits = 2,
  protect_integers = FALSE,
  missing = "",
  width = NULL,
  as_percent = FALSE,
  zap_small = FALSE,
  lead_zero = TRUE,
  style_positive = "none",
  style_negative = "hyphen",
  decimal_point = getOption("OutDec"),
  ...
)

format_percent(x, ...)

Arguments

Value

A formatted string.

Examples

format_value(1.20)
format_value(1.2)
format_value(1.2012313)
format_value(c(0.0045, 234, -23))
format_value(c(0.0045, 0.12, 0.34))
format_value(c(0.0045, 0.12, 0.34), as_percent = TRUE)
format_value(c(0.0045, 0.12, 0.34), digits = "scientific")
format_value(c(0.0045, 0.12, 0.34), digits = "scientific2")
format_value(c(0.045, 0.12, 0.34), lead_zero = FALSE)
format_value(c(0.0045, 0.12, 0.34), decimal_point = ",")

# default
format_value(c(0.0045, 0.123, 0.345))
# significant figures
format_value(c(0.0045, 0.123, 0.345), digits = "signif")

format_value(as.factor(c("A", "B", "A")))
format_value(iris$Species)

format_value(3)
format_value(3, protect_integers = TRUE)

format_value(head(iris))

Description

Returns the requested auxiliary parameters from models, like dispersion, sigma, or beta...

Usage

get_auxiliary(
  x,
  type = "sigma",
  summary = TRUE,
  centrality = "mean",
  verbose = TRUE,
  ...
)

get_dispersion(x, ...)

## Default S3 method:
get_dispersion(x, ...)

Arguments

Details

Currently, only sigma and the dispersion parameter are returned, and only for a limited set of models.

Value

The requested auxiliary parameter, or NULL if this information could not be accessed.

Sigma Parameter

See get_sigma().

Dispersion Parameter

There are many different definitions of "dispersion", depending on the context. get_auxiliary() returns the dispersion parameters that usually can be considered as variance-to-mean ratio for generalized (linear) mixed models. Exceptions are models of class glmmTMB, where the dispersion equals σ². In detail, the computation of the dispersion parameter for generalized linear models is the ratio of the sum of the squared working-residuals and the residual degrees of freedom. For mixed models of class glmer, the dispersion parameter is also called φ and is the ratio of the sum of the squared Pearson-residuals and the residual degrees of freedom. For models of class glmmTMB, dispersion is σ².

brms-models

For models of class brmsfit, there are different options for the type argument. See a list of supported auxiliary parameters here: find_parameters.BGGM().

Examples

# from ?glm
clotting <- data.frame(
  u = c(5, 10, 15, 20, 30, 40, 60, 80, 100),
  lot1 = c(118, 58, 42, 35, 27, 25, 21, 19, 18),
  lot2 = c(69, 35, 26, 21, 18, 16, 13, 12, 12)
)
model <- glm(lot1 ~ log(u), data = clotting, family = Gamma())
get_auxiliary(model, type = "dispersion") # same as summary(model)$dispersion

Description

Returns the model's function call when available.

Usage

get_call(x)

Arguments

Value

A function call.

Examples

data(mtcars)
m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
get_call(m)

m <- lme4::lmer(Sepal.Length ~ Sepal.Width + (1 | Species), data = iris)
get_call(m)

Description

This functions tries to get the data that was used to fit the model and returns it as data frame.

Usage

get_data(x, ...)

## Default S3 method:
get_data(x, source = "environment", verbose = TRUE, ...)

## S3 method for class 'glmmTMB'
get_data(
  x,
  effects = "all",
  component = "all",
  source = "environment",
  verbose = TRUE,
  ...
)

## S3 method for class 'afex_aov'
get_data(x, shape = c("long", "wide"), ...)

## S3 method for class 'rma'
get_data(
  x,
  source = "environment",
  verbose = TRUE,
  include_interval = FALSE,
  transf = NULL,
  transf_args = NULL,
  ci = 0.95,
  ...
)

Arguments

Value

The data that was used to fit the model.

Model components

Possible values for the component argument depend on the model class. Following are valid options:

• "all": returns all model components, applies to all models, but will only have an effect for models with more than just the conditional model component.

• "conditional": only returns the conditional component, i.e. "fixed effects" terms from the model. Will only have an effect for models with more than just the conditional model component.

• "smooth_terms": returns smooth terms, only applies to GAMs (or similar models that may contain smooth terms).

• "zero_inflated" (or "zi"): returns the zero-inflation component.

• "dispersion": returns the dispersion model component. This is common for models with zero-inflation or that can model the dispersion parameter.

• "instruments": for instrumental-variable or some fixed effects regression, returns the instruments.

• "nonlinear": for non-linear models (like models of class nlmerMod or nls), returns staring estimates for the nonlinear parameters.

• "correlation": for models with correlation-component, like gls, the variables used to describe the correlation structure are returned.

• "location": returns location parameters such as conditional, zero_inflated, smooth_terms, or instruments (everything that are fixed or random effects - depending on the effects argument - but no auxiliary parameters).

• "distributional" (or "auxiliary"): components like sigma, dispersion, beta or precision (and other auxiliary parameters) are returned.

Special models

Some model classes also allow rather uncommon options. These are:

• mhurdle: "infrequent_purchase", "ip", and "auxiliary"

• BGGM: "correlation" and "intercept"

• BFBayesFactor, glmx: "extra"

• averaging:"conditional" and "full"

• mjoint: "survival"

• mfx: "precision", "marginal"

• betareg, DirichletRegModel: "precision"

• mvord: "thresholds" and "correlation"

• clm2: "scale"

• selection: "selection", "outcome", and "auxiliary"

For models of class brmsfit (package brms), even more options are possible for the component argument, which are not all documented in detail here.

Examples

data(cbpp, package = "lme4")
cbpp$trials <- cbpp$size - cbpp$incidence
m <- glm(cbind(incidence, trials) ~ period, data = cbpp, family = binomial)
head(get_data(m))

Description

Create a reference matrix, useful for visualisation, with evenly spread and combined values. Usually used to make generate predictions using get_predicted(). See this vignette for a tutorial on how to create a visualisation matrix using this function.

Alternatively, these can also be used to extract the "grid" columns from objects generated by emmeans and marginaleffects.

Usage

get_datagrid(x, ...)

## S3 method for class 'data.frame'
get_datagrid(
  x,
  by = "all",
  factors = "reference",
  numerics = "mean",
  preserve_range = FALSE,
  reference = x,
  length = 10,
  range = "range",
  ...
)

## S3 method for class 'numeric'
get_datagrid(x, length = 10, range = "range", ...)

## S3 method for class 'factor'
get_datagrid(x, ...)

## Default S3 method:
get_datagrid(
  x,
  by = "all",
  factors = "reference",
  numerics = "mean",
  preserve_range = TRUE,
  reference = x,
  include_smooth = TRUE,
  include_random = FALSE,
  include_response = FALSE,
  data = NULL,
  verbose = TRUE,
  ...
)

## S3 method for class 'emmGrid'
get_datagrid(x, ...)

## S3 method for class 'slopes'
get_datagrid(x, ...)

Arguments

Value

Reference grid data frame.

See Also

get_predicted()

Examples

# Datagrids of variables and dataframes =====================================

# Single variable is of interest; all others are "fixed" ------------------
# Factors
get_datagrid(iris, by = "Species") # Returns all the levels
get_datagrid(iris, by = "Species = c('setosa', 'versicolor')") # Specify an expression

# Numeric variables
get_datagrid(iris, by = "Sepal.Length") # default spread length = 10
get_datagrid(iris, by = "Sepal.Length", length = 3) # change length
get_datagrid(iris[2:150, ],
  by = "Sepal.Length",
  factors = "mode", numerics = "median"
) # change non-targets fixing
get_datagrid(iris, by = "Sepal.Length", range = "ci", ci = 0.90) # change min/max of target
get_datagrid(iris, by = "Sepal.Length = [0, 1]") # Manually change min/max
get_datagrid(iris, by = "Sepal.Length = [sd]") # -1 SD, mean and +1 SD
# identical to previous line: -1 SD, mean and +1 SD
get_datagrid(iris, by = "Sepal.Length", range = "sd", length = 3)
get_datagrid(iris, by = "Sepal.Length = [quartiles]") # quartiles

# Numeric and categorical variables, generating a grid for plots
# default spread length = 10
get_datagrid(iris, by = c("Sepal.Length", "Species"), range = "grid")
# default spread length = 3 (-1 SD, mean and +1 SD)
get_datagrid(iris, by = c("Species", "Sepal.Length"), range = "grid")

# Standardization and unstandardization
data <- get_datagrid(iris, by = "Sepal.Length", range = "sd", length = 3)
data$Sepal.Length # It is a named vector (extract names with `names(out$Sepal.Length)`)
datawizard::standardize(data, select = "Sepal.Length")
data <- get_datagrid(iris, by = "Sepal.Length = c(-2, 0, 2)") # Manually specify values
data
datawizard::unstandardize(data, select = "Sepal.Length")

# Multiple variables are of interest, creating a combination --------------
get_datagrid(iris, by = c("Sepal.Length", "Species"), length = 3)
get_datagrid(iris, by = c("Sepal.Length", "Petal.Length"), length = c(3, 2))
get_datagrid(iris, by = c(1, 3), length = 3)
get_datagrid(iris, by = c("Sepal.Length", "Species"), preserve_range = TRUE)
get_datagrid(iris, by = c("Sepal.Length", "Species"), numerics = 0)
get_datagrid(iris, by = c("Sepal.Length = 3", "Species"))
get_datagrid(iris, by = c("Sepal.Length = c(3, 1)", "Species = 'setosa'"))

# With list-style by-argument
get_datagrid(iris, by = list(Sepal.Length = c(1, 3), Species = "setosa"))

# With models ===============================================================
# Fit a linear regression
model <- lm(Sepal.Length ~ Sepal.Width * Petal.Length, data = iris)
# Get datagrid of predictors
data <- get_datagrid(model, length = c(20, 3), range = c("range", "sd"))
# same as: get_datagrid(model, range = "grid", length = 20)
# Add predictions
data$Sepal.Length <- get_predicted(model, data = data)
# Visualize relationships (each color is at -1 SD, Mean, and + 1 SD of Petal.Length)
plot(data$Sepal.Width, data$Sepal.Length,
  col = data$Petal.Length,
  main = "Relationship at -1 SD, Mean, and + 1 SD of Petal.Length"
)