insight v0.11.0

0

Monthly downloads

0th

Percentile

Easy Access to Model Information for Various Model Objects

A tool to provide an easy, intuitive and consistent access to information contained in various R models, like model formulas, model terms, information about random effects, data that was used to fit the model or data from response variables. 'insight' mainly revolves around two types of functions: Functions that find (the names of) information, starting with 'find_', and functions that get the underlying data, starting with 'get_'. The package has a consistent syntax and works with many different model objects, where otherwise functions to access these information are missing.

Readme

insight

DOI CRAN\_Status\_Badge Documentation R-check downloads total

Gain insight into your models!

When fitting any statistical model, there are many useful pieces of information that are simultaneously calculated and stored beyond coefficient estimates and general model fit statistics. Although there exist some generic functions to obtain model information and data, many package-specific modeling functions do not provide such methods to allow users to access such valuable information.

insight is an R-package that fills this important gap by providing a suite of functions to support almost any model (see a list of the many models supported below in the List of Supported Packages and Models section). The goal of insight, then, is to provide tools to provide easy, intuitive, and consistent access to information contained in model objects. These tools aid applied research in virtually any field who fit, diagnose, and present statistical models by streamlining access to every aspect of many model objects via consistent syntax and output.

Built with non-programmers in mind, insight offers a broad toolbox for making model and data information easily accessible. While insight offers many useful functions for working with and understanding model objects (discussed below), we suggest users start with model_info(), as this function provides a clean and consistent overview of model objects (e.g., functional form of the model, the model family, link function, number of observations, variables included in the specification, etc.). With a clear understanding of the model introduced, users are able to adapt other functions for more nuanced exploration of and interaction with virtually any model object.

Definition of Model Components

The functions from insight address different components of a model. In an effort to avoid confusion about specific “targets” of each function, in this section we provide a short explanation of insight’s definitions of regression model components.

Data

The dataset used to fit the model.

Parameters

Values estimated or learned from data that capture the relationship between variables. In regression models, these are usually referred to as coefficients.

Response and Predictors

  • response: the outcome or response variable (dependent variable) of a regression model.
  • predictor: independent variables of (the fixed part of) a regression model. For mixed models, variables that are only in the random effects part (i.e. grouping factors) of the model are not returned as predictors by default. However, these can be included using additional arguments in the function call, treating predictors are “unique”. As such, if a variable appears as a fixed effect and a random slope, it is treated as one (the same) predictor.

Variables

Any unique variable names that appear in a regression model, e.g., response variable, predictors or random effects. A “variable” only relates to the unique occurence of a term, or the term name. For instance, the expression x + poly(x, 2) has only the variable x.

Terms

Terms themselves consist of variable and factor names separated by operators, or involve arithmetic expressions. For instance, the expression x + poly(x, 2) has one variable x, but two terms x and poly(x, 2).

Random Effects

  • random slopes: variables that are specified as random slopes in a mixed effects model.
  • random or grouping factors: variables that are specified as grouping variables in a mixed effects model.

Aren’t the predictors, terms and parameters the same thing?

In some cases, yes. But not in all cases. Find out more by clicking here to access the documentation.

Functions

The package revolves around two key prefixes: get_* and find_*. The get_* prefix extracts values (or data) associated with model-specific objects (e.g., parameters or variables), while the find_* prefix lists model-specific objects (e.g., priors or predictors). These are powerful families of functions allowing for great flexibility in use, whether at a high, descriptive level (find_*) or narrower level of statistical inspection and reporting (get_*).

In total, the insight package includes 16 core functions: get_data(), get_priors(), get_variance(), get_parameters(), get_predictors(), get_random(), get_response(), find_algorithm(), find_formula(), find_variables(), find_terms(), find_parameters(), find_predictors(), find_random(), find_response(), and model_info(). In all cases, users must supply at a minimum, the name of the model fit object. In several functions, there are additional arguments that allow for more targeted returns of model information. For example, the find_terms() function’s effects argument allows for the extraction of “fixed effects” terms, “random effects” terms, or by default, “all” terms in the model object. We point users to the package documentation or the complementary package website, https://easystats.github.io/insight/, for a detailed list of the arguments associated with each function as well as the returned values from each function.

Examples of Use Cases in R

We now would like to provide examples of use cases of the insight package. These examples probably do not cover typical real-world problems, but serve as illustration of the core idea of this package: The unified interface to access model information. insight should help both users and package developers in order to reduce the hassle with the many exceptions from various modelling packages when accessing model information.

Making Predictions at Specific Values of a Term of Interest

Say, the goal is to make predictions for a certain term, holding remaining co-variates constant. This is achieved by calling predict() and feeding the newdata-argument with the values of the term of interest as well as the “constant” values for remaining co-variates. The functions get_data() and find_predictors() are used to get this information, which then can be used in the call to predict().

In this example, we fit a simple linear model, but it could be replaced by (m)any other models, so this approach is “universal” and applies to many different model objects.

library(insight)
m <- lm(Sepal.Length ~ Species + Petal.Width + Sepal.Width, data = iris)

dat <- get_data(m)
pred <- find_predictors(m, flatten = TRUE)

l <- lapply(pred, function(x) {
    if (is.numeric(dat[[x]])) 
        mean(dat[[x]]) else unique(dat[[x]])
})

names(l) <- pred
l <- as.data.frame(l)

cbind(l, predictions = predict(m, newdata = l))
#>      Species Petal.Width Sepal.Width predictions
#> 1     setosa         1.2         3.1         5.1
#> 2 versicolor         1.2         3.1         6.1
#> 3  virginica         1.2         3.1         6.3

Printing Model Coefficients

The next example should emphasize the possibilities to generalize functions to many different model objects using insight. The aim is simply to print coefficients in a complete, human readable sentence.

The first approach uses the functions that are available for some, but obviously not for all models, to access the information about model coefficients.

print_params <- function(model) {
    paste0("My parameters are ", paste0(row.names(summary(model)$coefficients), collapse = ", "), 
        ", thank you for your attention!")
}

m1 <- lm(Sepal.Length ~ Petal.Width, data = iris)
print_params(m1)
#> [1] "My parameters are (Intercept), Petal.Width, thank you for your attention!"

# obviously, something is missing in the output
m2 <- mgcv::gam(Sepal.Length ~ Petal.Width + s(Petal.Length), data = iris)
print_params(m2)
#> [1] "My parameters are , thank you for your attention!"

As we can see, the function fails for gam-models. As the access to models depends on the type of the model in the R ecosystem, we would need to create specific functions for all models types. With insight, users can write a function without having to worry about the model type.

print_params <- function(model) {
    paste0("My parameters are ", paste0(insight::find_parameters(model, flatten = TRUE), 
        collapse = ", "), ", thank you for your attention!")
}

m1 <- lm(Sepal.Length ~ Petal.Width, data = iris)
print_params(m1)
#> [1] "My parameters are (Intercept), Petal.Width, thank you for your attention!"

m2 <- mgcv::gam(Sepal.Length ~ Petal.Width + s(Petal.Length), data = iris)
print_params(m2)
#> [1] "My parameters are (Intercept), Petal.Width, s(Petal.Length), thank you for your attention!"

Installation

Run the following to install the latest GitHub-version of insight:

install.packages("devtools")
devtools::install_github("easystats/insight")

Or install the latest stable release from CRAN:

install.packages("insight")

Documentation

Please visit https://easystats.github.io/insight/ for documentation.

Contributing and Support

In case you want to file an issue or contribute in another way to the package, please follow this guide. For questions about the functionality, you may either contact us via email or also file an issue.

List of Supported Models by Class

Currently, 156 model classes are supported.

supported_models()
#>   [1] "aareg"             "afex_aov"          "aov"              
#>   [4] "aovlist"           "Arima"             "averaging"        
#>   [7] "bamlss"            "bamlss.frame"      "bayesQR"          
#>  [10] "bayesx"            "BBmm"              "BBreg"            
#>  [13] "bcplm"             "betamfx"           "betaor"           
#>  [16] "betareg"           "BFBayesFactor"     "BGGM"             
#>  [19] "bife"              "bigglm"            "biglm"            
#>  [22] "blavaan"           "blrm"              "bracl"            
#>  [25] "brglm"             "brmsfit"           "brmultinom"       
#>  [28] "censReg"           "cgam"              "cgamm"            
#>  [31] "cglm"              "clm"               "clm2"             
#>  [34] "clmm"              "clmm2"             "clogit"           
#>  [37] "complmrob"         "coxme"             "coxph"            
#>  [40] "coxph.penal"       "cpglm"             "cpglmm"           
#>  [43] "crch"              "crq"               "crqs"             
#>  [46] "DirichletRegModel" "feglm"             "feis"             
#>  [49] "felm"              "fixest"            "flexsurvreg"      
#>  [52] "gam"               "Gam"               "gamlss"           
#>  [55] "gamm"              "gamm4"             "gbm"              
#>  [58] "gee"               "geeglm"            "glht"             
#>  [61] "glimML"            "glm"               "Glm"              
#>  [64] "glmm"              "glmmadmb"          "glmmPQL"          
#>  [67] "glmmTMB"           "glmrob"            "glmRob"           
#>  [70] "glmx"              "gls"               "gmnl"             
#>  [73] "HLfit"             "htest"             "hurdle"           
#>  [76] "iv_robust"         "ivreg"             "lavaan"           
#>  [79] "lm"                "lm_robust"         "lme"              
#>  [82] "lmerMod"           "lmerModLmerTest"   "lmrob"            
#>  [85] "lmRob"             "logistf"           "logitmfx"         
#>  [88] "logitor"           "LORgee"            "lqm"              
#>  [91] "lqmm"              "lrm"               "manova"           
#>  [94] "MANOVA"            "margins"           "maxLik"           
#>  [97] "mclogit"           "mcmc"              "mcmc.list"        
#> [100] "MCMCglmm"          "mediate"           "merMod"           
#> [103] "merModList"        "meta_bma"          "meta_fixed"       
#> [106] "meta_random"       "metaplus"          "mipo"             
#> [109] "mira"              "mixed"             "MixMod"           
#> [112] "mixor"             "mle"               "mle2"             
#> [115] "mlm"               "mlogit"            "mmlogit"          
#> [118] "multinom"          "negbinirr"         "negbinmfx"        
#> [121] "ols"               "plm"               "poissonirr"       
#> [124] "poissonmfx"        "polr"              "probitmfx"        
#> [127] "psm"               "ridgelm"           "rlm"              
#> [130] "rlmerMod"          "RM"                "rma"              
#> [133] "rma.uni"           "robmixglm"         "rq"               
#> [136] "rqss"              "scam"              "sem"              
#> [139] "speedglm"          "speedlm"           "stanmvreg"        
#> [142] "stanreg"           "survfit"           "survreg"          
#> [145] "svyglm"            "svyolr"            "tobit"            
#> [148] "truncreg"          "vgam"              "vglm"             
#> [151] "wbgee"             "wblm"              "wbm"              
#> [154] "zcpglm"            "zeroinfl"          "zerotrunc"
  • Didn’t find a model? File an issue and request additional model-support in insight!

Credits

If this package helped you, please consider citing as follows:

Lüdecke D, Waggoner P, Makowski D. insight: A Unified Interface to Access Information from Model Objects in R. Journal of Open Source Software 2019;4:1412. doi: 10.21105/joss.01412

Functions in insight

Name Description
display Generic export of data frames into formatted tables
all_models_equal Checks if all objects are models of same class
export_table Data frame and Tables Pretty Formatting
find_algorithm Find sampling algorithm and optimizers
clean_parameters Get clean names of model parameters
download_model Download circus models
find_formula Find model formula
find_statistic Find statistic for model
find_response Find name of the response variable
.colour_detect Detect coloured cells
find_variables Find names of all variables
find_terms Find all model terms
format_pd Probability of direction (pd) formatting
find_offset Find possible offset terms in a model
color_if Color-formatting for data columns based on condition
find_interactions Find interaction terms from models
find_weights Find names of model weights
fish Sample data set
format_rope Percentage in ROPE formatting
format_number Convert number to words
get_response Get the values from the response variable
get_sigma Get residual standard deviation from models
clean_names Get clean names of model terms
find_predictors Find names of model predictors
get_variance Get variance components from random effects models
find_parameters Find names of model parameters
get_priors Get summary of priors used for a model
format_p p-values formatting
get_random Get the data from random effects
get_predictors Get the data from model predictors
get_parameters Get model parameters
link_inverse Get link-inverse function from model object
model_info Access information from model objects
n_obs Get number of observations from a model
get_data Get the data that was used to fit the model
format_value Numeric Values Formatting
find_random Find names of random effects
find_random_slopes Find names of random slopes
get_weights Get the values from model weights
is_multivariate Checks if an object stems from a multivariate response model
is_model_supported Checks if an object is a regression model object supported in insight package.
null_model Compute intercept-only model for regression models
print_color Coloured console output
parameters_table Parameter table formatting
get_statistic Get statistic associated with estimates
format_bf Bayes Factor formatting
has_intercept Checks if model has an intercept
get_varcov Get variance-covariance matrix from models
format_ci Confidence/Credible Interval (CI) Formatting
is_nullmodel Checks if model is a null-model (intercept-only)
link_function Get link-function from model object
print_parameters Prepare summary statistics of model parameters for printing
standardize_names Standardize column names
is_model Checks if an object is a regression model object
No Results!

Vignettes of insight

Name
figure3a.png
figure3b.png
figure3c.png
figure3d.png
insight.Rmd
insight_design_1.png
No Results!

Last month downloads

Details

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/insight)](http://www.rdocumentation.org/packages/insight)