# insight v0.11.0

Monthly downloads

## 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

**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

Type | Package |

License | GPL-3 |

URL | https://easystats.github.io/insight/ |

BugReports | https://github.com/easystats/insight/issues |

Encoding | UTF-8 |

RoxygenNote | 7.1.1 |

VignetteBuilder | knitr |

Language | en-US |

Config/testthat/edition | 3 |

Config/testthat/parallel | true |

Config/testthat/start-first | watcher, parallel* |

NeedsCompilation | no |

Packaged | 2020-11-24 12:34:01 UTC; Daniel |

Repository | CRAN |

Date/Publication | 2020-11-24 14:10:02 UTC |

suggests | AER , afex , aod , BayesFactor , bayestestR , bbmle , betareg , BGGM , biglm , blavaan , blme , brms , censReg , cgam , coxme , cplm , crch , effectsize , emmeans , estimatr , feisr , fixest , gam , gamlss , gamm4 , gbm , gee , geepack , GLMMadaptive , glmmTMB , gmnl , httr , ivreg , JM , knitr , lavaan , lfe , lme4 , logistf , MASS , Matrix , MCMCglmm , mgcv , mice , mlogit , multgee , nlme , nnet , ordinal , parameters , plm , pscl , quantreg , rmarkdown , rms , robustbase , robustlmm , rstanarm , rstudioapi , speedglm , spelling , splines , statmod , survey , survival , testthat , tripack , truncreg , VGAM |

imports | methods , stats , utils |

depends | R (>= 3.5) |

Contributors | Dominique Makowski, Indrajeet Patil, Philip Waggoner, Mattan S. Ben-Shachar |

#### Include our badge in your README

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