see

see: An R Package for Visualizing Statistical Models - Published in JOSS (2021)

https://github.com/easystats/see

Keywords

Keywords from Contributors

Scientific Fields

Repository

:art: Visualisation toolbox for beautiful and publication-ready figures

README.Rmd

---
output: github_document
bibliography: paper/paper.bib
csl: apa.csl
---

# see: Model Visualisation Toolbox for 'easystats' and 'ggplot2' 

```{r, echo=FALSE, warning=FALSE, message=FALSE}
library(see)

knitr::opts_chunk$set(
  dpi = 150,
  collapse = TRUE,
  out.width = "100%",
  fig.path = "man/figures/",
  warning = FALSE,
  message = FALSE
)
```

[![DOI](https://joss.theoj.org/papers/10.21105/joss.03393/status.svg)](https://doi.org/10.21105/joss.03393)
[![downloads](https://cranlogs.r-pkg.org/badges/see)](https://cran.r-project.org/package=see)
[![total](https://cranlogs.r-pkg.org/badges/grand-total/see)](https://cranlogs.r-pkg.org/)

***"Damned are those who believe without seeing"***

*easystats* is a collection of packages that operate in synergy to provide a consistent and intuitive syntax when working with statistical models in the R programming language [@base2021]. Most *easystats* packages return comprehensive numeric summaries of model parameters and performance. The *see* package complements these numeric summaries with a host of functions and tools to produce a range of publication-ready visualizations for model parameters, predictions, and performance diagnostics. As a core pillar of *easystats*, the *see* package helps users to utilize visualization for more informative, communicable, and well-rounded scientific reporting.



# Installation

[![CRAN](https://www.r-pkg.org/badges/version/see)](https://cran.r-project.org/package=see) [![see status badge](https://easystats.r-universe.dev/badges/see)](https://easystats.r-universe.dev) [![R-CMD-check](https://github.com/easystats/see/workflows/R-CMD-check/badge.svg?branch=main)](https://github.com/easystats/see/actions) [![codecov](https://codecov.io/gh/easystats/see/branch/main/graph/badge.svg)](https://app.codecov.io/gh/easystats/see)

The *see* package is available on CRAN, while its latest development version is available on R-universe (from _rOpenSci_).

Type | Source | Command
---|---|---
Release | CRAN | `install.packages("see")`
Development | r-universe | `install.packages("see", repos = "https://easystats.r-universe.dev")`
Development | GitHub | `remotes::install_github("easystats/see")`

Once you have downloaded the package, you can then load it using:

```{r}
library("see")
```

> **Tip**
>
> Instead of `library(see)`, use `library(easystats)`.
> This will make all features of the  easystats-ecosystem available.
>
> To stay updated, use `easystats::install_latest()`.

# Plotting functions for 'easystats' packages

[![Documentation](https://img.shields.io/badge/documentation-see-orange.svg?colorB=E91E63)](https://easystats.github.io/see/)
[![Blog](https://img.shields.io/badge/blog-easystats-orange.svg?colorB=FF9800)](https://easystats.github.io/blog/posts/)
[![Features](https://img.shields.io/badge/features-see-orange.svg?colorB=2196F3)](https://easystats.github.io/see/reference/index.html)


Below we present one or two plotting methods for each *easystats* package, but many other methods are available. Interested readers are encouraged to explore the range of examples on the package [website](https://easystats.github.io/see/articles/).

## [parameters](https://github.com/easystats/parameters)

The *parameters* package converts summaries of regression model objects into data frames [@Lüdecke2020parameters]. The *see* package can take this transformed object and, for example, create a dot-and-whisker plot for the extracted regression estimates simply by passing the `parameters` class object to `plot()`.

```{r parameters1}
library(parameters)
library(see)

model <- lm(wt ~ am * cyl, data = mtcars)

plot(parameters(model))
```

As *see* outputs objects of class `ggplot`, *ggplot2* functions can be added as layers to the plot the same as with all other *ggplot2* visualizations. For example, we might add a title using `labs()` from *ggplot2*.

```{r parameters2}
library(parameters)
library(see)

model <- lm(wt ~ am * cyl, data = mtcars)

plot(parameters(model)) +
  ggplot2::labs(title = "A Dot-and-Whisker Plot")
```

Plotting functions for the **parameters** package are demonstrated [in this vignette](https://easystats.github.io/see/articles/parameters.html).

## [bayestestR](https://github.com/easystats/bayestestR)

Similarly, for Bayesian regression model objects, which are handled by the *bayestestR* package [@Makowski2019], the *see* package provides special plotting methods relevant for Bayesian models (e.g., Highest Density Interval, or *HDI*). Users can fit the model and pass the model results, extracted via *bayestestR*, to `plot()`.

```{r bayestestR}
library(bayestestR)
library(rstanarm)
library(see)

set.seed(123)
model <- stan_glm(wt ~ mpg, data = mtcars, refresh = 0)
result <- hdi(model, ci = c(0.5, 0.75, 0.89, 0.95))

plot(result)
```

Plotting functions for the **bayestestR** package are demonstrated [in this vignette](https://easystats.github.io/see/articles/bayestestR.html).

## [performance](https://github.com/easystats/performance)

The *performance* package is primarily concerned with checking regression model assumptions [@Lüdecke2020performance]. The *see* package offers tools to visualize these assumption checks, such as the normality of residuals. Users simply pass the fit model object to the relevant *performance* function (`check_normality()` in the example below). Then, this result can be passed to `plot()` to produce a *ggplot2* visualization of the check on normality of the residuals.

```{r performance}
library(performance)
library(see)

model <- lm(wt ~ mpg, data = mtcars)
check <- check_normality(model)

plot(check, type = "qq")
```

Plotting functions for the **performance** package are demonstrated [in this vignette](https://easystats.github.io/see/articles/performance.html).

## [effectsize](https://github.com/easystats/effectsize)

The *effectsize* package computes a variety of effect size metrics for fitted models to assesses the practical importance of observed effects [@Ben-Shachar2020]. In conjunction with *see*, users are able to visualize the magnitude and uncertainty of effect sizes by passing the model object to the relevant *effectsize* function (`omega_squared()` in the following example), and then to `plot()`.

```{r effectsize}
library(effectsize)
library(see)

model <- aov(wt ~ am * cyl, data = mtcars)

plot(omega_squared(model))
```

Plotting functions for the **effectsize** package are demonstrated [in this vignette](https://easystats.github.io/see/articles/effectsize.html).

## [modelbased](https://github.com/easystats/modelbased)

The *modelbased* package computes model-based estimates and predictions from fitted models [@Makowski2020modelbased]. *see* provides methods to quickly visualize these model predictions. For the following example to work, you need to have installed the *emmeans* package first.

```{r modelbased1}
library(modelbased)
library(see)

data(mtcars)
mtcars$gear <- as.factor(mtcars$gear)
model <- lm(mpg ~ wt * gear, data = mtcars)

predicted <- estimate_expectation(model, data = "grid")
plot(predicted, show_data = TRUE)
```

One can also visualize *marginal means* (i.e., the mean at each factor level averaged over other predictors) using `estimate_means()`, that is then passed to `plot()`.

```{r modelbased2, error=TRUE}
means <- estimate_means(model)

plot(means)
```

Plotting functions for the **modelbased** package are demonstrated [in this vignette](https://easystats.github.io/see/articles/modelbased.html).

## [correlation](https://github.com/easystats/correlation)

The *correlation* package provides a unified syntax and human-readable code to carry out many types of correlation analysis [@Makowski2020]. A user can run `summary(correlation(data))` to create a construct a correlation matrix for the variables in a dataframe. With *see*, this matrix can be passed to `plot()` to visualize these correlations in a correlation matrix.

```{r correlation, error=FALSE}
library(correlation)
library(see)

results <- summary(correlation(iris))

plot(results, show_data = "points")
```

Plotting functions for the **correlation** package are demonstrated [in this vignette](https://easystats.github.io/see/articles/correlation.html).

# Themes

### Modern

```{r}
library(ggplot2)

ggplot(iris, aes(x = Sepal.Width, y = Sepal.Length, color = Species)) +
  geom_point2() +
  theme_modern()
```

### Lucid

```{r}
library(ggplot2)

p <- ggplot(iris, aes(x = Sepal.Width, y = Sepal.Length, color = Species)) +
  geom_point2()

p + theme_lucid()
```

### Blackboard

```{r}
p + theme_blackboard()
```

### Abyss

```{r}
p + theme_abyss()
```

# Palettes

This is just one example of the available palettes. See [this vignette](https://easystats.github.io/see/articles/seecolorscales.html) for a detailed overview of palettes and color scales.

### Material design

```{r}
p1 <- ggplot(iris, aes(x = Species, y = Sepal.Length, fill = Species)) +
  geom_boxplot() +
  theme_modern(axis.text.angle = 45) +
  scale_fill_material_d()

p2 <- ggplot(iris, aes(x = Species, y = Sepal.Length, fill = Species)) +
  geom_violin() +
  theme_modern(axis.text.angle = 45) +
  scale_fill_material_d(palette = "ice")

p3 <- ggplot(iris, aes(x = Petal.Length, y = Petal.Width, color = Sepal.Length)) +
  geom_point2() +
  theme_modern() +
  scale_color_material(discrete = FALSE)
```

## Multiple plots

The `plots()` function allows us to plot the figures side by side.

```{r}
plots(p1, p2, p3, n_columns = 2)
```

The `plots()` function can also be used to add **tags** (*i.e.*, labels for subfigures).

```{r}
plots(p1, p2, p3,
  n_columns = 2,
  tags = paste("Fig. ", 1:3)
)
```

# Geoms

## Better looking points

`geom_points2()` and `geom_jitter2()` allow points without borders and contour.

```{r, fig.width=9.5, fig.height=5.8}
normal <- ggplot(iris, aes(x = Petal.Width, y = Sepal.Length)) +
  geom_point(size = 8, alpha = 0.3) +
  theme_modern()

new <- ggplot(iris, aes(x = Petal.Width, y = Sepal.Length)) +
  geom_point2(size = 8, alpha = 0.3) +
  theme_modern()

plots(normal, new, n_columns = 2)
```



## Half-violin Half-dot plot

Create a half-violin half-dot plot, useful for visualising the distribution and the sample size at the same time.

```{r}
ggplot(iris, aes(x = Species, y = Sepal.Length, fill = Species)) +
  geom_violindot(fill_dots = "black") +
  theme_modern() +
  scale_fill_material_d()
```

## Radar chart (Spider plot)

```{r}
library(datawizard)

# prepare the data in tidy format
data <- iris |>
  datawizard::data_group("Species") |>
  datawizard::data_summary(
    Sepal.Length = mean(Sepal.Length),
    Sepal.Width = mean(Sepal.Width),
    Petal.Length = mean(Petal.Length),
    Petal.Width = mean(Petal.Width)
  ) |>
  datawizard::reshape_longer(c(
    "Sepal.Length",
    "Sepal.Width",
    "Petal.Length",
    "Petal.Width"
  ))

data |>
  ggplot(aes(
    x = name,
    y = value,
    color = Species,
    group = Species,
    fill = Species
  )) +
  geom_polygon(linewidth = 1, alpha = 0.1) +
  coord_radar() +
  theme_radar()
```

# Contributing and Support

In case you want to file an issue or contribute in another way to the package, please follow [this guide](https://github.com/easystats/see/blob/master/.github/CONTRIBUTING.md). For questions about the functionality, you may either contact us via email or also file an issue.

# Code of Conduct

Please note that this project is released with a
[Contributor Code of Conduct](https://easystats.github.io/see/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms.

# References

Owner

JOSS Publication

see: An R Package for Visualizing Statistical Models

Published

August 06, 2021

DOI

10.21105/joss.03393

Volume 6, Issue 64, Page 3393

Authors

Daniel Lüdecke
University Medical Center Hamburg-Eppendorf, Germany

Indrajeet Patil
Center for Humans and Machines, Max Planck Institute for Human Development, Berlin, Germany

Mattan S. Ben-Shachar
Ben-Gurion University of the Negev, Israel

Brenton M. Wiernik
Department of Psychology, University of South Florida, USA

Philip Waggoner
University of Chicago, USA

Dominique Makowski
Nanyang Technological University, Singapore

Editor

Frederick Boehm

Tags

easystats ggplot2 ggplot2-extension

View PDF Review Thread Software Archive

Papers & Mentions

GitHub Events

Committers

Last synced: 10 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages