PlotXTabs2 {CGPfunctions}

Bivariate bar (column) charts with statistical tests

Description

Bivariate bar charts for nominal and ordinal data with (optionally) statistical details included in the plot as a subtitle.

Usage

PlotXTabs2(
  data,
  x,
  y,
  counts = NULL,
  results.subtitle = TRUE,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  plottype = "percent",
  xlab = NULL,
  ylab = "Percent",
  legend.title = NULL,
  legend.position = "right",
  labels.legend = NULL,
  sample.size.label = TRUE,
  data.label = "percentage",
  label.text.size = 4,
  label.fill.color = "white",
  label.fill.alpha = 1,
  bar.outline.color = "black",
  x.axis.orientation = NULL,
  conf.level = 0.95,
  k = 2,
  perc.k = 0,
  mosaic.offset = 0.003,
  mosaic.alpha = 1,
  bf.details = FALSE,
  bf.display = "regular",
  sampling.plan = "jointMulti",
  fixed.margin = "rows",
  prior.concentration = 1,
  paired = FALSE,
  ggtheme = ggplot2::theme_bw(),
  package = "RColorBrewer",
  palette = "Dark2",
  direction = 1,
  ggplot.component = NULL
)

Arguments

data

A dataframe or tibble containing the 'x' and 'y' variables.

x

The variable to plot on the X axis of the chart.

y

The variable to segment the **columns** and test for independence.

counts

If the dataframe is based upon counts rather than individual rows for observations, 'counts' must contain the name of variable that contains the counts. See 'HairEyeColor' example.

results.subtitle

Decides whether the results of statistical tests are displayed as a subtitle (Default: TRUE). If set to FALSE, no subtitle.

title

The text for the plot title.

subtitle

The text for the plot subtitle. **N.B** if statistical results are requested through 'results.subtitle = TRUE' the results will have precedence.

caption

The text for the plot caption. Please note the interaction with 'bf.details'.

plottype

one of four options "side", "stack", "mosaic" or "percent"

xlab

Custom text for the 'x' axis label (Default: 'NULL', which will cause the 'x' axis label to be the 'x' variable).

ylab

Custom text for the 'y' axis label (Default: '"Percent"'). Set to 'NULL' for no label.

legend.title

Title text for the legend.

legend.position

The position of the legend '"none"', '"left"', '"right"', '"bottom"', '"top"' (Default: '"right"').

labels.legend

A character vector with custom labels for levels of the 'y' variable displayed in the legend.

sample.size.label

Logical that decides whether sample size information should be displayed for each level of the grouping variable 'y' (Default: 'TRUE').

data.label

Character decides what information needs to be displayed on the label in each bar segment. Possible options are '"percentage"' (default), '"counts"', '"both"'.

label.text.size

Numeric that decides size for bar labels (Default: '4').

label.fill.color

Character that specifies fill color for bar labels (Default: 'white').

label.fill.alpha

Numeric that specifies fill color transparency or '"alpha"' for bar labels (Default: '1' range '0' to '1').

bar.outline.color

Character specifying color for bars (default: '"black"').

x.axis.orientation

The orientation of the 'x' axis labels one of "slant" or "vertical" to change from the default horizontal orientation (Default: 'NULL' which is horizontal).

conf.level

Scalar between 0 and 1. If unspecified, the defaults return lower and upper confidence intervals (0.95).

k

Number of digits after decimal point (should be an integer) (Default: k = 2) for statistical results.

perc.k

Numeric that decides number of decimal places for percentage labels (Default: '0').

mosaic.offset

Numeric that decides size of spacing between mosaic blocks (Default: '.003' which is very narrow). "reasonable" values probably lie between .05 and .001

mosaic.alpha

Numeric that controls the "alpha" level of the mosaic plot blocks (Default: '1' which is essentially no "fading"). Values must be in the range 0 to 1 see: 'ggplot2::aes_colour_fill_alpha'

bf.details

Logical that decides whether to display additional information from the Bayes Factor test in the caption (default:'FALSE'). This will take precedence over any text you enter as a 'caption'.

bf.display

Character that determines how the Bayes factor value is is displayed. The default is simply the number rounded to 'k'. Other options include "sensible", "log" and "support".

sampling.plan

the sampling plan (see details in ?contingencyTableBF).

fixed.margin

(see details in ?contingencyTableBF).

prior.concentration

(see details in ?contingencyTableBF).

paired

Not used yet.

ggtheme

A function, ggplot2 theme name. Default value is ggplot2::theme_bw(). Any of the ggplot2 themes, or themes from extension packages are allowed (e.g., hrbrthemes::theme_ipsum(), etc.).

package

Name of package from which the palette is desired as string or symbol.

palette

Name of palette as string or symbol.

direction

Either '1' or '-1'. If '-1' the palette will be reversed.

ggplot.component

A ggplot component to be added to the plot prepared by ggstatsplot. Default is NULL. The argument should be entered as a function. If the given function has an argument axes.range.restrict and if it has been set to TRUE, the added ggplot component might not work as expected.

Author(s)

Chuck Powell, Indrajeet Patil

Examples

# for reproducibility
set.seed(123)

# simplest possible call with the defaults
PlotXTabs2(
  data = mtcars,
  y = vs,
  x =  cyl
)  

# more complex call
PlotXTabs2(
  data = datasets::mtcars,
  y = vs,
  x = cyl,
  bf.details = TRUE,
  labels.legend = c("0 = V-shaped", "1 = straight"),
  legend.title = "Engine Style",
  legend.position = "right",
  title = "The perenial mtcars example",
  palette = "Pastel1"
)

PlotXTabs2(
  data = as.data.frame(HairEyeColor),
  y = Eye,
  x = Hair,
  counts = Freq
)

## Not run: 
# mosaic plot requires ggmosaic 0.2.2 or higher from github
PlotXTabs2(
  data = mtcars,
  x = vs,
  y =  am, 
  plottype = "mosaic", 
  data.label = "both", 
  mosaic.alpha = .9, 
  bf.display = "support", 
  title = "Motorcars Mosaic Plot VS by AM"
)

## End(Not run)