scsplice 2.1.0

Single-cell alternative-splicing analysis for the scverse ecosystem.

scsplice is the Python port of the R package splikit. It analyses splice-junction count data in single-cell RNA-seq, treating each event as a pair of inclusion (M1) and exclusion (M2) counts derived from local junction variants (LJVs). The package is AnnData-native — junctions live on the var axis, M1 and M2 sit in layers, and downstream analysis composes naturally with scanpy.

Status

v2.1.0 keeps a deliberately focused API:

• scs.io.read_starsolo — ingest STARsolo Solo.out/SJ/ for one or more samples.
• scs.tl.make_m2 — build the exclusion matrix from M1 + LJV grouping.
• scs.pp.highly_variable_events — per-library binomial-deviance HVE selection.
• scs.io.read_starsolo_gene — read raw or filtered gene counts, including STARsolo EM matrices.
• scs.tl.pseudo_correlation — beta-binomial Cox-Snell / Nagelkerke pseudo-R² with event-wise permutation inference.
• scs.tl.get_pseudo_correlation_result — materialize export-ready statistics and long null tables.
• scs.pp.highly_variable_genes — Seurat/R-splikit variance-stabilizing-transformation (VST) HVG selection (pip install "scsplice[hvg]").

Plotting and silhouette utilities from the R package, and R splikit's other HVG method (sum_deviance), are intentionally omitted — scanpy, pyranges, and sklearn already cover that ground.

Installation

scsplice ships a C++ extension built via scikit-build-core + pybind11. Eigen3 (header-only) is required at install time; OpenMP is optional but strongly recommended for multi-threaded kernels.

From PyPI

pip install scsplice

From source

git clone https://github.com/Arshammik/scsplice
cd scsplice
pip install .

System dependencies before running pip install:

Ubuntu / Debian

sudo apt install libeigen3-dev libomp-dev

macOS (Homebrew)

brew install eigen libomp
# tell CMake where Apple Clang's OpenMP lives
export OpenMP_ROOT="$(brew --prefix libomp)"
export LDFLAGS="-L${OpenMP_ROOT}/lib"
export CPPFLAGS="-I${OpenMP_ROOT}/include"

HPC cluster (Compute Canada / Sharcnet pattern)

module load eigen/3.4.0
# any modern GCC with OpenMP (gcc/12+) on the system module path

Editable install (development)

pip install -e ".[dev]"

This installs the package, all test dependencies, the docs toolchain (mkdocs-material, mkdocstrings[python], mkdocs-jupyter), and ruff / pre-commit. C++ edits require re-running pip install -e .; pure-Python edits take effect immediately.

Quick start

import numpy as np
import scsplice as scs
import scanpy as sc

# (1) Ingest STARsolo splice-junction counts (M1) and LJV grouping
adata = scs.io.read_starsolo(
    sj_dirs=["sample1/Solo.out/SJ", "sample2/Solo.out/SJ"],
    sample_ids=["s1", "s2"],
)

# (2) Build exclusion matrix (M2) from inclusion counts + junction grouping
scs.tl.make_m2(adata, n_threads=8)

# (3) Identify highly variable events per library using binomial deviance
scs.pp.highly_variable_events(adata, min_row_sum=50, n_threads=8)

# (4) Compute pseudo-correlation with the 100-permutation default
# zdb must be events × cells and aligned to adata.var_names / adata.obs_names
zdb = np.random.default_rng(42).normal(size=(adata.n_vars, adata.n_obs))
scs.tl.pseudo_correlation(adata, zdb, seed=42, n_threads=8)
result = scs.tl.get_pseudo_correlation_result(adata)
result.statistics.to_csv("pseudo_correlation_statistics.csv", index=False)
result.null_distribution.to_csv("pseudo_correlation_null.csv", index=False)

# Optional: compose with scanpy on the splicing embedding
# (PCA / neighbors / leiden over logit(M1 / (M1 + M2)))

Gene-expression ingestion defaults to raw STARsolo counts, preferring UniqueAndMult-EM.mtx and falling back to matrix.mtx, then independently applies the internal filtered-barcode whitelist. Use matrix_source="filtered" to read the filtered matrix directly or matrix_source="auto" for the scsplice 2.0.0 source-selection behavior.

Numerical equivalence

scsplice reproduces R splikit results to a documented tolerance on a fixed reference dataset (M2 bit-exact; HVE deviance rtol=1e-10; pseudo-correlation rtol=1e-7; HVG standardize_variance rtol=1e-6). The M1/M2/HVE/pseudo-correlation cross-language regression suite and R reference fixtures live on the validation branch. The highly_variable_genes (VST) equivalence test lives on main (tests/test_highly_variable_genes_vs_r.py) and is skipped automatically until its fixture is regenerated via Rscript tests/r_export/export_hvg_reference.R — see that script's header and tests/load_hvg_r_ref.py. Its loess step uses scikit-misc's loess binding, which wraps the same netlib/Cleveland-Grosse Fortran/C code R's stats::loess() calls, so the equivalence is genuine rather than a from-scratch approximation.

Documentation

Full documentation is available at https://arshammik.github.io/scsplice/.

Topics include:

• Getting Started — installation and first workflow
• Tutorials — step-by-step notebooks
• How-to Guides — recipes for common tasks
• Reference — complete API documentation
• Explanation — conceptual background and design

License

MIT.