SpliceWiz

Workflows

Standard Workflow

Build a reference, process alignment BAM files, collate sample data, filter low-confidence events, and perform differential alternative splicing analysis.

library(SpliceWiz)

# 1. Build the reference
ref_path <- file.path(tempdir(), "Reference")
buildRef(
  reference_path = ref_path,
  fasta = chrZ_genome(),
  gtf = chrZ_gtf(),
  ontologySpecies = "Homo sapiens"
)

# 2. Process BAM files
bams <- SpliceWiz_example_bams()
pb_path <- file.path(tempdir(), "pb_output")
processBAM(
  bamfiles = bams$path,
  sample_names = bams$sample,
  reference_path = ref_path,
  output_path = pb_path
)

# 3. Collate the experiment
expr <- findSpliceWizOutput(pb_path)
nxtse_path <- file.path(tempdir(), "NxtSE_output")
collateData(
  Experiment = expr,
  reference_path = ref_path,
  output_path = nxtse_path
)

# 4. Import the experiment
se <- makeSE(nxtse_path)

Input: Genome FASTA, GTF annotation, and raw BAM files. Output: A collated NxtSE object containing alternative splicing quantifications.

Novel Splicing Detection

Detect and analyze novel alternative splicing events using unannotated junctions and tandem reads.

library(SpliceWiz)

ref_path <- file.path(tempdir(), "Reference")
bams <- SpliceWiz_example_bams()
pb_path <- file.path(tempdir(), "pb_output")
expr <- findSpliceWizOutput(pb_path)

nxtse_path <- file.path(tempdir(), "NxtSE_output_novel")
collateData(
  Experiment = expr,
  reference_path = ref_path,
  output_path = nxtse_path,
  novelSplicing = TRUE,
  novelSplicing_requireOneAnnotatedSJ = TRUE,
  novelSplicing_minSamples = 3,
  novelSplicing_minSamplesAboveThreshold = 1,
  novelSplicing_countThreshold = 10,
  novelSplicing_useTJ = TRUE
)

se <- makeSE(nxtse_path)

Input: Processed BAM outputs and a reference path. Output: A collated NxtSE object containing identified and filtered novel splicing events.

Star Alignment And Reference Generation

Build a STAR genome index and align FASTQ files to generate BAMs using SpliceWiz wrappers.

library(SpliceWiz)

# Locate BAM files generated by STAR alignment
bams <- findBAMS(tempdir(), level = 1)

Input: Directory containing STAR-aligned BAM files. Output: A data frame of BAM file paths and sample names.

Coverage Visualization

The analysis and visualization of alternative splicing (AS) events from RNA sequencing data remains

library(SpliceWiz)

if (interactive()) {
  spliceWiz(demo = TRUE)
}

Input: Interactive R session. Output: Launches the SpliceWiz Shiny-based graphical user interface for coverage and alternative splicing visualization.

Novel Splicing Analysis

The analysis and visualization of alternative splicing (AS) events from RNA sequencing data remains

library(SpliceWiz)

ref_path <- file.path(tempdir(), "Reference")
buildRef(
  reference_path = ref_path,
  fasta = chrZ_genome(),
  gtf = chrZ_gtf()
)

bams <- SpliceWiz_example_bams()
pb_path <- file.path(tempdir(), "pb_output")
processBAM(
  bamfiles = bams$path,
  sample_names = bams$sample,
  reference_path = ref_path,
  output_path = pb_path
)

expr <- findSpliceWizOutput(pb_path)
nxtse_path <- file.path(tempdir(), "NxtSE_output_novel")
collateData(
  Experiment = expr,
  reference_path = ref_path,
  output_path = nxtse_path,
  novelSplicing = TRUE
)

se <- makeSE(nxtse_path)

Input: Genome FASTA, GTF, and BAM files. Output: An NxtSE object containing quantified annotated and novel alternative splicing events.

When to Use

• Quantifying alternative splicing events (ASEs) such as skipped exons (SE), mutually-exclusive exons (MXE), alternative 5'/3' splice sites (A5SS/A3SS), alternate first/last exons (AFE/ALE), and retained introns (IR/RI) from RNA-seq BAM files using processBAM().
• Detecting novel splicing events using unannotated junctions and tandem junction reads by setting novelSplicing = TRUE in collateData().
• Building a customized SpliceWiz reference from genome FASTA and GTF files using buildRef().
• Performing interactive differential alternative splicing analysis and coverage visualization using the Shiny GUI launched via spliceWiz().

When NOT to Use

• For alignment of raw FASTQ reads directly in R if STAR is not installed or if wrappers are not preferred; use external aligners instead.
• When system memory is extremely limited (e.g., < 8 GB RAM) for building human/mouse references or processing large BAM files; buildRef() and processBAM() require at least 8-16 GB RAM.
• For single-threaded collation of very large datasets where memory is a constraint unless lowMemoryMode = TRUE is specified in collateData().

Data Requirements

• Genome FASTA file (e.g., from chrZ_genome()) and gene annotation GTF file (e.g., from chrZ_gtf()).
• RNA-seq alignment BAM files (either read-name sorted or coordinate sorted) containing gapped junction reads.
• A sample annotation table (e.g., CSV format) mapping sample names to experimental conditions.

Key Parameters

• reference_path: Directory path where the SpliceWiz reference is built or stored.
• fasta: Path to the genome FASTA file used in buildRef().
• gtf: Path to the gene annotation GTF file used in buildRef().
• novelSplicing (FALSE): Logical parameter in collateData() to enable novel alternative splicing event discovery.
• novelSplicing_requireOneAnnotatedSJ (FALSE): Logical parameter in collateData() requiring novel junctions to share at least one annotated splice site.
• novelSplicing_minSamples (1): Minimum number of samples required to retain a novel junction.
• lowMemoryMode (FALSE): Logical parameter in collateData() to minimize RAM usage to ~8 GB during collation.
• n_threads (1): Number of threads for multi-threaded operations in processBAM() and collateData().

Best Practices

• Verify that OpenMP is enabled for multi-threaded BAM processing via processBAM(), especially on macOS where libomp may need to be installed.
• Use findBAMS() with level = 0 or level = 1 to systematically locate BAM files and automatically resolve sample names.
• Use findSpliceWizOutput() to organize the output files of processBAM() before running collateData().
• Set lowMemoryMode = TRUE in collateData() when collating large experiments (20+ samples) on machines with limited RAM.

Common Pitfalls

• Out of memory errors during collation: Occurs when running collateData() with multiple threads on large datasets; fix by setting lowMemoryMode = TRUE to limit RAM usage to ~8 GB.
• Low mappability regions confounding intron retention (IR) analysis: Repetitive regions can skew IR ratios; fix by specifying genome_type (e.g., "hg38", "mm10") in buildRef() to use pre-built mappability exclusions.
• Missing statistical dependencies for differential analysis: Attempting differential analysis without required packages; fix by installing DoubleExpSeq, DESeq2, limma, or edgeR.

Alternatives

• DESeq2: For gene-level differential expression analysis using negative binomial models.
• edgeR: For differential expression and quasi-likelihood-based analysis of count data.
• limma: For modeling log-normal distributions of expression data.

Citations

• Wong, A. C. H. (2026). SpliceWiz: Quick Start. R Package Vignette.

References

• Homepage: bioconductor.org/packages/splicewiz
• Vignette: https://bioconductor.org/packages/release/bioc/vignettes/splicewiz/inst/doc/vignette_0_cc3952e3.html