Skip to contents

State Distribution Plot Over Time

Source: R/distribution_plot.R
distribution_plot.Rd

Draws how state proportions (or counts) evolve across time points. For each time column, tabulates how many sequences are in each state and renders the result as a stacked area (default) or stacked bar chart. Accepts the same inputs as sequence_plot.

Usage

distribution_plot(
  x,
  group = NULL,
  scale = c("proportion", "count"),
  geom = c("area", "bar"),
  na = TRUE,
  trim = NULL,
  trim_clusterwise = FALSE,
  state_colors = NULL,
  na_color = "grey90",
  frame = FALSE,
  width = NULL,
  height = NULL,
  main = NULL,
  show_n = TRUE,
  time_label = "Time",
  xlab = NULL,
  y_label = NULL,
  ylab = NULL,
  tick = NULL,
  ncol = NULL,
  nrow = NULL,
  combined = TRUE,
  legend = c("right", "bottom", "none"),
  legend_size = NULL,
  legend_title = NULL,
  legend_ncol = NULL,
  legend_border = NA,
  legend_bty = "n"
)

Arguments

x

Wide-format sequence data. Accepts the same inputs as sequence_plot: data.frame, matrix, netobject, net_clustering, netobject_group, net_mmm, or tna. When clustering info is available, one panel is drawn per cluster.

group

Optional grouping vector (length nrow(x)) producing one panel per group. NULL (default) falls back to the cluster assignments carried by a net_clustering / net_mmm / netobject_group input; supplying group overrides them.

scale

"proportion" (default) divides each column by its total so bands fill 0..1. "count" keeps raw counts.

geom

"area" (default) draws stacked polygons; "bar" draws stacked bars.

na

If TRUE (default), NA cells are shown as an extra band coloured na_color.

trim

Optional time-axis truncation, to stop a few long sequences from stretching the plot. NULL (default) keeps the full width. A fraction in (0, 1) drops everything past that quantile of sequence lengths (e.g. trim = 0.95); a value >= 1 is an absolute cut (trim = 50 keeps the first 50 time points). See sequence_plot.

trim_clusterwise

Grouped plots only, fractional trim only. FALSE (default) uses one pooled cutoff for every panel so the time axes stay aligned; TRUE crops each group to its own length quantile (panels can differ in width). See sequence_plot.

state_colors

Colours for the state fills. Either an unnamed vector, one colour per state in level order, or a named lookup (c(plan = "#0072B2")) where only the states you name are overridden and the rest keep the default Okabe-Ito palette. Names this plot does not draw are dropped with a message, so one palette can be reused across figures.

na_color

Colour for the NA band. Default "grey90".

frame

FALSE (default) draws no panel box; TRUE draws a box around each panel.

width, height

Optional device dimensions. See sequence_plot.

main

Plot title.

show_n

Append "(n = N)" (per-group when grouped) to the title.

time_label

X-axis label.

xlab

Alias for time_label.

y_label

Y-axis label. Defaults to "Proportion" or "Count" based on scale.

ylab

Alias for y_label.

tick

Show every Nth x-axis label. NULL = auto.

ncol, nrow

Facet grid dimensions. NULL = auto: ncol = ceiling(sqrt(G)), nrow = ceiling(G / ncol). Ignored when combined = FALSE.

combined

When TRUE (default), groups are arranged on one figure via graphics::layout(). When FALSE, each group is drawn on its own page (one full-size figure per group, with its own legend). Useful when you want each group at full size in knitr (fig.show = "asis") or to save each as a separate file. Single-group calls (G == 1) ignore this argument.

legend

Legend position: "right" (default), "bottom", or "none".

legend_size

Legend text size. NULL (default) auto-scales from device width (clamped to [0.65, 1.2]).

legend_title

Optional legend title.

legend_ncol

Number of legend columns.

legend_border

Swatch border colour.

legend_bty

"n" (borderless) or "o" (boxed).

Value

Invisibly, a list describing the drawn figure:

counts

Named list, one entry per group, each a (state x time point) numeric matrix of cell counts. Rows are named by levels; columns are the retained time points.

proportions

Same shape as counts, each column divided by its total.

levels

Character vector of state labels in plotting order, with "NA" appended when na = TRUE.

palette

Character vector of fill colours, parallel to levels.

groups

Character vector of group labels ("all" when ungrouped), parallel to counts / proportions.

See also

sequence_plot, build_clusters

Examples

distribution_plot(as.data.frame(trajectories))