Skip to content

README.md

Latest commit

 

History

History
370 lines (277 loc) · 8.26 KB

README.md

File metadata and controls

370 lines (277 loc) · 8.26 KB

plotutilityscript

Utility plotting functions for microbiome, groundwater, and ecological community datasets.

Features

Currently includes:

  • nested_abundance_plot()
    • Creates nested abundance bar plots from long-format data.
    • Supports arbitrary nested facet levels using ggh4x.
    • Automatically separates higher-level groups, such as Season, into bordered panels.
    • Uses a shared y-axis and shared legend.
    • Combines panels using patchwork.
    • Supports custom fill palettes and ggplot2 fill scales.
    • Supports proportional panel widths when split groups have different numbers of bars.
    • Supports user-defined ggplot2 theme modifications.
    • Allows control of strip text size, bar width, x-axis padding, y-axis padding, and split-panel spacing.

Nested abundance plot

Installation

Install directly from GitHub

Install the required package:

install.packages("remotes")

Install plotutilityscript:

remotes::install_github(
  "gamalielcabria/plotutilityscript"
)

Load the package:

library(plotutilityscript)

Install from a local clone

Clone the repository:

git clone https://github.com/gamalielcabria/plotutilityscript.git

Install from source:

install.packages(
  "~/path/to/plotutilityscript",
  repos = NULL,
  type = "source"
)

Load the package:

library(plotutilityscript)

Dependencies

The package automatically installs required dependencies:

  • ggplot2
  • dplyr
  • purrr
  • rlang
  • ggh4x
  • patchwork
  • cowplot
  • grid

Input Data Requirements

The input data should be in long format, with one row per observation.

Example:

Season Site.ID Timepoint Replicate Genus Abundance
Spring Site_A W1 R1 Genus_A 0.25
Spring Site_A W1 R1 Genus_B 0.12
Spring Site_A W1 R1 Genus_C 0.08

The function requires columns for:

  • x-axis values, such as replicate or duplicate sample ID
  • y-axis values, such as relative abundance
  • fill grouping, such as OTU, Genus, or Phylum
  • split grouping, such as Season
  • nested facet variables, such as Site.ID and Timepoint

Basic Example

This is the simplest use case. It uses the default style and splits the plot by Season.

library(plotutilityscript)

p <- nested_abundance_plot(
  data = plot_df,
  x_col = Replicate,
  y_col = Abundance,
  fill_col = Genus,
  split_col = Season,
  nested_cols = c("Site.ID", "Timepoint")
)

p

More Customized Example

This example uses more of the available customization options.

library(plotutilityscript)

p <- nested_abundance_plot(
  # Data and required mappings
  data = plot_df,
  x_col = Replicate,      # x-axis categories; here, replicate samples
  y_col = Abundance,      # bar height; here, relative abundance
  fill_col = Genus,       # stacked bar fill groups
  split_col = Season,     # creates one bordered plot block per season
  nested_cols = c("Site.ID", "Timepoint"), # nested facet strips within season

  # Color Palette
  palette = wes16,

  # Axis and legend labels
  y_label = "Relative abundance",
  fill_label = "OTU",

  # Y-axis scale
  y_limits = c(0, 1),              # fixed y-axis range
  y_breaks = seq(0, 1, 0.2),       # y-axis tick marks
  show_y_axis = FALSE,

  # Split-panel layout
  split_width_mode = "proportional", # season widths follow number of bars
  min_split_width = 1,               # minimum relative width per season
  season_gap = 0.02,                 # space between season plot blocks
  layout_widths = c(0.04, 1, 0.25),  # y-axis, main plot, legend widths

  # Bar and panel spacing
  x_expand = c(0.05, 0),       # fallback x-axis expansion
  x_padding = c(0, 1),         # left/right padding inside facets
  y_padding = c(0, 0),         # bottom/top y-axis padding
  plot_margin = ggplot2::margin(8, 12, 8, 8), # space inside season border

  # Strip text styling
  strip_text_size = c(12, 8, 6), # strip text sizes for nested levels
  strip_text_face = c("bold", "plain", "plain"), # For both size and face, the order starts from highest level to the smallest levels

  # Extra ggplot theme modifications
  plot_theme = ggplot2::theme(
    axis.text.x = ggplot2::element_text(
      angle = 0,
      hjust = 0.5,
      size = 7
    ),
    legend.text = ggplot2::element_text(size = 6),
    legend.title = ggplot2::element_text(size = 8)
  )
)

p

ggsave("plot.png", plot = p, width = 12, height = 6, dpi = 300, units = "in")

What this customized example does

  • x_col = Replicate places replicate IDs on the x-axis.
  • y_col = Abundance uses abundance values as the bar heights.
  • fill_col = Genus stacks bars by genus.
  • split_col = Season creates one bordered plot block per season.
  • nested_cols = c("Site.ID", "Timepoint") creates nested facet strips within each season.
  • split_width_mode = "proportional" makes season panels wider when they contain more bars.
  • min_split_width = 1 sets the minimum relative width for smaller season panels.
  • x_padding = c(0.5, 1) adds horizontal breathing room inside each facet.
  • y_padding = c(0, 0) keeps the y-axis tightly aligned from 0 to 1.
  • strip_text_size = c(12, 8, 6) controls nested strip text sizes.
  • plot_margin = ggplot2::margin(8, 12, 8, 8) adds space between the outer season border and plot contents.
  • layout_widths = c(0.04, 1, 0.25) controls the relative widths of the y-axis, main plot, and legend.
  • plot_theme applies additional ggplot2 theme changes, such as rotated x-axis text and smaller legend text.

Here is an example of the code above: Nested Abundance 2

Function Reference

nested_abundance_plot()

Create a nested abundance bar plot with:

  • Shared y-axis
  • Shared legend
  • Dynamic split panels
  • Nested facet strips
  • Automatic patchwork layout
  • Optional proportional split-panel widths
  • Optional palette and fill-scale customization
  • Optional theme customization

Required arguments

nested_abundance_plot(
  data,
  x_col,
  y_col,
  fill_col,
  split_col,
  nested_cols
)

Common optional arguments

nested_abundance_plot(
  data = plot_df,
  x_col = Replicate,
  y_col = Abundance,
  fill_col = Genus,
  split_col = Season,
  nested_cols = c("Site.ID", "Timepoint"),

  y_label = "Relative abundance",
  fill_label = "Genus",

  split_width_mode = "proportional",
  min_split_width = 1,

  bar_width = 0.95,
  x_padding = c(0.5, 1),
  y_padding = c(0, 0.03),

  strip_text_size = c(12, 8),
  strip_text_face = c("bold", "plain"),

  plot_margin = ggplot2::margin(8, 12, 8, 8),

  plot_theme = ggplot2::theme(
    axis.text.x = ggplot2::element_text(angle = 45, hjust = 1)
  )
)

Colour Customization

Named palette

my_palette <- c(
  Bacillota = "#f38400",
  Bacteroidota = "#be0032",
  Pseudomonadota = "#0067a5"
)

p <- nested_abundance_plot(
  data = plot_df,
  x_col = Duplicate,
  y_col = RelAbund,
  fill_col = Phylum,
  split_col = Season,
  nested_cols = c("Location", "Week"),
  palette = my_palette
)

ggplot2 fill scale

p <- nested_abundance_plot(
  data = plot_df,
  x_col = Duplicate,
  y_col = RelAbund,
  fill_col = Phylum,
  split_col = Season,
  nested_cols = c("Location", "Week"),
  fill_scale = ggplot2::scale_fill_brewer(palette = "Set3")
)

If both palette and fill_scale are supplied, fill_scale is used.

Theme Customization

Use plot_theme to modify ggplot2 theme elements.

p <- nested_abundance_plot(
  data = plot_df,
  x_col = Duplicate,
  y_col = RelAbund,
  fill_col = Phylum,
  split_col = Season,
  nested_cols = c("Location", "Week"),
  plot_theme = ggplot2::theme(
    axis.text.x = ggplot2::element_text(angle = 45, hjust = 1),
    legend.text = ggplot2::element_text(size = 7),
    legend.title = ggplot2::element_text(size = 9)
  )
)

Saving a Plot

ggplot2::ggsave(
  filename = "nested_abundance_plot.png",
  plot = p,
  width = 12,
  height = 6,
  dpi = 300,
  units = "in"
)

If proportional panel widths are used and some groups contain many more bars than others, increase the output width.

License

MIT License

Copyright (c) Gamaliel Cabria