visualisation_matrix {modelbased}

Create a reference grid

Description

This function is an alias (another name) for the insight::get_datagrid() function. Same arguments apply.

Usage

visualisation_matrix(x, ...)

## S3 method for class 'data.frame'
visualisation_matrix(
  x,
  by = "all",
  target = NULL,
  at = NULL,
  factors = "reference",
  numerics = "mean",
  preserve_range = FALSE,
  reference = x,
  ...
)

## S3 method for class 'numeric'
visualisation_matrix(x, ...)

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

Arguments

x

An object from which to construct the reference grid.

...

Arguments passed to or from other methods (for instance, length or range to control the spread of numeric variables.).

by

Indicates the focal predictors (variables) for the reference grid and at which values focal predictors should be represented. If not specified otherwise, representative values for numeric variables or predictors are evenly distributed from the minimum to the maximum, with a total number of length values covering that range (see 'Examples'). Possible options for by are:

• "all", which will include all variables or predictors.

• a character vector of one or more variable or predictor names, like c("Species", "Sepal.Width"), which will create a grid of all combinations of unique values. For factors, will use all levels, for numeric variables, will use a range of length length (evenly spread from minimum to maximum) and for character vectors, will use all unique values.

• a list of named elements, indicating focal predictors and their representative values, e.g. by = list(Sepal.Length = c(2, 4), Species = "setosa").

• a string with assignments, e.g. by = "Sepal.Length = 2" or by = c("Sepal.Length = 2", "Species = 'setosa'") - note the usage of single and double quotes to assign strings within strings.

There is a special handling of assignments with brackets, i.e. values defined inside [ and ⁠]⁠.For numeric variables, the value(s) inside the brackets should either be

• two values, indicating minimum and maximum (e.g. by = "Sepal.Length = [0, 5]"), for which a range of length length (evenly spread from given minimum to maximum) is created.

• more than two numeric values by = "Sepal.Length = [2,3,4,5]", in which case these values are used as representative values.

• a "token" that creates pre-defined representative values:

  • for mean and -/+ 1 SD around the mean: "x = [sd]"

  • for median and -/+ 1 MAD around the median: "x = [mad]"

  • for Tukey's five number summary (minimum, lower-hinge, median, upper-hinge, maximum): "x = [fivenum]"

  • for terciles, including minimum and maximum: "x = [terciles]"

  • for terciles, excluding minimum and maximum: "x = [terciles2]"

  • for quartiles, including minimum and maximum: "x = [quartiles]"

  • for quartiles, excluding minimum and maximum: "x = [quartiles2]"

  • for minimum and maximum value: "x = [minmax]"

  • for 0 and the maximum value: "x = [zeromax]"

For factor variables, the value(s) inside the brackets should indicate one or more factor levels, like by = "Species = [setosa, versicolor]". Note: the length argument will be ignored when using brackets-tokens.

The remaining variables not specified in by will be fixed (see also arguments factors and numerics).

target, at

Deprecated name. Please use by instead.

factors

Type of summary for factors. Can be "reference" (set at the reference level), "mode" (set at the most common level) or "all" to keep all levels.

numerics

Type of summary for numeric values. Can be "all" (will duplicate the grid for all unique values), any function ("mean", "median", ...) or a value (e.g., numerics = 0).

preserve_range

In the case of combinations between numeric variables and factors, setting preserve_range = TRUE will drop the observations where the value of the numeric variable is originally not present in the range of its factor level. This leads to an unbalanced grid. Also, if you want the minimum and the maximum to closely match the actual ranges, you should increase the length argument.

reference

The reference vector from which to compute the mean and SD. Used when standardizing or unstandardizing the grid using effectsize::standardize.

Value

Reference grid data frame.

Examples

library(modelbased)

# Add one row to change the "mode" of Species
data <- rbind(iris, iris[149, ], make.row.names = FALSE)

# Single variable is of interest; all others are "fixed"
visualisation_matrix(data, by = "Sepal.Length")
visualisation_matrix(data, by = "Sepal.Length", length = 3)
visualisation_matrix(data, by = "Sepal.Length", range = "ci", ci = 0.90)
visualisation_matrix(data, by = "Sepal.Length", factors = "mode")

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

# with list-style at-argument
visualisation_matrix(data, by = list(Sepal.Length = c(1, 3), Species = "setosa"))

# Standardize
vizdata <- visualisation_matrix(data, by = "Sepal.Length")
standardize(vizdata)