Visualize jst_* result objects or plot variables directly from a data frame

Unified plotting function. Can be called in three ways:

Usage

jplot(x, which = "core", ...)

# Default S3 method
jplot(
  x,
  ...,
  by = NULL,
  type = NULL,
  line = FALSE,
  equation = TRUE,
  r2 = TRUE,
  band = "ci",
  subset = NULL,
  labels = NULL,
  numeric = NULL,
  categorical = NULL,
  count = NULL,
  facet = NULL
)

# S3 method for class 'jst_lm'
jplot(
  x,
  which = "core",
  focal = NULL,
  at = "zero",
  equation = TRUE,
  r2 = TRUE,
  ...
)

# S3 method for class 'jst_logistic'
jplot(x, which = "core", focal = NULL, at = "zero", ...)

# S3 method for class 'jst_ttest'
jplot(x, which = "core", ...)

# S3 method for class 'jst_anova'
jplot(x, which = "core", ...)

# S3 method for class 'jst_corr'
jplot(x, which = "core", ...)

# S3 method for class 'jst_crosstab'
jplot(x, which = "core", ...)

# S3 method for class 'jst_desc'
jplot(x, which = "core", ...)

# S3 method for class 'jst_freq'
jplot(x, which = "core", ...)

Arguments

x: A result object from one of the package's analysis functions (result-object form), or a data frame (data-first form).
which: Character vector. core (default), all, or one or more specific plot names valid for the object's class. (Result-object form only.)
...: Additional arguments: for the result-object form these are passed to class-specific methods; for the data-first form these are unquoted variable names (1 or 2).
by: Unquoted variable name for group-coloring (data-first form).
type: Character. Plot type override for the data-first form. One of histogram, density, bar, scatter, box, grouped_bar. If NULL (default), auto-detected from variable types; density is never the automatic choice.
line: Controls a line overlay on data-first scatter plots. One of FALSE (default; no line), TRUE (alias for lm), lm, loess, connect.
equation: Logical. If TRUE (default), displays the equation in the subtitle for line = "lm" scatter plots (data-first form) or jst_lm fit plots (result-object form).
r2: Logical. If TRUE (default), displays R-squared in the subtitle alongside the equation.
band: Character. Uncertainty band type for line = "lm" scatter plots. One of ci (default; 95% confidence band for the mean, flares at the ends), pi (95% prediction interval for individual observations), see (constant-width band at +/- t*SEE; useful for teaching homoskedasticity), none.
subset: Optional unquoted logical expression to filter cases for this call only (data-first form). Written in R syntax and checked the way jsubset() checks a filter: subset = NOT(Age < 40), for example, is refused with the corrected subset = !(Age < 40) shown (see jsubset for a translation table).
labels: Character or NULL. Variable label display mode (data-first and formula forms): one of "both", "names", "labels", "legend", or "legend.bottom". "names" uses variable names as axis/legend titles; "labels" uses each variable's label as its axis/legend title instead (falling back to the name when unlabelled) and prints no console legend; "legend" and "legend.bottom" keep names on the axes and print a console label legend. "both" is accepted but currently renders as "names" on plots (the "name: label" form for plot titles is deferred to a later phase). NULL (default) defers to joutput()'s variable.id setting. Not a logical.
numeric: Optional. Plotted variables to treat as continuous for this call (the per-call counterpart of jnumeric()), named bare or in quotes, several with c(): numeric = Education. In jplot() a variable's class chooses the geometry, so this forces numeric handling (histogram for a single variable; scatter / numeric axis in the formula and two-variable forms). Applies to the plotted variables only, not the by grouping variable.
categorical: Optional. Plotted variables to treat as categorical for this call (the per-call counterpart of jdummy() for plotting purposes), named bare or in quotes, several with c(). Forces categorical geometry (bar for a single variable; box / categorical axis in the formula form). A variable cannot be listed in both categorical and numeric/count.
count: Optional. Plotted variables to treat as counts for this call (the per-call counterpart of jcount()), named bare or in quotes, several with c(). A count is numeric-like for plotting, so it draws the same as numeric; it is provided for symmetry with the other analysis functions.
facet: Unquoted variable name for one panel per group (variable-list form: a histogram, density plot, bar chart or grouped bar chart), bare or in quotes. See Details.
focal: Unquoted name of the independent variable to place on the x-axis for jst_lm / jst_logistic fit and probability plots. Defaults to the first independent variable in the model that is not dummy-coded, since a fitted line needs a numeric axis. A dummy-coded categorical variable is named as the formula names it (focal = Region), and is drawn with its categories along the axis: the predicted outcome (or probability) at each with its 95% confidence interval, the cases behind them.
at: Character string or named list specifying where non-focal independent variables are held when drawing the fitted line in jst_lm / jst_logistic methods. One of zero (default), mean, mixed (categorical at 0, interval at mean), or a named list list(Var1 = value, ...). A term computed from the focal variable alone, or from it and variables held – a square, I(x^2); a log, log(x + 1) – is not held: it is computed from the focal variable at each point of the line, so the line of a model with a squared term is a curve.

Value

Invisibly, a single ggplot object if one plot is produced, or a named list of ggplot objects if multiple are produced (result-object form). Invisibly returns the ggplot object for the data-first form.

Details

Result-object form: Pass a result object returned by one of the package's analysis functions. Produces appropriate plots for each class of result (see valid plot names below).

Formula form (for plots that distinguish DV from IV): Pass a formula as the first argument, followed optionally by a data frame, given either positionally or as data = : jplot(WellbeingScore ~ Income, data = community) is the same plot as jplot(WellbeingScore ~ Income, community). Used for scatterplots and boxplots, consistent with the formula syntax of jlm(), jaov(), and jt(). The DV on the left of ~ goes on the y-axis; the IV on the right goes on the x-axis. Only single-IV formulas are supported here; for multi-IV models, fit with jlm() and pass the result to jplot(). Each side names a variable as it stands: a computed term such as log(Income) or I(Age > 40) is refused, so create it as a variable of the data first.

Variable-list form (for distributions and counts): Pass a data frame followed by one or two unquoted variable names. The data frame is given either positionally or as data = : jplot(data = community, Age) is the same plot as jplot(community, Age). Used for histograms (1 numeric), bar charts (1 categorical), and grouped bar charts (2 categorical). Calls that would otherwise auto-detect to a scatter or boxplot produce a helpful error directing you to the formula form.

A labelled variable with a few categories, such as Region – six values or fewer with at least one of them labelled, or whole numbers from 0 to 6 – is drawn as categories when nothing says otherwise: alone, as a bar chart; beside another variable in the variable-list form, as one of a grouped bar chart's two variables or as a boxplot's groups (the error then gives the formula line); on the right of a formula, as the groups of a boxplot. This is for the plot only: the analysis functions read such a variable as numbers unless it is registered or asserted (see jdummy). numeric = or count =, a jnumeric() or jcount() registration, a type, or line, band, equation or r2 (which only a scatter plot draws) keeps the numbers.

Supports pipeline integration (jsubset, jcomplete, per-call subset), grouping via by = , and regression lines with equation/R-squared/band annotations.

Valid plot names by class (for the result-object form):

jst_lm: fit, predicted, effects, coef, residuals, qq, scale, cooks, leverage
jst_logistic: probability, logit (the same fitted line on the log-odds scale, where it is straight: the linear predictor and its 95% band against the focal variable, the cases as a rug along the axis, those with the outcome at the top and the others at the bottom; at a dummy-coded focal variable's categories, the log-odds at each), roc, calibration, binned, cooks, leverage, coef
jst_ttest, jst_anova: box (the default), qq (a normal Q-Q plot of the standardized residuals: each case's distance from its group's mean, or for a paired test each pair's difference from the mean difference)
jst_corr: heatmap, scatter (scatter requires exactly 2 variables in the correlation)
jst_crosstab: bar

The shortcut keyword core (default) produces a curated default set for the class; all produces every plot the class supports.

For a jst_lm result, effects draws one plot per variable of the model: a term computed from a variable (I(x^2), log(x + 1), I(x * z)) is drawn in that variable's plot, following it along the axis, with the other variables held as at sets them. A dummy-coded categorical variable is one variable, drawn as one plot: its categories along the axis, labeled as the coefficient table labels them, with the predicted outcome at each and its 95% confidence interval. A variable the fit dropped as an exact linear combination of the others has no effect to draw. For a model with no predictors (y ~ 1), the plots that need a predictor, or that are drawn against the fitted values or the leverage, are left out with a note.

Valid plot types for the data-first form: histogram, density, bar, scatter, box, grouped_bar. A density plot is the histogram's alternative for a numeric variable – its kernel density estimate, one curve, or one per group of by = laid over each other – and is drawn only when asked for with type = "density".

In the variable-list form facet = draws one panel per group of the variable named, with the groups' value labels as the panel titles: the alternative to by = when the groups are many, since colors laid over each other stop being readable past a handful. The two can be combined, by = coloring the groups of one variable within each panel of another. A scatterplot or boxplot by groups takes by = in the formula form; facet = is refused there.

Valid line values: FALSE (default), TRUE (alias for lm), lm, loess, connect.

Valid band values: ci (default confidence band around the regression line, flares at the ends), pi (prediction interval for individual observations, wider), see (constant-width +/- t*SEE band illustrating the homoskedasticity assumption), none (no band).

Methods (by class)

jplot(default): the default method: a scatter or box plot from a formula (DV ~ IV), or a histogram or bar chart from a data frame and one or more variables.
jplot(jst_lm): diagnostic, coefficient (forest), and fitted-effect plots for a jlm() linear-regression result.
jplot(jst_logistic): predicted-probability (S-curve) and coefficient plots for a jlogistic() result.
jplot(jst_ttest): a group-comparison box plot for a jt() result, with the group means marked; which = "qq" draws the normal Q-Q plot of its residuals.
jplot(jst_anova): a group-comparison box plot for a jaov() result, with the group means marked; which = "qq" draws the normal Q-Q plot of its residuals.
jplot(jst_corr): a heat-map of the correlation matrix for a jcorr() result, or a scatter plot for a single pair.
jplot(jst_crosstab): a grouped bar chart of cell counts for a jcrosstab() result.
jplot(jst_desc): (planned) direct plotting of a jdesc() result is not yet available; this method points you to the data-first form, for example jplot(data, Variable).
jplot(jst_freq): (planned) direct plotting of a jfreq() result is not yet available; this method points you to the data-first form, for example jplot(data, Variable).

Examples

# Result-object form
m <- jlm(WellbeingScore ~ Income + Age, community)
#> Linear Regression
#> 
#> Case Processing    Excluded  Remaining
#>     Original             --        103
#>     Auto-listwise         6         97
#>     Analysis N           --         97
#> 
#> Missing data   From 103   %
#>     Income
#>       Missing      6     5.8
#> --------------------------------------
#> 
#> Coefficients
#>                 b      SE     t      β      p
#> -----------  ------  -----  -----  -----  -----
#> (Intercept)  24.815  3.749  6.620         <.001
#> Income        0.000  0.000  6.813  0.564  <.001
#> Age           0.181  0.082  2.208  0.183   .030
#> 
#> Outcome: WellbeingScore
#> 
#> R-squared: 0.411    Adjusted R-squared: 0.398
#> Residual Standard Error: 9.013
#> 
#> F-statistic: 32.729 on 2 and 94 DF, p-value: <.001
#> Sum of Squares:
#>   Regression: 5317.416
#>   Residual:   7635.945
#>   Total:      12953.361
#> 
jplot(m)                            # core diagnostics + fit plot




jplot(m, which = "coef")            # coefficient forest plot
#> `height` was translated to `width`.

jplot(m, which = "fit", focal = Age, at = "mean")


# Formula form (scatter and box)
jplot(WellbeingScore ~ Income, community)               # scatter
#> Scatterplot: WellbeingScore and Income
#> 
#> Analysis N: 97 (6 Excluded)
#> 

jplot(WellbeingScore ~ Income, community, line = "lm")  # + regression line
#> Scatterplot: WellbeingScore and Income
#> 
#> Analysis N: 97 (6 Excluded)
#> 

jplot(WellbeingScore ~ Income, community, line = "lm", band = "see")
#> Scatterplot: WellbeingScore and Income
#> 
#> Analysis N: 97 (6 Excluded)
#> 

jplot(WellbeingScore ~ Income, community, by = Volunteer, line = "lm")
#> Scatterplot: WellbeingScore and Income by Volunteer
#> 
#> Analysis N: 97 (6 Excluded)
#> 
#> Ignoring unknown labels:
#> • fill : "Volunteer"


# Boxplot: a labelled variable with a few categories, such as Region,
# is drawn as groups on the right of the formula (for the plot only)
jplot(WellbeingScore ~ Region, community)
#> Boxplot: WellbeingScore and Region
#> 
#> Analysis N: 103
#> 

# categorical = asserts it in any variable; numeric = keeps the codes
jplot(WellbeingScore ~ Region, community, categorical = "Region")
#> Boxplot: WellbeingScore and Region
#> 
#> Analysis N: 103
#> 


# Variable-list form (distributions and counts)
jplot(community, Age)                      # histogram
#> Histogram: Age
#> 
#> Analysis N: 103
#> 

jplot(data = community, Age)               # the same, data frame as data =
#> Histogram: Age
#> 
#> Analysis N: 103
#> 

jplot(community, Region)                   # bar chart
#> Bar Chart: Region
#> 
#> Analysis N: 103
#> 

jplot(community, Region, Volunteer)        # grouped bar chart
#> Grouped Bar Chart: Region and Volunteer
#> 
#> Analysis N: 103
#> 


# Using juse() default (omit the data frame in either form)
juse(community)
#> Default data frame set to: community
jplot(WellbeingScore ~ Income)               # scatter
#> Scatterplot: WellbeingScore and Income
#> Using default data frame: community
#> 
#> Analysis N: 97 (6 Excluded)
#> 

jplot(WellbeingScore ~ Income, line = "lm")  # + regression line
#> Scatterplot: WellbeingScore and Income
#> Using default data frame: community
#> 
#> Analysis N: 97 (6 Excluded)
#> 

jplot(Age)                                   # histogram
#> Histogram: Age
#> Using default data frame: community
#> 
#> Analysis N: 103
#> 

jplot(Region, Volunteer)                     # grouped bar chart
#> Grouped Bar Chart: Region and Volunteer
#> Using default data frame: community
#> 
#> Analysis N: 103
#>