### Build SpliceWiz Reference from Example Genome

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Builds a SpliceWiz reference using a built-in example genome and GTF. Useful for quick testing and examples.

```r
library(SpliceWiz)

# --- Quick example using built-in example genome ---
example_ref <- file.path(tempdir(), "Reference")
buildRef(
    reference_path = example_ref,
    fasta = chrZ_genome(),
    gtf   = chrZ_gtf()
)
```

--------------------------------

### Install SpliceWiz Development Version from GitHub

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Installs the latest development version of SpliceWiz and its ompBAM dependency from GitHub. Requires the devtools package.

```r
library("devtools")
install_github("alexchwong/ompBAM")
install_github("alexchwong/SpliceWiz", "main", dependencies = TRUE)
```

--------------------------------

### Install SpliceWiz and Dependencies

Source: https://github.com/alexchwong/splicewiz/blob/main/inst/htslib_version/README.md

Installs the SpliceWiz R package and its dependencies using BiocManager. Ensure BiocManager is up-to-date before installing SpliceWiz.

```R
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install(version = "3.16")
BiocManager::valid()              # checks for out of date packages

BiocManager::install("SpliceWiz")
```

--------------------------------

### Install ompBAM and SpliceWiz from GitHub

Source: https://github.com/alexchwong/splicewiz/blob/main/README.md

Install the ompBAM package and the latest development version of SpliceWiz directly from GitHub using the devtools package. This method is useful for the latest features or for older Bioconductor versions.

```r
library("devtools")
install_github("alexchwong/ompBAM")

# To install the latest devel version, install from the "main" branch
install_github("alexchwong/SpliceWiz", "main", dependencies=TRUE)
```

--------------------------------

### Install libomp on MacOS

Source: https://github.com/alexchwong/splicewiz/blob/main/README.md

For MacOS users, install libomp libraries using brew to enable OpenMP multi-threading support for SpliceWiz.

```bash
brew install libomp
```

--------------------------------

### Install SpliceWiz from Bioconductor

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Installs the current release of SpliceWiz and its dependencies from Bioconductor. Ensure R version is 4.4 or higher.

```r
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install(version = "3.20")
BiocManager::install("SpliceWiz")
```

--------------------------------

### Build Full SpliceWiz Reference with STAR

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Builds a SpliceWiz reference and a STAR aligner index in a single step. Requires STAR to be installed on Linux and specifies the number of threads.

```r
# --- One-step: STAR + SpliceWiz reference (Linux + STAR required) ---
buildFullRef(
    reference_path        = "./Reference_with_STAR",
    fasta                 = "genome.fa",
    gtf                   = "transcripts.gtf",
    genome_type           = "hg38",
    use_STAR_mappability  = TRUE,
    n_threads             = 4
)
```

--------------------------------

### STAR_buildRef / STAR_alignReads / STAR_alignExperiment — STAR Alignment Wrappers

Source: https://context7.com/alexchwong/splicewiz/llms.txt

These functions wrap the STAR aligner to build genome indexes and align RNA-seq FASTQ files. They require STAR to be installed on a Linux-based system and resources to be prepared via `getResources()` or `buildRef()`.

```APIDOC
## STAR_buildRef / STAR_alignReads / STAR_alignExperiment

### Description
These functions wrap the STAR aligner to build genome indexes and align RNA-seq FASTQ files. They require STAR to be installed on a Linux-based system and resources to be prepared via `getResources()` or `buildRef()`.

### Method
R function call

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```r
library(SpliceWiz)

# Check STAR installation
STAR_version()
```

### Response
None

### Error Handling
None specified.
```

--------------------------------

### Install SpliceWiz for Bioconductor Devel

Source: https://github.com/alexchwong/splicewiz/blob/main/README.md

Install the development version of SpliceWiz for future Bioconductor (3.21) and R (4.5) versions using BiocManager. Includes a check for outdated packages.

```r
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install(version = "devel")
BiocManager::valid()              # checks for out of date packages

BiocManager::install("SpliceWiz")
```

--------------------------------

### Roxygenize and Install htslib SpliceWiz

Source: https://github.com/alexchwong/splicewiz/blob/main/inst/htslib_version/README.md

After copying the htslib files, this R code roxygenizes the package to update documentation for htslib functions and then installs the package from the local source.

```R
# Roxygenize for documentation on processBAM_hts() and BAM2COV_hts()
devtools::document("/path/to/SpliceWiz")

# Install the package
install.packages(
    "/path/to/SpliceWiz", 
    repos = NULL, 
    type = "source"
)
```

--------------------------------

### Check STAR Aligner Version

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Checks the installed version of the STAR aligner. This is a prerequisite for using the STAR alignment wrapper functions.

```r
library(SpliceWiz)

# Check STAR installation
STAR_version()
```

--------------------------------

### Install SpliceWiz for Bioconductor Release

Source: https://github.com/alexchwong/splicewiz/blob/main/README.md

Install the current release of SpliceWiz and its dependencies using BiocManager for R version 4.4 and Bioconductor 3.20. Includes a check for outdated packages.

```r
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install(version = "3.20")
BiocManager::valid()              # checks for out of date packages

BiocManager::install("SpliceWiz")
```

--------------------------------

### Launch SpliceWiz in Demo Mode

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Launches the SpliceWiz Shiny GUI in a demo mode, which automatically sets up demo BAM files and a reference genome in a temporary directory. Ideal for exploring the GUI's features without providing your own data.

```r
library(SpliceWiz)

# Launch demo mode (places demo BAMs and reference in tempdir())
if (interactive()) {
    spliceWiz(demo = TRUE)
}
```

--------------------------------

### Build Reference with GO Annotations

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Builds a reference dataset including Gene Ontology annotations. This is a prerequisite for GO analysis. Specify the output path, FASTA file, GTF file, and the species for ontology.

```r
library(SpliceWiz)
require("limma")

# Build reference with GO annotations
ref_path <- file.path(tempdir(), "Reference_withGO")
buildRef(
    reference_path  = ref_path,
    fasta           = chrZ_genome(),
    gtf             = chrZ_gtf(),
    ontologySpecies = "Homo sapiens"
)
```

--------------------------------

### File Discovery Helpers

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Functions to recursively scan directories for BAM, FASTQ, or processBAM output files.

```APIDOC
## findSamples / findBAMS / findFASTQ / findSpliceWizOutput

### Description
Recursively scan directories to build sample-annotated data frames of BAM, FASTQ, or processBAM output files. These data frames are used as input to `processBAM()`, `STAR_alignExperiment()`, and `collateData()`.

### Parameters
- `path` (string) - The directory to scan.
- `level` (integer, optional) - For `findBAMS`, specifies the directory level to use as sample name (0: file name, 1: parent directory name).
- `paired` (boolean, optional) - For `findFASTQ`, whether to look for paired-end FASTQ files.
- `fastq_suffix` (string, optional) - For `findFASTQ`, the suffix of the FASTQ files to look for.

### Returns
- `data.frame` - A data frame containing sample names and file paths. For `findFASTQ`, it includes `sample`, `forward`, `reverse`. For `findSpliceWizOutput`, it includes `sample`, `path`, `cov_file`.
```

--------------------------------

### Find Paired FASTQ Files

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Recursively scans directories to find paired gzipped FASTQ files and returns a sample-annotated data frame. Specify the directory to scan and optionally the FASTQ suffix.

```r
library(SpliceWiz)

# Find paired gzipped FASTQ files
df.fastq <- findFASTQ("./raw", paired = TRUE, fastq_suffix = ".fq.gz")
# Returns: data.frame(sample, forward, reverse)
```

--------------------------------

### Launch SpliceWiz Interactive Shiny GUI (Browser Mode)

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Launches the SpliceWiz Shiny GUI in the system's default web browser. This mode allows for a resizable interface.

```r
library(SpliceWiz)

# Launch in system browser (resizable)
if (interactive()) {
    spliceWiz(mode = "browser")
}
```

--------------------------------

### Build STAR Genome-Only Reference

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Builds a STAR genome-only reference. This is a precursor step before injecting GTF on the fly during alignment. Specify reference paths and number of threads.

```r
STAR_buildGenome(
    reference_path = "./Reference_FTP",
    STAR_ref_path  = file.path("./Reference_FTP", "STAR_genomeOnly"),
    n_threads = 8, sparsity = 2
)
```

--------------------------------

### Clone Repository and Copy htslib Files

Source: https://github.com/alexchwong/splicewiz/blob/main/inst/htslib_version/README.md

Clones the SpliceWiz GitHub repository and copies the htslib version files to the root directory. This step is performed from the command line.

```bash
# Navigate to a directory of your choice, e.g.:
cd /path/to

git clone https://github.com/alexchwong/SpliceWiz
cd SpliceWiz
cp -r inst/htslib_version/* .
```

--------------------------------

### Build STAR Genome Reference

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Builds a STAR genome reference and optionally computes Mappability Exclusion BED files. Ensure the reference path and STAR reference path are correctly specified.

```r
STAR_buildRef(
    reference_path          = "./Reference_FTP",
    STAR_ref_path           = file.path("./Reference_FTP", "STAR"),
    n_threads               = 8,
    also_generate_mappability = TRUE
)
```

--------------------------------

### Build SpliceWiz Reference from Ensembl FTP

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Builds a SpliceWiz reference by downloading FASTA and GTF files directly from Ensembl FTP. Requires specifying the FTP URL and genome type.

```r
# --- Reference from Ensembl FTP ---
FTP <- "ftp://ftp.ensembl.org/pub/release-94/"
buildRef(
    reference_path = "./Reference_FTP",
    fasta = paste0(FTP,
        "fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz"),
    gtf   = paste0(FTP,
        "gtf/homo_sapiens/Homo_sapiens.GRCh38.94.chr.gtf.gz"),
    genome_type = "hg38"
)
```

--------------------------------

### Build Reference for BAM Processing

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Builds a reference genome and GTF for BAM processing using `buildRef`. Ensure `fasta` and `gtf` arguments point to valid files or use helper functions like `chrZ_genome()` and `chrZ_gtf()`.

```r
library(SpliceWiz)

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

--------------------------------

### Find BAM Files

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Recursively scans directories to find BAM files and creates a sample-annotated data frame. Use 'level' to specify how sample names are derived from file paths (0: filename, 1: parent directory).

```r
library(SpliceWiz)

# Find BAM files named by sample (level 0: file name = sample name)
df.bams <- findBAMS("./bams", level = 0)
# Returns: data.frame(sample, path)

# Find BAMs named by parent directory (level 1: folder name = sample name)
df.bams <- findBAMS("./bams", level = 1)
```

--------------------------------

### Launch SpliceWiz Interactive Shiny GUI (Dialog Mode)

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Launches the SpliceWiz Shiny GUI as a fixed-size dialog box within RStudio. Requires RStudio and is configured for a 1920x1080 resolution.

```r
library(SpliceWiz)

# Launch as a fixed-size dialog box in RStudio (1920x1080)
if (interactive()) {
    spliceWiz(mode = "dialog", res = "1080p")
}
```

--------------------------------

### Build SpliceWiz Reference from User Files

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Constructs a SpliceWiz reference using user-supplied FASTA and GTF files. Specifies genome type for automatic resource selection.

```r
# --- Real hg38 reference from user-supplied files ---
buildRef(
    reference_path = "./Reference_hg38",
    fasta          = "genome.fa",
    gtf            = "transcripts.gtf",
    genome_type    = "hg38"   # auto-selects nonPolyA + Mappability resources
)
```

--------------------------------

### Align Single Paired-End Sample with STAR

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Aligns a single paired-end FASTQ sample using STAR. Specify input FASTQ files, STAR reference path, and desired BAM output path. Adjust n_threads for performance.

```r
STAR_alignReads(
    fastq_1         = "sample1_1.fastq",
    fastq_2         = "sample1_2.fastq",
    STAR_ref_path   = file.path("./Reference_FTP", "STAR"),
    BAM_output_path = "./bams/sample1",
    n_threads       = 8
)
```

--------------------------------

### buildRef / buildFullRef — Build SpliceWiz Reference

Source: https://context7.com/alexchwong/splicewiz/llms.txt

These functions download or accept user-supplied genome FASTA and GTF annotation files, then construct the SpliceWiz reference required for BAM processing. `buildRef()` handles common genomes (hg38, hg19, mm10, mm9) with built-in mappability and non-polyA resources. `buildFullRef()` additionally creates a STAR aligner reference in one step.

```APIDOC
## buildRef / buildFullRef

### Description
These functions download or accept user-supplied genome FASTA and GTF annotation files, then construct the SpliceWiz reference required for BAM processing. `buildRef()` handles common genomes (hg38, hg19, mm10, mm9) with built-in mappability and non-polyA resources. `buildFullRef()` additionally creates a STAR aligner reference in one step.

### Method
R function call

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```r
library(SpliceWiz)

# --- Quick example using built-in example genome ---
example_ref <- file.path(tempdir(), "Reference")
buildRef(
    reference_path = example_ref,
    fasta = chrZ_genome(),
    gtf   = chrZ_gtf()
)

# --- Real hg38 reference from user-supplied files ---
buildRef(
    reference_path = "./Reference_hg38",
    fasta          = "genome.fa",
    gtf            = "transcripts.gtf",
    genome_type    = "hg38"   # auto-selects nonPolyA + Mappability resources
)

# --- Reference from Ensembl FTP ---
FTP <- "ftp://ftp.ensembl.org/pub/release-94/"
buildRef(
    reference_path = "./Reference_FTP",
    fasta = paste0(FTP,
        "fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz"),
    gtf   = paste0(FTP,
        "gtf/homo_sapiens/Homo_sapiens.GRCh38.94.chr.gtf.gz"),
    genome_type = "hg38"
)

# --- Reference from AnnotationHub records ---
# First search: AnnotationHub::query(ah, c("Homo Sapiens", "release-94"))
buildRef(
    reference_path = "./Reference_AH",
    fasta          = "AH65745",
    gtf            = "AH64631",
    genome_type    = "hg38"
)

# --- With chromosome aliases (Ensembl ref, UCSC-named BAMs) ---
chrom.df <- GenomeInfoDb::genomeStyles()$Homo_sapiens
buildRef(
    reference_path     = "./Reference_UCSC",
    fasta              = "AH65745",
    gtf                = "AH64631",
    genome_type        = "hg38",
    chromosome_aliases = chrom.df[, c("Ensembl", "UCSC")]
)

# --- One-step: STAR + SpliceWiz reference (Linux + STAR required) ---
buildFullRef(
    reference_path        = "./Reference_with_STAR",
    fasta                 = "genome.fa",
    gtf                   = "transcripts.gtf",
    genome_type           = "hg38",
    use_STAR_mappability  = TRUE,
    n_threads             = 4
)

# --- Rebuild existing reference after SpliceWiz version upgrade ---
buildRef(reference_path = "./Reference_hg38", overwrite = TRUE)
```

### Response
None

### Error Handling
None specified.
```

--------------------------------

### Plot Individual Sample Coverage with Sashimi Arcs

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Generates a static ggplot2 coverage plot for individual samples, including sashimi plot junction arcs. Requires the SpliceWiz SE object, the event of interest, and the tracks to display. Set plotJunctions to TRUE.

```r
# Individual-sample coverage with sashimi junction arcs (ggplot)
plotCoverage(
    se             = se,
    Event          = "SE:SRSF3-203-exon4;SRSF3-202-int3",
    tracks         = colnames(se)[1:4],
    plotJunctions  = TRUE
)
```

--------------------------------

### Build SpliceWiz Reference from AnnotationHub

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Constructs a SpliceWiz reference using FASTA and GTF files identified by AnnotationHub record IDs. Requires prior searching of AnnotationHub.

```r
# --- Reference from AnnotationHub records ---
# First search: AnnotationHub::query(ah, c("Homo Sapiens", "release-94"))
buildRef(
    reference_path = "./Reference_AH",
    fasta          = "AH65745",
    gtf            = "AH64631",
    genome_type    = "hg38"
)
```

--------------------------------

### Align Experiment with GTF Reference

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Aligns an experiment using a STAR reference that includes GTF annotations loaded on the fly. Use the output from STAR_loadGenomeGTF as the STAR_ref_path.

```r
STAR_alignExperiment(
    Experiment      = Experiment,
    STAR_ref_path   = star_gtf_ref,
    BAM_output_path = "./bams",
    n_threads       = 8
)
```

--------------------------------

### getCoverage / getCoverage_DF / getCoverageRegions / getCoverageBins

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Low-level functions to retrieve per-nucleotide alignment coverage from SpliceWiz's compact binary COV files. Supports random-access for genomic regions, GRanges-based regional summaries, and binned retrieval for large windows.

```APIDOC
## getCoverage / getCoverage_DF / getCoverageRegions / getCoverageBins — COV File Access

Low-level functions to retrieve per-nucleotide alignment coverage from SpliceWiz's compact binary COV files. Supports random-access for genomic regions, GRanges-based regional summaries, and binned retrieval for large windows.

### Description

- `getCoverage`: Retrieves coverage as an Rle (Rle object) for a specified genomic region and strand.
- `getCoverage_DF`: Retrieves coverage as a data.frame with 'coordinate' and 'value' columns for a specified genomic region and strand.
- `getCoverageRegions`: Calculates mean coverage over specified genomic regions (GRanges).
- `getCoverageBins`: Retrieves coverage summarized into bins for a large genomic region.

### Usage

```r
# Retrieve coverage as an RLE
cov_rle <- getCoverage(cov_file, seqname = "chrZ",
    start = 10000, end = 20000, strand = "*")

# Retrieve as a data.frame
cov_df <- getCoverage_DF(cov_file, seqname = "chrZ",
    start = 10000, end = 20000, strand = "*")

# Mean coverage over a GRanges of 100-nt windows
gr_cov <- getCoverageRegions(cov_file, regions = gr, strandMode = "reverse")

# Binned coverage of a large region
gr_fetch <- getCoverageBins(
    cov_file,
    region = GenomicRanges::GRanges(
        seqnames = "chrZ",
        ranges   = IRanges::IRanges(start = 100, end = 100000),
        strand   = "*"
    ),
    bins = 2000
)

# Export whole-genome coverage as BigWig
cov_whole <- getCoverage(cov_file)
rtracklayer::export(cov_whole, file.path(tempdir(), "sample.bw"), "bw")
```

### Parameters

#### `getCoverage` and `getCoverage_DF` Parameters

- **cov_file** (character) - Path to the COV file.
- **seqname** (character) - The chromosome name.
- **start** (integer) - The start coordinate of the region.
- **end** (integer) - The end coordinate of the region.
- **strand** (character) - The strand ("+", "-", or "*").

#### `getCoverageRegions` Parameters

- **cov_file** (character) - Path to the COV file.
- **regions** (GRanges) - A GRanges object specifying the regions.
- **strandMode** (character) - How to handle strand information: "" (no strand), "reverse" (reverse strand), "ignore" (ignore strand).

#### `getCoverageBins` Parameters

- **cov_file** (character) - Path to the COV file.
- **region** (GRanges) - A GRanges object specifying the region to bin.
- **bins** (integer) - The number of bins to divide the region into.

### Returns

- `getCoverage`: An Rle object representing coverage.
- `getCoverage_DF`: A data.frame with 'coordinate' and 'value' columns.
- `getCoverageRegions`: A GRanges object with an added 'cov_mean' column.
- `getCoverageBins`: A GRanges object with summarized coverage per bin.
```

--------------------------------

### makeSE — Import Collated Dataset as NxtSE Object

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Constructs a NxtSE object from a collated data directory. Supports on-disk or in-memory modes and optional sample filtering.

```APIDOC
## makeSE — Import Collated Dataset as NxtSE Object

### Description
Constructs a `NxtSE` object (extending `SummarizedExperiment`) from the collated data directory. Supports on-disk (DelayedArray/HDF5) or fully in-memory modes. Optionally filters to a subset of samples via `colData`.

### Method Signature
```r
makeSE(collate_path, colData = NULL)
```

### Parameters
* `collate_path` (character) - Path to the collated data directory.
* `colData` (data.frame, optional) - A data frame containing sample annotations for filtering.

### Request Example
```r
library(SpliceWiz)

# Load full dataset
se <- makeSE(collate_path = file.path(tempdir(), "Collated_output"))

# Load subset of samples with annotations
sample_annot <- data.frame(
    sample    = c("sample1", "sample2", "sample3"),
    treatment = c("A", "A", "B")
)
se <- makeSE(
    collate_path = file.path(tempdir(), "Collated_output"),
    colData      = sample_annot
)
```

### Related Functions
* `realize_NxtSE()`: Realizes HDF5 DelayedArrays into RAM.
* `findSamples()`: Finds sample files.
* `covfile()`: Accessor for coverage file paths.
* `dim()`: Dimensions of the NxtSE object.
* `rowData()`: Event metadata.
* `colData()`: Sample metadata.
* `sampleQC()`: QC metrics per sample.
* `assay()`: Accesses assays like 'Included' and 'Excluded' counts.
```

--------------------------------

### Direct Gene-Level GO Analysis

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Performs Gene Ontology (GO) analysis directly on a list of genes. Requires a list of enriched genes, all universe genes, a pre-built ontology reference, and the ontology type.

```r
# Direct gene-level GO analysis
ontology <- viewGO(ref_path)
all_genes <- sort(unique(ontology$gene_id))
go_genes <- goGenes(
    enrichedGenes  = all_genes[1:500],
    universeGenes  = all_genes,
    ontologyRef    = ontology,
    ontologyType   = "BP"
)
```

--------------------------------

### Import Collated Data with makeSE

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Load collated splicing data into a NxtSE object. Supports loading the full dataset or a subset of samples. Use realize_NxtSE to load data into RAM.

```r
library(SpliceWiz)

# Load full dataset
se <- makeSE(collate_path = file.path(tempdir(), "Collated_output"))

# Load subset of samples with annotations
sample_annot <- data.frame(
    sample    = c("sample1", "sample2", "sample3"),
    treatment = c("A", "A", "B")
)
se <- makeSE(
    collate_path = file.path(tempdir(), "Collated_output"),
    colData      = sample_annot
)

# Realize all HDF5 DelayedArrays into RAM for faster downstream operations
se <- realize_NxtSE(se)

# Reassign COV files if they have moved
covfile_df <- findSamples(system.file("extdata", package = "SpliceWiz"), ".cov")
covfile(se) <- covfile_df$path

# Inspect the object
dim(se)           # rows = ASE events, cols = samples
rowData(se)       # event metadata (EventName, EventType, EventRegion, ...)
colData(se)       # sample metadata
sampleQC(se)      # QC metrics per sample
assay(se, "Included")  # included isoform counts (DelayedMatrix or matrix)
assay(se, "Excluded")  # excluded isoform counts
```

--------------------------------

### Load GTF for STAR Alignment

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Loads a GTF file to create a STAR genome reference on the fly for alignment. This is useful for incorporating gene annotations. Specify reference paths and sjdbOverhang.

```r
star_gtf_ref <- STAR_loadGenomeGTF(
    reference_path    = "./Reference_FTP",
    STAR_ref_path     = file.path("./Reference_FTP", "STAR_genomeOnly"),
    STARgenome_output = file.path(tempdir(), "STAR"),
    sjdbOverhang      = 100
)
```

--------------------------------

### ASE_limma: Differential AS Analysis with limma

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Performs differential alternative splicing analysis using the limma package with a log-normal model. Recommended for general use. Requires limma package.

```r
library(SpliceWiz)

se <- SpliceWiz_example_NxtSE(novelSplicing = TRUE)
colData(se)$treatment <- rep(c("A", "B"), each = 3)
colData(se)$replicate <- rep(c("P", "Q", "R"), 2)

# Apply default filters first (recommended)
se <- se[applyFilters(se), ]

# --- limma (log-normal model) ---
require("limma")
res_limma <- ASE_limma(
    se         = se,
    test_factor = "treatment",
    test_nom    = "A",          # nominator (e.g. treatment)
    test_denom  = "B",          # denominator (e.g. control)
    batch1      = "replicate",  # optional batch correction
    IRmode      = "all"         # "all", "annotated", or "annotated_binary"
)
# Columns: EventName, EventType, EventRegion, deltaPSI, abs_deltaPSI,
#          AvgPSI_A, AvgPSI_B, logFC, AveExpr, t, P.Value, adj.P.Val, B

# --- edgeR (negative binomial, recommended) ---
require("edgeR")
res_edgeR <- ASE_edgeR(
    se          = se,
    test_factor = "treatment",
    test_nom    = "A",
    test_denom  = "B",
    useQL       = TRUE   # quasi-likelihood method (reduces false positives)
)
# Columns: EventName, EventType, logFC, logCPM, F, PValue, FDR, ...

# --- DESeq2 (negative binomial with dispersion shrinkage) ---
require("DESeq2")
res_deseq <- ASE_DESeq(
    se          = se,
    test_factor = "treatment",
    test_nom    = "A",
    test_denom  = "B",
    n_threads   = 2
)

# --- DoubleExpSeq (beta-binomial / generalized beta prime) ---
require("DoubleExpSeq")
res_des <- ASE_DoubleExpSeq(se, "treatment", "A", "B")

# --- Time series with limma (degrees_of_freedom models polynomial trends) ---
colData(se)$timepoint <- rep(c(1, 2, 3), each = 2)
res_ts_limma <- ASE_limma_timeseries(se, "timepoint", degrees_of_freedom = 2)

# --- Time series with edgeR ---
res_ts_edgeR <- ASE_edgeR_timeseries(se, "timepoint", degrees_of_freedom = 1)

# --- DESeq2 time series (leave test_nom/test_denom blank) ---
res_ts_deseq <- ASE_DESeq(se, "timepoint")

# Filter significant hits: |deltaPSI| > 0.1, FDR < 0.05
sig <- res_limma[abs(deltaPSI) > 0.1 & adj.P.Val < 0.05]
```

--------------------------------

### Collate Multi-Sample Data

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Collates output files from `processBAM()` across multiple samples to calculate PSI and IR-ratio values. This prepares a dataset for `makeSE()`. Specify the experiment data frame, reference path, and output path. `IRMode` can be set to "SpliceOver" or "SpliceMax".

```r
library(SpliceWiz)

expr <- findSpliceWizOutput(file.path(tempdir(), "SpliceWiz_Output"))

# Standard collation
collateData(
    Experiment     = expr,
    reference_path = file.path(tempdir(), "Reference"),
    output_path    = file.path(tempdir(), "Collated_output"),
    IRMode         = "SpliceOver",  # or "SpliceMax" (IRFinder-original)
    n_threads      = 4,
    overwrite      = FALSE
)
```

--------------------------------

### Custom edgeR GLM for ASE Analysis

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Provides advanced API for custom edgeR generalized linear models for differential ASE analysis. Useful for complex experimental designs, time series with splines, or multi-factor contrasts. Requires edgeR package.

```r
library(SpliceWiz)
require("edgeR")

se <- SpliceWiz_example_NxtSE()
colData(se)$treatment <- rep(c("A", "B"), each = 3)
colData(se)$replicate <- rep(c("P", "Q", "R"), 2)

# Fit model using formula strings
fit <- fitASE_edgeR(
    se             = se,
    strModelFormula = "~0 + replicate + treatment",
    strASEFormula   = "~0 + replicate + treatment + treatment:ASE"
)

# Inspect model coefficient names
colnames(fit$model_IncExc)
# [1] "replicateP" "replicateQ" "replicateR" "treatmentB"
colnames(fit$model_ASE)
# [1] "replicateP" "replicateQ" "replicateR" "treatmentB"
# [5] "treatmentA:ASEIncluded" "treatmentB:ASEIncluded"

# Test treatment B vs A contrast
res <- testASE_edgeR(se, fit,
    contrast_IncExc = c(0, 0, 0, 1),
    contrast_ASE    = c(0, 0, 0, 0, -1, 1)
)

# Append mean PSIs for each condition
res_psi <- addPSI_edgeR(res, se, "treatment", c("B", "A"))

# ----- Time series with polynomial splines -----
colData(se)$timepoint <- rep(c(1, 2, 3), each = 2)
Time  <- poly(colData(se)$timepoint, df = 2)
Batch <- factor(colData(se)$replicate)

Time_ASE  <- rbind(Time, Time)
Batch_ASE <- c(Batch, Batch)
ASE <- factor(rep(c("Included", "Excluded"), each = ncol(se)))

model_IncExc <- model.matrix(~0 + Batch + Time)
model_ASE    <- model.matrix(~0 + Batch_ASE + Time_ASE + Time_ASE:ASE)

fit_ts  <- fitASE_edgeR_custom(se, model_IncExc, model_ASE)
res_ts  <- testASE_edgeR(se, fit_ts, coef_IncExc = 3:4, coef_ASE = 5:6)
res_ts_psi <- addPSI_edgeR(res_ts, se, "timepoint", c(1, 2, 3))
```

--------------------------------

### Create and Apply ASE Filters

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Define custom filters for splicing events based on annotations or data metrics. Apply default or custom filters to a NxtSE object to subset events.

```r
library(SpliceWiz)

se <- SpliceWiz_example_NxtSE()

# --- Build custom filters ---

# Annotation filter: keep only protein-coding events
f_pc <- ASEFilter(filterClass = "Annotation", filterType = "Protein_Coding")

# Data filter: require depth >= 20 in IR/RI events
f_depth <- ASEFilter(
    filterClass = "Data",
    filterType  = "Depth",
    minimum     = 20,
    EventTypes  = c("IR", "RI")
)

# Data filter: require >=60% participation in splice events
# satisfied in at least 2 of the condition levels of "Genotype"
f_part <- ASEFilter(
    filterClass = "Data",
    filterType  = "Participation",
    minimum     = 60,
    EventTypes  = c("MXE", "SE", "AFE", "ALE", "A3SS", "A5SS"),
    condition   = "Genotype",
    minCond     = 2
)

# Inspect filter descriptions
f_pc; f_depth; f_part

# --- Apply default recommended filters ---
# (Depth >= 20, IR participation >= 70%, splice participation >= 40%,
#  consistency, terminus, exclusive MXE, strict AltSS)
filters <- getDefaultFilters()
se_filtered <- se[applyFilters(se, filters), ]

# Apply a single filter
se_depth_filtered <- se[runFilter(se, filters[[1]]), ]

# Apply filters with treatment annotation
colData(se)$treatment <- rep(c("A", "B"), each = 3)
f_cond <- ASEFilter(
    filterClass = "Data",
    filterType  = "Depth",
    minimum     = 10,
    condition   = "treatment",
    pcTRUE      = 80   # 80% of samples per condition must pass
)
se_cond_filtered <- se[runFilter(se, f_cond), ]
```

--------------------------------

### STAR Reference and Alignment Functions

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Functions for building STAR genome references and aligning sequencing reads.

```APIDOC
## STAR_buildRef

### Description
Builds a STAR genome reference index.

### Parameters
- `reference_path` (string) - Path to the directory where the reference will be stored.
- `STAR_ref_path` (string) - Full path to the STAR reference directory.
- `n_threads` (integer) - Number of threads to use for the process.
- `also_generate_mappability` (boolean) - Whether to also generate a mappability exclusion BED file.

## STAR_alignReads

### Description
Aligns a single paired-end sample using STAR.

### Parameters
- `fastq_1` (string) - Path to the first FASTQ file.
- `fastq_2` (string) - Path to the second FASTQ file.
- `STAR_ref_path` (string) - Path to the STAR reference directory.
- `BAM_output_path` (string) - Path to save the output BAM file.
- `n_threads` (integer) - Number of threads to use.

## STAR_alignExperiment

### Description
Aligns multiple samples using STAR, with support for two-pass mapping.

### Parameters
- `Experiment` (data.frame) - A data frame with sample information, including forward and reverse read paths.
- `STAR_ref_path` (string) - Path to the STAR reference directory or a loaded STAR genome GTF reference object.
- `BAM_output_path` (string) - Directory to save the output BAM files.
- `n_threads` (integer) - Number of threads to use.
- `two_pass` (boolean) - Whether to perform two-pass mapping (default is FALSE).

## STAR_buildGenome

### Description
Builds a genome-only STAR reference.

### Parameters
- `reference_path` (string) - Path to the directory where the reference will be stored.
- `STAR_ref_path` (string) - Full path to the STAR reference directory.
- `n_threads` (integer) - Number of threads to use.
- `sparsity` (integer) - Sparsity parameter for genome building.

## STAR_loadGenomeGTF

### Description
Loads a genome-only STAR reference and injects GTF information on the fly.

### Parameters
- `reference_path` (string) - Path to the reference directory.
- `STAR_ref_path` (string) - Path to the STAR reference directory.
- `STARgenome_output` (string) - Path for the STAR genome output.
- `sjdbOverhang` (integer) - Value for sjdbOverhang.

```

--------------------------------

### NxtSE-class — The NxtSE S4 Class

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Extends SummarizedExperiment with accessors for splicing event data, coverage files, QC, and genomic ranges.

```APIDOC
## NxtSE-class — The NxtSE S4 Class

### Description
`NxtSE` extends `SummarizedExperiment` with accessors for junction counts, coverage file paths, QC data, and event genomic ranges. Supports standard subsetting, `cbind()`, and `rbind()`.

### Accessors
* `up_inc(se)`: Upstream included junction/exon-intron reads.
* `down_inc(se)`: Downstream included junction/exon-intron reads.
* `up_exc(se)`: Upstream excluded junction reads (MXE only).
* `down_exc(se)`: Downstream excluded junction reads (MXE only).
* `junc_PSI(se)`: PSI of each junction.
* `junc_counts(se)`: Stranded junction counts.
* `junc_counts_uns(se)`: Unstranded junction counts.
* `junc_gr(se)`: GRanges of junctions.
* `row_gr(se)`: Event region as GRanges.
* `sourcePath(se)`: Path to the source data directory.
* `assayNames(se)`: Retrieve all assay names.

### Subsetting and Combining
* Standard subsetting using `[]` for rows and columns.
* `cbind(se_A, se_B)`: Combines NxtSE objects horizontally.
* `rbind(se_A, se_B)`: Combines NxtSE objects vertically (not explicitly shown but implied by `cbind` and `SummarizedExperiment` extension).

### Coercion
* `as(se, "SummarizedExperiment")`: Coerces NxtSE to SummarizedExperiment.
* `as(se_raw, "NxtSE")`: Coerces SummarizedExperiment to NxtSE.

### Update
* `update_NxtSE(se)`: Updates object format after SpliceWiz version upgrade.

### Example Usage
```r
library(SpliceWiz)

se <- SpliceWiz_example_NxtSE()

# Access junction span counts
print(head(up_inc(se)))

# Access junction PSIs and counts
print(head(junc_PSI(se)))

# Subsetting
se_ir <- subset(se, EventType == "IR")
se_3samp <- se[, 1:3]

# Combine NxtSE objects
se_A <- se[, 1:3]; se_B <- se[, 4:6]
se_combined <- cbind(se_A, se_B)

# Coerce to/from SummarizedExperiment
se_raw  <- as(se, "SummarizedExperiment")
se_back <- as(se_raw, "NxtSE")

# Update object format
se <- update_NxtSE(se)

# Check source data directory
print(sourcePath(se))

# Retrieve all assay names
print(assayNames(se))
```
```

--------------------------------

### Build SpliceWiz Reference with Chromosome Aliases

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Builds a SpliceWiz reference, incorporating chromosome aliases for compatibility between different naming conventions (e.g., Ensembl vs. UCSC).

```r
# --- With chromosome aliases (Ensembl ref, UCSC-named BAMs) ---
chrom.df <- GenomeInfoDb::genomeStyles()$Homo_sapiens
buildRef(
    reference_path     = "./Reference_UCSC",
    fasta              = "AH65745",
    gtf                = "AH64631",
    genome_type        = "hg38",
    chromosome_aliases = chrom.df[, c("Ensembl", "UCSC")]
)
```

--------------------------------

### Find SpliceWiz Output Files

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Scans directories for SpliceWiz output files (.txt.gz and .cov) and returns a sample-annotated data frame. This is useful for subsequent data collation.

```r
library(SpliceWiz)

# Find processBAM() output files (both .txt.gz and .cov)
expr <- findSpliceWizOutput(file.path(tempdir(), "SpliceWiz_Output"))
# Returns: data.frame(sample, path, cov_file)
```

--------------------------------

### Gene Ontology Analysis using Differential Events

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Performs Gene Ontology (GO) over-representation analysis on a list of significant differential ASE event names. Requires the significant event names, all event names, the SpliceWiz SE object, and the ontology type (BP, MF, or CC).

```r
# GO analysis using differential ASE event names
sig_events <- res_limma$EventName[res_limma$adj.P.Val < 0.05]
all_events <- res_limma$EventName

go_results <- goASE(
    enrichedEventNames = sig_events,
    universeEventNames = all_events,
    se                 = se,
    ontologyType       = "BP"        # "BP", "MF", or "CC"
)
```

--------------------------------

### Process BAM Files

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Functions to process BAM files for splice quantification and coverage information.

```APIDOC
## processBAM / BAM2COV

### Description
The core C++ engine (OpenMP-accelerated) processes BAM files against a SpliceWiz reference to quantify IR and splice junction reads, and generates compact binary COV files storing per-nucleotide alignment coverage.

### Parameters
- `bamfiles` (character vector) - Paths to the BAM files.
- `sample_names` (character vector) - Names of the samples corresponding to the BAM files.
- `reference_path` (string) - Path to the SpliceWiz reference.
- `output_path` (string) - Directory to save the output files (.txt.gz counts and .cov coverage files for `processBAM`, only .cov for `BAM2COV`).
- `n_threads` (integer) - Number of threads to use.
- `overwrite` (boolean) - Whether to overwrite existing output files.
- `run_featureCounts` (boolean, optional for `processBAM`) - Whether to also run Rsubread::featureCounts.

### BAM2COV Specific Parameters
- `output_path` (string) - Directory to save the output COV files.
- `overwrite` (boolean) - Whether to overwrite existing COV files.
```

--------------------------------

### PSI Matrix and Mean PSI Tables

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Constructs per-sample Percent Spliced In (PSI) matrices suitable for heatmaps and per-condition geometric mean PSI tables from a NxtSE object. Supports different methods like PSI, logit, or Z-score.

```r
library(SpliceWiz)

se <- SpliceWiz_example_NxtSE()
colData(se)$treatment <- rep(c("A", "B"), each = 3)

event_list <- rowData(se)$EventName

# Build PSI matrix (rows = events, columns = samples)
psi_mat <- makeMatrix(
    se              = se,
    event_list      = event_list[1:50],
    method          = "PSI",       # or "logit", "Z-score"
    depth_threshold = 10,
    na.percent.max  = 0.1
)

# Heatmap using pheatmap
require("pheatmap")
pheatmap(psi_mat, cluster_rows = TRUE, cluster_cols = TRUE)

# Logit-transformed matrix for statistical models
logit_mat <- makeMatrix(se, event_list[1:50], method = "logit")
```

--------------------------------

### Align Multiple Samples with STAR Two-Pass

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Aligns multiple samples using STAR with a two-pass mapping strategy. Define samples and their corresponding forward/reverse FASTQ files in a data frame. Ensure STAR reference path and BAM output directory are set.

```r
Experiment <- data.frame(
    sample  = c("sampleA", "sampleB"),
    forward = c("raw/sampleA/sampleA_1.fastq.gz",
                "raw/sampleB/sampleB_1.fastq.gz"),
    reverse = c("raw/sampleA/sampleA_2.fastq.gz",
                "raw/sampleB/sampleB_2.fastq.gz")
)

STAR_alignExperiment(
    Experiment      = Experiment,
    STAR_ref_path   = file.path("./Reference_FTP", "STAR"),
    BAM_output_path = "./bams",
    n_threads       = 8,
    two_pass        = TRUE
)
```

--------------------------------

### Export Coverage as BigWig

Source: https://context7.com/alexchwong/splicewiz/llms.txt

Exports the entire genome's coverage data from a COV file into a BigWig format file. Requires the 'rtracklayer' package and the path to the output BigWig file.

```r
# Export whole-genome coverage as BigWig
cov_whole <- getCoverage(cov_file)
rtracklayer::export(cov_whole, file.path(tempdir(), "sample.bw"), "bw")
```