Skip to contents

Make Splicejam Sashimi Figure

Source: R/splicejam-figure.R
splicejamFigure.Rd

Make Splicejam Sashimi Figure, with optional columns, gene model, subset region by coordinates or exon range.

Usage

splicejamFigure(
  sjenv = NULL,
  gene = "Myom1",
  gene_sd = NULL,
  filesDF = NULL,
  sample_id = NULL,
  use_exon_range = NULL,
  display_coords = NULL,
  facet_scales = "free_y",
  minJunctionScore = 10,
  scoreArcFactor = 0.6,
  use_ylim = NULL,
  base_size = 18,
  exonLabelSize = 14,
  label_junctions = TRUE,
  junction_alpha = 0.8,
  layout_ncol = 1,
  gene_panel_height = 1,
  do_plot = TRUE,
  use_memoise = FALSE,
  panel_method = c("patchwork", "cowplot", "plotly"),
  show_progress = TRUE,
  verbose = FALSE,
  ...
)

Arguments

sjenv

environment containing data produced by sashimiDataConstants(), specifically:

  • 'flatExonsByGene'

  • 'flatExonsByTx'

  • 'detectedTx'

  • 'detectedGenes'

  • tx2geneDF': data.frame with columns: 'gene_name', 'transcript_id'.

gene

character string with gene(s) to include in the flattened exon model.

gene_sd

list optional sashimi data output from prepareSashimi().

filesDF

data.frame with columns 'url', 'sample_id', 'type'. See prepareSashimi() for more information.

sample_id

character default NULL, optionally used to subset data to show only data for samples 'sample_id'.

use_exon_range

character vector with first and last exons to include in the genome coordinate range. Typically in the form: 'genesymbol_exon1', 'genesymbol_exon8b'

display_coords

numeric default NULL, with optional genome coordinates to use for the x-axis range.

facet_scales

character string passed to ggplot2::facet_wrap() argument 'scales'. Use 'fixed' to share the same y-axis range in each panel.

minJunctionScore

numeric default 10, passed to prepareSashimi() to require junctions with at least this score in order to be displayed. It is included here as a common argument to customize via prepareSashimi().

scoreArcFactor

numeric default 0.6 with default arc height added to the mean ribbon height, relative to its width. Default 0.6 ensures the ribbon rises at least 60% its width. Note argument 'scoreArcMinimum=100' can be adjusted through '...', and is not modified otherwise.

use_ylim

list of numeric y-axis limits, applied to each 'sample_id' panel. It uses ggh4x::scale_y_facet() and is currently experimental, working out the enquo mechanics.

base_size

numeric with base font size, default 18.

exonLabelSize

numeric with exon label size, default 14.

label_junctions

logical whether to label junctions with count/score, default TRUE.

junction_alpha

numeric default 0.8, default alpha for junction ribbon arcs. Higher values are more opaque, and less transparent.

layout_ncol

integer number of columns for output, default 1.

gene_panel_height

numeric relative panel height for the gene/transcript/exon model, relative to each sashimi panel with relative height 1. Default is 1.

do_plot

logical default TRUE, whether to render the plot.

use_memoise

logical default FALSE, whether to enable data cache methods with memoise.

panel_method

character method to assemble plot panels.

  • 'patchwork' (default) uses patchwork, and tends to have better handling of whitespace

  • 'cowplot' uses cowplot, but tends to have much more whitespace.

  • 'plotly' uses plotly to create an interactive figure.

show_progress

logical default TRUE, shows a progress bar using R terminal or Shiny, depending upon whether it is running inside Shiny.

  • Note: The progress is updated (somewhere) but not displayed unless the user (you) also enable it like this: progressr::handlers(global=TRUE)

  • The exception is when called from within sashimiAppServer(), which sets progressr::withShinyProgress() to enable it.

verbose

logical whether to print verbose output, default TRUE.

  • verbose == TRUE: prints major steps and elapsed time (default)

  • verbose == 2: as above, adding prepareSashimi() major steps

  • verbose == 3: as above, adding plotSashimi() and use_ylim in detail. Probably too verbose at that point.

...

additional arguments are passed to relevant functions: prepareSashimi(), gene2gg(), plotSashimi(). Some common examples:

  • show: passed to plotSashimi() to customize which features are displayed: 'coverage', 'junctions', 'junctionLabels'

  • fill_scheme: passed to plotSashimi() to define coloring by 'sample_id' (default) or 'exon'. When 'exon' the junctions are colored using 'junc_color' and 'junc_fill'.

Value

list with data elements:

  • cp_sashimi: the ggplot sashimi object

  • cp_sashimi_list: list of ggplot sashimi objects, per panel

  • cp_gene: the ggplot gene/transcript/exon object

  • cp_genes: list of ggplot gene/transcript/exon objects

  • gene_sd: the sashimi data from prepareSashimi()

  • layout_ncol: the layout ncol as used

  • use_ylim: the list of ylim as used

  • timings_df: data.frame for various processing steps, and duration in seconds.

  • cp: the final assembled ggplot figure

Details

This function is intended to mimic the functional steps performed by launchSashimiApp() which are aimed to provide a user-friendly interface to the many internal details.

Notable features:

  • 'use_exon_range': new argument allows zooming into a genome coordinate range using exon names.

  • gene model is shown and aligned by default, using cowplot.

  • 'layout_ncol': allows multiple columns with splicejam and gene/transcript/exon model.

Progress Bar

To enable a progress bar when using R console:

progressr::handlers(global=TRUE)

This command permits the progress bar to print to the R console, otherwise the progress is tracked but not displayed. In other words, it makes a grand announcement in an empty room, in the far corner of an abandoned building.

Todo:

  • Consider providing interactive output via ggplotly().

  • Expand the approach to permit multiple genes.

  • Apply memoise to plot data, as in launchSashimiApp()

  • Check when supplied with display_coords, no use_exon_range, it should (in theory) find gene(s) in that region, use them to assemble flattened exons, then generate figure with one or more genes.

See also

Other Splicejam core functions: launchSashimiApp(), sashimiDataConstants()

Examples

# By default, it loads farrisdata
sjenv <- sashimiDataConstants()
#> (17:52:54) 27Jul2026: get_fn_envir(): Variable 'gtf' not found
#> (17:52:54) 27Jul2026: get_fn_envir(): Variable 'empty_uses_farrisdata' found in parent.frame(1)
#> (17:52:54) 27Jul2026: get_fn_envir(): Variable 'use_memoise' found in parent.frame(1)
#> (17:52:54) 27Jul2026: get_fn_envir(): Variable 'verbose' found in parent.frame(1)
#> (17:52:54) 27Jul2026: sashimiDataConstants(): Defining default gtf file: 'ftp://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_mouse/release_M12/gencode.vM12.annotation.gtf.gz' from which tx2geneDF, exonsByTx, and cdsByTx will be derived.
#> (17:52:54) 27Jul2026: sashimiDataConstants(): Downloading gtf: 'ftp://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_mouse/release_M12/gencode.vM12.annotation.gtf.gz' to: 'gencode.vM12.annotation.gtf.gz'
#> (17:53:39) 27Jul2026: sashimiDataConstants(): Deriving txdb from gtf: 'gencode.vM12.annotation.gtf.gz' to store as: 'gencode.vM12.annotation.txdb'
#> Import genomic features from the file as a GRanges object ... 
#> OK
#> Prepare the 'metadata' data frame ... 
#> OK
#> Make the TxDb object ... 
#> Warning: The "phase" metadata column contains non-NA values for features of type
#>   stop_codon. This information was ignored.
#> Warning: genome version information is not available for this TxDb object
#> OK
#> (17:54:11) 27Jul2026: sashimiDataConstants(): Reloading cached exonsByTx from txdb
#> (17:54:11) 27Jul2026: sashimiDataConstants(): Reloading cached cdsByTx from txdb
#> (17:54:15) 27Jul2026: sashimiDataConstants(): Reloading cached flatExonsByGene using: exonsByTx,cdsByTx,detectedTx,tx2geneDF
#> (17:54:17) 27Jul2026: sashimiDataConstants(): flattenExonsByTx_m_cached:TRUE
#> (17:54:17) 27Jul2026: sashimiDataConstants(): Reloading cached flatExonsByTx using: exonsByTx,cdsByTx,detectedTx,tx2geneDF

sjenv$filesDF <- farrisdata::farris_sashimi_files_df
sjfig <- splicejamFigure(sjenv=sjenv, gene="Gria1", sample_id=c("CA2_CB", "CA2_DE"))


sjfig <- splicejamFigure(sjenv=sjenv, gene="Gria1", sample_id=c("CA2_CB", "CA2_DE"),
   use_exon_range=c("Gria1_exon13", "Gria1_exon16"), scoreArcFactor=0.4)


sjfig2 <- splicejamFigure(sjenv=sjenv, gene="Gria1", sample_id=c("CA2_CB", "CA2_DE"),
   layout_ncol=2,
   use_exon_range=c("Gria1_exon13", "Gria1_exon16"), scoreArcFactor=0.4)


sjfig3 <- splicejamFigure(sjenv=sjenv, gene="Gria1", sample_id=c("CA2_CB", "CA2_DE", "CA1_CB"),
   layout_ncol=2, use_memoise=TRUE,
   use_exon_range=c("Gria1_exon13", "Gria1_exon16"), scoreArcFactor=0.4)