Package {mSigPlot}

Add peak labels with arrows to a ggplot

Description

Adds ggrepel::geom_text_repel() labels with closed arrowhead segments pointing from labels to the top bars in a bar plot. Used to identify dominant channels.

Usage

add_peak_labels(
  plot,
  df,
  x_col,
  y_col,
  label_col,
  num_peak_labels = 0,
  peak_label_cex = 0.7,
  base_size = 11,
  arrow_length = 0.01,
  label_threshold_denominator = 7
)

Arguments

Value

The ggplot object with labels added (or unchanged if num_peak_labels == 0).

Add a plot title, inside the panel (annotate) or above it (ggtitle)

Description

If title_outside_plot is FALSE, places plot_title inside the plot area via annotate("text", ...) at y = ymax * y_frac — the plot_ID83 style. If TRUE, places it above the plot via ggtitle() + theme(plot.title = ...). Title size is always plot_title_cex * base_size (points), normalized to mm for annotate.

Usage

add_plot_title(
  p,
  plot_title,
  title_outside_plot,
  plot_title_cex,
  base_size,
  ymax,
  x = 1,
  y_frac = 7.4/8,
  hjust = 0
)

Arguments

Value

The ggplot object with the title added.

plot_DBS144, plot_DBS144_pdf, plot_DBS78, plot_DBS78_pdf, plot_ID166, plot_ID166_pdf, plot_ID476, plot_ID476_pdf, plot_ID476_right, plot_ID476_right_pdf, plot_ID83, plot_ID83_pdf, plot_ID89, plot_ID89_pdf, plot_SBS12, plot_SBS12_pdf, plot_SBS192, plot_SBS192_pdf, plot_SBS288, plot_SBS96, plot_SBS96_pdf

Description

Plot functions for SBS, DBS, and indel mutational signature catalogs as bar charts. Most functions return ggplot2 objects; plot_SBS288 returns a patchwork object.

Usage

plot_DBS144(
  catalog,
  plot_title = NULL,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = TRUE,
  show_axis_title_y = TRUE,
  ylim = NULL,
  base_size = 11,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  axis_text_x_cex = 0.5,
  axis_title_x_cex = 0.8,
  axis_title_y_cex = 0.8,
  axis_text_y_cex = 0.7,
  grid = FALSE
)

plot_DBS144_pdf(catalog, filename, ...)

plot_DBS78(
  catalog,
  plot_title = NULL,
  grid = FALSE,
  upper = TRUE,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = FALSE,
  show_axis_title_y = TRUE,
  ylim = NULL,
  base_size = 11,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  count_label_cex = 0.9,
  class_label_cex = 0.8,
  axis_text_x_cex = 0.5,
  axis_title_x_cex = 0.8,
  axis_title_y_cex = 0.8,
  axis_text_y_cex = 0.7,
  show_counts = NULL,
  num_peak_labels = 0,
  peak_label_cex = 0.7
)

plot_DBS78_pdf(catalog, filename, ...)

plot_ID166(
  catalog,
  plot_title = NULL,
  grid = FALSE,
  upper = TRUE,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = FALSE,
  show_axis_title_y = TRUE,
  ylim = NULL,
  base_size = 11,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  title_x = 0.4,
  count_label_cex = 0.9,
  block_label_cex = 0.65,
  class_label_cex = 0.8,
  axis_text_x_cex = 0.5,
  bottom_label_cex = 0.65,
  axis_title_x_cex = 0.8,
  axis_title_y_cex = 0.8,
  axis_text_y_cex = 0.7,
  show_counts = NULL,
  num_peak_labels = 0,
  peak_label_cex = 0.7
)

plot_ID166_pdf(catalog, filename, ...)

plot_ID476(
  catalog,
  plot_title = NULL,
  base_size = 11,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  title_x = 0.4,
  count_label_cex = 0.9,
  class_label_cex = 0.8,
  axis_text_x_cex = 0.5,
  axis_title_x_cex = 0.8,
  axis_title_y_cex = 0.8,
  axis_text_y_cex = 0.7,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = TRUE,
  show_axis_title_y = TRUE,
  show_counts = NULL,
  num_peak_labels = 4,
  peak_label_cex = 0.7,
  label_threshold_denominator = 7,
  vline_labels = c(),
  simplify_labels = FALSE,
  plot_complex = FALSE,
  grid = FALSE
)

plot_ID476_pdf(catalog, filename, ...)

plot_ID476_right(
  catalog,
  plot_title = NULL,
  base_size = 11,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  title_x = 0.4,
  count_label_cex = 0.9,
  class_label_cex = 0.8,
  axis_text_x_cex = 0.5,
  axis_title_x_cex = 0.8,
  axis_title_y_cex = 0.8,
  axis_text_y_cex = 0.7,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = TRUE,
  show_axis_title_y = TRUE,
  show_counts = NULL,
  num_peak_labels = 3,
  peak_label_cex = 0.7,
  label_threshold_denominator = 7,
  vline_labels = c(),
  simplify_labels = TRUE,
  plot_complex = FALSE,
  grid = FALSE
)

plot_ID476_right_pdf(catalog, filename, ...)

plot_ID83(
  catalog,
  plot_title = NULL,
  grid = FALSE,
  upper = TRUE,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = TRUE,
  show_axis_title_y = TRUE,
  ylim = NULL,
  base_size = 11,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  title_x = 0.4,
  count_label_cex = 0.9,
  block_label_cex = 0.65,
  class_label_cex = 0.8,
  axis_text_x_cex = 0.5,
  bottom_label_cex = 0.65,
  axis_title_x_cex = 0.8,
  axis_title_y_cex = 0.8,
  axis_text_y_cex = 0.7,
  show_counts = NULL,
  num_peak_labels = 0,
  peak_label_cex = 0.7
)

plot_ID83_pdf(catalog, filename, ...)

plot_ID89(
  catalog,
  plot_title = NULL,
  upper = TRUE,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = TRUE,
  show_axis_title_y = TRUE,
  ylim = NULL,
  base_size = 11,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  title_x = 0.4,
  count_label_cex = 0.9,
  block_label_cex = 0.65,
  class_label_cex = 0.8,
  axis_text_x_cex = 0.5,
  axis_title_x_cex = 0.8,
  axis_title_y_cex = 0.8,
  axis_text_y_cex = 0.7,
  show_counts = NULL,
  plot_complex = FALSE,
  num_peak_labels = 0,
  peak_label_cex = 0.7,
  grid = FALSE
)

plot_ID89_pdf(catalog, filename, ...)

plot_SBS12(
  catalog,
  plot_title = NULL,
  abundance = NULL,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = FALSE,
  show_axis_title_y = TRUE,
  ylim = NULL,
  base_size = 11,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  axis_text_x_cex = 0.5,
  axis_title_x_cex = 0.8,
  axis_title_y_cex = 0.8,
  axis_text_y_cex = 0.7,
  grid = FALSE
)

plot_SBS12_pdf(catalog, filename, ...)

plot_SBS192(
  catalog,
  plot_title = NULL,
  grid = FALSE,
  upper = TRUE,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = FALSE,
  show_axis_title_y = TRUE,
  ylim = NULL,
  base_size = 11,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  title_x = 0,
  count_label_cex = 0.9,
  class_label_cex = 0.8,
  axis_text_x_cex = 0.5,
  axis_title_x_cex = 0.8,
  axis_title_y_cex = 0.8,
  axis_text_y_cex = 0.7,
  show_counts = NULL,
  num_peak_labels = 0,
  peak_label_cex = 0.7
)

plot_SBS192_pdf(catalog, filename, ...)

plot_SBS288(
  catalog,
  plot_title = NULL,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  ...
)

plot_SBS288_pdf(catalog, filename, ...)

plot_SBS96(
  catalog,
  plot_title = NULL,
  grid = FALSE,
  upper = TRUE,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = FALSE,
  show_axis_title_y = TRUE,
  ylim = NULL,
  base_size = 11,
  plot_title_cex = 1,
  title_outside_plot = FALSE,
  title_x = 0,
  count_label_cex = 0.9,
  class_label_cex = 0.8,
  axis_text_x_cex = 0.5,
  axis_title_x_cex = 0.8,
  axis_title_y_cex = 0.8,
  axis_text_y_cex = 0.7,
  show_counts = NULL,
  num_peak_labels = 0,
  peak_label_cex = 0.7
)

plot_SBS96_pdf(catalog, filename, ...)

Arguments

Details

Functions in this family:

• plot_SBS96, plot_SBS192: SBS trinucleotide context

• plot_DBS78: DBS dinucleotide substitutions

• plot_DBS144: DBS with transcription strand

• plot_SBS12: SBS strand bias summary (collapses 192 to 12 bars)

• plot_SBS288: SBS with three-strand context

• plot_ID166: Indel genic/intergenic (166 channels)

• plot_ID83: Indel COSMIC classification (83 channels)

• plot_ID89: Indel Koh classification (89 channels)

• plot_ID476, plot_ID476_right: Indel with flanking context (476 channels)

Each has a corresponding ⁠_pdf()⁠ variant for multi-sample PDF export.

Value

Plot functions return a ggplot2 object (or a patchwork object for plot_SBS288), or NULL with a warning if the catalog is invalid (wrong size or row names). PDF functions return NULL invisibly (called for side effect of creating a PDF file), or stop with an error if the catalog is invalid.

Examples

set.seed(1)
sig <- runif(144)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$DBS144
plot_DBS144(sig, plot_title = "Example DBS144 signature")

set.seed(1)
sig <- runif(78)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$DBS78
plot_DBS78(sig, plot_title = "Example DBS78 signature")

set.seed(1)
sig <- runif(166)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$ID166
plot_ID166(sig, plot_title = "Example ID166 signature")


set.seed(1)
sig <- runif(476)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$ID476
plot_ID476(sig, plot_title = "Example ID476")



set.seed(1)
sig <- runif(476)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$ID476
plot_ID476_right(sig, plot_title = "Example ID476 right panel")


set.seed(1)
sig <- runif(83)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$ID
plot_ID83(sig, plot_title = "Example ID83")

set.seed(1)
sig <- runif(89)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$ID89
plot_ID89(sig, plot_title = "Example ID89")

set.seed(1)
sig <- runif(192)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$SBS192
plot_SBS12(sig, plot_title = "Example SBS12 strand bias")

set.seed(1)
sig <- runif(192)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$SBS192
plot_SBS192(sig, plot_title = "Example SBS192 signature")


set.seed(1)
sig <- runif(288)
names(sig) <- catalog_row_order()$SBS288
plot_SBS288(sig, plot_title = "Example SBS288")


# Plot a random SBS96 signature (proportions summing to 1)
set.seed(1)
sig <- runif(96)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$SBS96
plot_SBS96(sig, plot_title = "Example SBS96 signature")

Convert base_size (points) to mm for geom_text sizing

Description

Convert base_size (points) to mm for geom_text sizing

Usage

base_mm(base_size)

Arguments

Value

Numeric base size in mm.

Return catalog row orders for all supported catalog types

Description

Returns a named list containing the canonical row ordering for each catalog type. These are used for validation and ordering of mutation catalogs. The result is cached after the first call.

Usage

catalog_row_order()

Details

Row names use a compact 4-letter format for SBS types: e.g. ACAA encodes the trinucleotide context as ⁠<5' base><ref><3' base><alt>⁠. SBS288 row names add a strand prefix: T:ACAA (transcribed), U:ACAA (untranscribed), N:ACAA (non-transcribed).

Catalogs with "stapled" row names (e.g. ⁠A[C>A]A⁠ for SBS96, ⁠T:A[C>A]A⁠ for SBS288) are automatically converted to compact format by normalize_catalog() before validation, so both formats are accepted by all SBS plotting functions. (Only SBS functions use stapled row names.)

Value

A named list with elements: SBS96, SBS192, SBS288, SBS1536, DBS78, DBS136, DBS144, ID (83-category COSMIC indels), ID166, ID89, ID476.

Examples

cro <- catalog_row_order()
head(cro$SBS96)
length(cro$DBS78)

Detect y-axis type from data and attributes

Description

Determines the y-axis type for a catalog. Checks the y_axis_type_attr attribute first; if absent, infers from data values and optional ylim.

Usage

detect_y_axis_type(values, y_axis_type_attr = NULL, ylim = NULL)

Arguments

Value

Character string: one of "counts", "proportion", "muts_per_million", or "density_proportion".

plot_DBS136, plot_DBS136_pdf, plot_SBS1536, plot_SBS1536_pdf

Description

Plot functions for SBS and DBS mutational signature catalogs as heatmaps. Plot functions return patchwork objects (composites of ggplot2 panels).

Usage

plot_DBS136(
  catalog,
  plot_title = NULL,
  base_size = 11,
  plot_title_cex = 1.2,
  axis_text_cex = 0.8,
  strip_text_cex = 1,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = TRUE,
  show_axis_title_y = TRUE
)

plot_DBS136_pdf(catalog, filename, ...)

plot_SBS1536(
  catalog,
  plot_title = NULL,
  base_size = 11,
  plot_title_cex = 1.2,
  axis_text_cex = 0.8,
  strip_text_cex = 1,
  show_axis_text_x = TRUE,
  show_axis_text_y = TRUE,
  show_axis_title_x = TRUE,
  show_axis_title_y = TRUE
)

plot_SBS1536_pdf(catalog, filename, ...)

Arguments

Details

Functions in this family:

• plot_SBS1536: SBS pentanucleotide context (1536 channels)

• plot_DBS136: DBS heatmap (136 channels, 10 4x4 panels)

Each has a corresponding ⁠_pdf()⁠ variant for multi-sample PDF export.

Value

Plot functions return a patchwork object (a composite of ggplot2 panels), or NULL with a warning if the catalog is invalid (wrong size or row names). Note: adding ggplot2 layers with + (e.g. + ggtitle()) applies only to the last sub-plot, not the composite; use patchwork::plot_annotation() for titles/captions on the whole composition. PDF functions return NULL invisibly (called for side effect of creating a PDF file), or stop with an error if the catalog is invalid.

Examples

set.seed(1)
sig <- runif(136)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$DBS136
plot_DBS136(sig, plot_title = "Example DBS136")


set.seed(1)
sig <- runif(1536)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$SBS1536
plot_SBS1536(sig, plot_title = "Example SBS1536")

Derive ID89 figure-axis labels from canonical IndelType strings

Description

Rewrites the canonical ID89 channel names from catalog_row_order()$ID89 into the compact tick-label style used on the x-axis of plot_ID89().

Usage

id89_figlabels(indel_types)

Arguments

Details

Single-base channels (matching Del(C), Del(T), Ins(C), Ins(T)): the Del(..)/Ins(..) wrapper and the ⁠:R⁠ prefix are dropped, and any open-ended repeat range ⁠(N,)⁠ is rewritten as ⁠(N+)⁠.

Multi-base channels (longer Del/Ins/MH rows): leading ⁠Del(⁠/⁠Ins(⁠ is rewritten to ⁠L(⁠, a leading open-ended length ⁠(N,)⁠ is space-padded to ⁠(N, )⁠, a trailing R(N,) becomes ⁠R(N+)⁠, a trailing M(N,) is space-padded to M(N, ), and all colons are removed.

The "Complex" channel is returned unchanged.

Value

A character vector of the same length as indel_types, giving the figure-label form of each channel name.

Examples

id89_figlabels(c(
  "[Del(C):R1]A",
  "Del(C):R(6,9)",
  "Del(2,4):R1",
  "Del(2,):U(1,2):R(5,)",
  "Del(6,):M(4,)",
  "Complex"
))

Normalize catalog input to a 1-column data.frame

Description

Internal helper that coerces a catalog from any supported input type (numeric vector, matrix, data.table, tibble, data.frame) to a 1-column data.frame with validated row names. Stapled SBS row names (e.g. ⁠A[C>A]A⁠ for SBS96, ⁠T:A[C>A]A⁠ for SBS288) are automatically converted to compact format before validation.

Usage

normalize_catalog(
  catalog,
  expected_nrow,
  canonical_order = NULL,
  type_label = ""
)

Arguments

Value

A 1-column data.frame, or NULL if row names do not match canonical order.

Return order for DBS136 plotting

Description

Returns the 160-element character vector mapping the 136-row DBS catalog into a 160-position layout (10 groups of 16 for 10 heatmap images). 24 entries are not in the DBS136 catalog and serve as NA placeholders.

Usage

order_DBS136_for_plotting()

Value

A 160-element character vector of row names for DBS136 heatmap layout.

Generic multi-sample PDF export for bar plots

Description

Creates a multi-page PDF with plots arranged in a grid. Each page contains up to plots_per_page plots in a single column.

Usage

plot_catalog_pdf(
  catalog,
  filename,
  plot_fn,
  plots_per_page = 5,
  width = 12,
  height = 14,
  ...
)

Arguments

Value

NULL invisibly.

plot_guess, plot_guess_pdf

Description

Automatically select the appropriate plotting function based on the number of rows in the catalog.

Usage

plot_guess(catalog, ...)

plot_guess_pdf(catalog, filename, ...)

Arguments

Details

plot_guess() plots a single sample. plot_guess_pdf() creates a multi-page PDF file containing plots for multiple samples, arranged with 5 samples per page (except heatmap types: 1 per page). Uses Cairo for high-quality PDF rendering.

Value

plot_guess() returns a plot object. The exact class depends on the dispatched function: most return a ggplot object; SBS288, DBS136, and SBS1536 return patchwork objects. Note: adding ggplot2 layers with + to a patchwork object (e.g. + ggtitle()) applies only to the last sub-plot, not the composite; use patchwork::plot_annotation() instead. plot_guess_pdf() returns NULL invisibly (called for side effect of creating a PDF file).

See Also

plot_SBS96(), plot_SBS192(), plot_SBS288(), plot_SBS1536(), plot_DBS78(), plot_DBS136(), plot_DBS144(), plot_ID166(), plot_ID476(), plot_ID89(), plot_ID83()

Examples

# Auto-detect a 96-channel catalog and dispatch to plot_SBS96
set.seed(1)
sig <- runif(96)
sig <- sig / sum(sig)
names(sig) <- catalog_row_order()$SBS96
plot_guess(sig, plot_title = "Auto-detected SBS96")


sig <- matrix(runif(96 * 3), nrow = 96)
rownames(sig) <- catalog_row_order()$SBS96
colnames(sig) <- paste0("Sig", 1:3)
plot_guess_pdf(sig, filename = tempfile(fileext = ".pdf"))

Internal helper functions shared across plot functions

Description

Internal helper functions shared across plot functions

Prepare indel data for plotting

Description

Merges a catalog vector with an indel type table, producing a long-format data frame ready for ggplot. Used by plot_ID476, plot_ID476_right, and plot_ID89.

Usage

prepare_indel_data(catalog, type_table)

Arguments

Value

Data frame with columns from type_table plus Sample and freq.

Return reorder vector for DBS144 plotting

Description

Returns the 132-element character vector used to reorder DBS144 catalog rows for paired strand display. Only 132 of 144 entries are included; the 12 self-complementary DBS types that lack strand distinction are omitted.

Usage

reorder_DBS144_for_plotting()

Value

A 132-element character vector of DBS144 row names in plotting order.

Return reorder vector for SBS192 plotting

Description

Returns the character vector used to reorder SBS192 catalog rows so transcribed and untranscribed strand entries alternate as pairs.

Usage

reorder_SBS192_for_plotting()

Value

A 192-element character vector of SBS192 row names in plotting order.

Resolve show_counts parameter

Description

If show_counts is NULL (auto), returns TRUE when catalog_type is "counts", FALSE otherwise. If explicitly set, returns the value unchanged.

Usage

resolve_show_counts(show_counts, catalog_type)

Arguments

Value

Logical.

Return the 476-channel indel type classification table

Description

Constructs a data frame mapping 476 indel channels to their type, class, and figure label. The result is cached after the first call.

Usage

type_476_indel_type()

Value

A 476-row data frame with columns: IndelType, Indel, Figlabel.

Convert stapled SBS96 row names to compact format

Description

Converts names like "A[C>A]T" to "ACTA" (compact ⁠<5' base><ref><3' base><alt>⁠ format).

Usage

unstaple_SBS96_rownames(stapled_names)

Arguments

Value

Character vector of compact 4-letter identifiers.