Statistic Plot

Visualizes data using various plot types such as bar plots, rose plots, ring plots, pie charts, trend plots, area plots, dot plots, sankey plots, chord plots, venn diagrams, and upset plots.

Usage

StatPlot(
  meta.data,
  stat.by,
  group.by = NULL,
  split.by = NULL,
  bg.by = NULL,
  flip = FALSE,
  NA_color = "grey",
  NA_stat = TRUE,
  keep_empty = FALSE,
  individual = FALSE,
  stat_level = NULL,
  plot_type = c("bar", "rose", "ring", "pie", "trend", "trend_alluvial", "area", "dot",
    "sankey", "chord", "venn", "upset"),
  venn_engine = c("ggVennDiagram", "venny"),
  venn_args = list(),
  stat_type = c("percent", "count", "value"),
  value.by = NULL,
  top_n = Inf,
  rank.by = c("absolute", "value"),
  complete_groups = NULL,
  value_cutoff = NULL,
  value_limits = NULL,
  value_midpoint = 0,
  value_legend_title = NULL,
  bar_fill = NULL,
  bar_width = 0.8,
  point_size = c(2.5, 7),
  character_width = 50,
  return_data = FALSE,
  position = c("stack", "dodge"),
  palette = "Chinese",
  palcolor = NULL,
  alpha = 1,
  bg_palette = "Chinese",
  bg_palcolor = NULL,
  bg_alpha = 0.2,
  label = FALSE,
  label_cutoff = NULL,
  label.size = 3.5,
  label.fg = "black",
  label.bg = "white",
  label.bg.r = 0.1,
  aspect.ratio = NULL,
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  legend.position = "right",
  legend.direction = "vertical",
  theme_use = "theme_this",
  theme_args = list(),
  x_text_angle = 45,
  grid_major = TRUE,
  grid_major_colour = "grey80",
  grid_major_linetype = 2,
  grid_major_linewidth = 0.3,
  combine = TRUE,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  force = FALSE,
  seed = 11
)

Arguments

meta.data

The data frame containing the data to be plotted.

stat.by

The column name(s) in meta.data specifying the variable(s) to be plotted.

group.by

The column name(s) in meta.data specifying the grouping variable(s). Default is NULL.

split.by

The column name in meta.data specifying the variable to split plots by. Default is NULL.

bg.by

The column name in meta.data specifying the background variable for bar plots.

flip

Whether to flip the plot. Default is FALSE.

NA_color

The color to use for missing values.

NA_stat

Whether to include missing values in the plot. Default is TRUE.

keep_empty

Whether to keep empty groups in the plot. Default is FALSE.

individual

Whether to plot individual groups separately. Default is FALSE.

stat_level

The level(s) of the variable(s) specified in stat.by to include in the plot. Default is NULL.

plot_type

The type of plot to create. Can be one of "bar", "rose", "ring", "pie", "trend", "trend_alluvial", "area", "dot", "sankey", "chord", "venn", or "upset".

venn_engine

The engine used when plot_type = "venn". Can be one of "ggVennDiagram" or "venny". Default is "ggVennDiagram". The "venny" engine supports 2 to 4 sets.

venn_args

A list of additional arguments passed to venny::venny when plot_type = "venn" and venn_engine = "venny". The data argument is generated internally and cannot be supplied here.

stat_type

The type of statistic to compute for the plot. Can be one of "percent", "count", or "value". Continuous value mode supports plot_type = "bar" and plot_type = "dot".

value.by

Numeric column used when stat_type = "value".

top_n

Maximum number of records retained per group and split in value mode. Default is Inf.

rank.by

Rank continuous values by absolute magnitude or signed value.

complete_groups

For value dot plots, retain every available group for a label selected in any group within the same split.

value_cutoff

Optional minimum absolute value.

value_limits

Optional continuous colour limits. Symmetric limits are inferred by default.

value_midpoint

Midpoint of the continuous colour scale.

value_legend_title

Legend title for continuous values.

bar_fill

Optional fixed fill used by value bars.

bar_width

Width of bars in value mode.

point_size

Size range for value dot plots.

character_width

Maximum wrapped label width in value mode.

return_data

Return the plot and prepared data in value mode.

position

The position adjustment for the plot. Can be one of "stack" or "dodge".

palette

The name of the color palette to use. Default is "Chinese".

palcolor

Custom colors to use instead of palette. Default is NULL.

alpha

The transparency level for the plot.

bg_palette

The name of the background color palette to use for bar plots.

bg_palcolor

The color to use in the background color palette.

bg_alpha

The transparency level for the background color in bar plots.

label

Whether to add labels on the plot. Default is FALSE.

label_cutoff

Optional minimum plotted value required to show a label. Labels are shown only for values strictly greater than this cutoff. For percentage plots, use proportions; for example, label_cutoff = 0.1 shows labels only for values greater than 10%. Default is NULL, which labels all values.

label.size

The size of the labels.

label.fg

The foreground color of the labels.

label.bg

The background color of the labels.

label.bg.r

The radius of the rounded corners of the label background.

aspect.ratio

Aspect ratio of the panel. Default is NULL.

title

The title of the plot. Default is NULL.

subtitle

The subtitle of the plot. Default is NULL.

xlab

The label for the x-axis. Default is NULL.

ylab

The label for the y-axis. Default is NULL.

legend.position

The position of the legend. Can be one of "none", "left", "right", "bottom", "top", or a two-element numeric vector. Default is "right".

legend.direction

The direction of the legend. Can be one of "vertical" or "horizontal". Default is "vertical".

theme_use

The theme to use for the plot. Default is "theme_this".

theme_args

Additional arguments to pass to the theme function. Default is list().

x_text_angle

Rotation angle for x-axis labels. Default is 45. Must be a finite number.

grid_major

Whether to show major panel grid lines. Default is TRUE.

grid_major_colour

Color of major panel grid lines.

grid_major_linetype

Linetype of major panel grid lines.

grid_major_linewidth

Line width of major panel grid lines.

combine

Whether to combine multiple plots into one. Default is TRUE.

nrow

Number of rows when combining plots. Default is NULL.

ncol

Number of columns when combining plots. Default is NULL.

byrow

Whether to fill plots by row when combining. Default is TRUE.

force

Whether to force plotting even when variables have more than 100 levels. Default is FALSE.

seed

Random seed for reproducibility. Default is 11.

Examples

set.seed(1)
meta_data <- data.frame(
  Type = factor(
    sample(c("A", "B", "C"),
      50,
      replace = TRUE,
      prob = c(0.5, 0.3, 0.2)
    )
  ),
  Group = factor(sample(c("X", "Y", "Z"), 50, replace = TRUE)),
  Batch = factor(sample(c("B1", "B2"), 50, replace = TRUE))
)
meta_data$Region <- factor(
  ifelse(meta_data$Group %in% c("X", "Y"), "R1", "R2"),
  levels = c("R1", "R2")
)

StatPlot(
  meta_data,
  stat.by = "Type",
  group.by = "Group",
  split.by = "Batch",
  plot_type = "bar",
  position = "dodge"
)


StatPlot(
  meta_data,
  stat.by = "Type",
  group.by = "Group",
  stat_type = "count",
  plot_type = "ring",
  position = "dodge"
)
#> Warning: Removed 1 row containing missing values or values outside the scale range
#> (`geom_col()`).


StatPlot(
  meta_data,
  stat.by = "Type",
  group.by = "Group",
  stat_type = "count"
)


StatPlot(
  meta_data,
  stat.by = "Type",
  plot_type = "pie"
)


StatPlot(
  meta_data,
  stat.by = "Type",
  group.by = "Group",
  stat_type = "count",
  plot_type = "area"
)


StatPlot(
  meta_data,
  stat.by = "Type",
  group.by = "Group",
  plot_type = "dot"
)


StatPlot(
  meta_data,
  stat.by = "Type",
  group.by = "Group",
  stat_type = "count",
  plot_type = "trend"
)


rank_data <- data.frame(
  Feature = paste0("Feature", 1:12),
  Group = rep(c("Control", "Treatment"), each = 6),
  Value = c(
    -2.4, 1.8, 1.2, -0.8, 0.6, 0.2,
    2.7, -2.1, 1.5, 0.9, -0.5, 0.3
  )
)

StatPlot(
  rank_data,
  stat.by = "Feature",
  value.by = "Value",
  group.by = "Group",
  stat_type = "value",
  plot_type = "bar",
  top_n = 4,
  flip = TRUE,
  palette = "RdBu"
)


StatPlot(
  rank_data,
  stat.by = "Feature",
  value.by = "Value",
  group.by = "Group",
  stat_type = "value",
  plot_type = "dot",
  top_n = 3,
  palette = "RdBu"
)


importance_data <- data.frame(
  Variable = paste0("Variable", 1:8),
  Importance = c(0.91, 0.78, 0.64, 0.52, 0.43, 0.31, 0.18, 0.09)
)
StatPlot(
  importance_data,
  stat.by = "Variable",
  value.by = "Importance",
  stat_type = "value",
  top_n = 5,
  flip = TRUE,
  bar_fill = "#3C8DBC"
)