Tutorial R Seurat ↔ Shanuz side-by-side comparisons

Documentation-only release. No library code changed — the installable shanuz package remains 0.2.0 on PyPI and is byte-identical to the 0.2.0 wheel. This tags a batch of tutorial improvements only.

What changed

Every tutorial now presents a genuine left-R (Seurat) / right-Python (Shanuz) side-by-side comparison. Two tutorials were previously pure ports whose "R (Seurat)" column held only code (no R figures), which read as an "R-only" page; others had one-sided or orphaned figures.

New R reproduction scripts

Each mirrors its Python tutorial's exact pipeline and writes r_* figures titled "R Seurat – …":

Script	Tutorial
tutorials/pbmc8k_subclustering_verify.R	Advanced PBMC 8k clustering + subclustering
tutorials/cbmc_citeseq_verify.R	Multimodal CITE-seq (RNA + ADT)
tutorials/pbmc3k_verify.R	PBMC 3k (the RidgePlot the vignette omits)
tutorials/pbmc3k_sctransform_verify.R	SCTransform (cell-type UMAP + SCT-vs-standard)

Balance & cleanup

• 23 new R Seurat figures across the advanced, multimodal, sctransform, and pbmc3k tutorials.
• All 6 tutorials verified two-sided — R-side figure count equals Shanuz count everywhere.
• Surfaced two orphaned xenium figures (QC violin, clusters-in-space) and removed redundant duplicate QC-scatter panels. Zero orphaned figures repo-wide.

Notable finding

Seurat's CLR normalization (margin=2) has a different absolute scale than Shanuz's, so the CITE-seq annotation thresholds are re-calibrated to Seurat's per-cluster CLR values (documented in cbmc_citeseq_verify.R); both resolve the same 9 lineages.

Full changelog: v0.2.0...tutorials-2026.07.06

v0.2.0 — Harmony batch integration + WNN multimodal analysis

First feature release since 0.1.x. Adds batch-effect correction, weighted multimodal integration, and two more dimensionality reductions — all validated against the published wheel (156 tests + all 9 tutorial scripts).

Highlights

Batch correction / integration (v0.2.0)

• run_harmony(...) — Harmony batch correction via harmonypy; stores a DimReduc("harmony") usable downstream (find_neighbors(reduction="harmony"), etc.). Verified to lower per-batch silhouette while preserving cell-type separation.
• integrate_layers(...) — Seurat v5 dispatch API (method="harmony"; cca/rpca raise NotImplementedError, on the roadmap).
• New [integration] extra: pip install "shanuz[integration]" (pulls harmonypy).

Multimodal WNN (v0.4.0)

• find_multi_modal_neighbors(...) — Weighted Nearest Neighbor analysis (Hao et al. 2021). Learns per-cell modality weights, builds joint wknn/wsnn graphs, and writes <assay>.weight columns.
• run_umap(graph=...) — embed a precomputed graph (e.g. wsnn) directly, so find_clusters / run_umap work on the joint WNN graph.

Additional reductions (v0.5.0)

• run_ica (embeddings + loadings) and run_tsne.

Tutorials & docs

• CBMC CITE-seq tutorial extended with a WNN section (run_wnn, Step 8).
• README links made absolute so they render on the PyPI page; test count updated (156).

Install

pip install "shanuz[integration]"   # + Harmony
pip install "shanuz[all]"           # everything

Notes

• WNN uses the roadmap-sanctioned scale-invariant weight approximation (validated by structure recovery, not bit-exact R parity).
• Deferred to future cycles: CCA/RPCA + IntegrateData, v0.3.0 reference mapping, DESeq2 pseudobulk, SketchData/BPCells.

PyPI: https://pypi.org/project/shanuz/0.2.0/
Full diff: v0.1.2...v0.2.0

Shanuz v0.1.1

Spatial transcriptomics (Xenium / Visium / CosMx)

This release adds a spatial analysis layer to shanuz — Seurat-parity loaders and
neighbourhood/niche analysis, validated end-to-end against R Seurat.

Added

• Loaders: load_xenium, load_visium, load_cosmx — each returns a Shanuz
  object with expression and populated per-FOV centroids (.images).
  load_xenium keeps only Gene Expression features by default (matching
  LoadXenium's assay split; keep_controls=True to retain controls).
• Spatial-aware from_anndata — rebuilds .images from obsm['spatial'] +
  obs['fov'] instead of misfiling it as a bogus PCA-style reduction.
• Neighbourhood / niche analysis: get_tissue_coordinates, spatial_knn,
  nearest_neighbor_distance, local_neighborhood, build_niche_assay
  (Seurat v5's BuildNicheAssay), composition_test (directional Fisher/BH
  enrichment across a categorical split).
• Spatial plots: image_dim_plot / image_feature_plot — matplotlib
  centroid scatter, immune to the ggplot2 4.x ImageDimPlot blank-render bug.
• add_module_score(search=True) — case/punctuation-insensitive gene-symbol
  resolution (local UpdateSymbolList stand-in).
• datasets.xenium_mouse_brain() — one-line auto-download (~20 MB) of a
  public 10x Xenium dataset for the new tutorial.
• Tutorial 5 — Xenium spatial (R vs Python): side-by-side R Seurat / shanuz
  walkthrough on a public 10x Xenium mouse-brain section (36,602 cells x 248
  genes — the dataset in Seurat's own spatial vignette). Every deterministic
  anchor (cell counts, marker-defined cell types, nearest-neighbour distances,
  local density, composition test) matches R to 8 significant figures.
• GitHub Actions CI (ruff + pytest across Python 3.10-3.12), py.typed marker.

Notes

• Still open for the spatial milestone (tracked in ROADMAP.md): a MERSCOPE
  loader, FindSpatiallyVariableFeatures (Moran's I), and Visium tissue-image
  (SpatialDimPlot/SpatialFeaturePlot) plots.
• No breaking changes — all additions are backward compatible; the four
  existing tutorials (PBMC 3k, PBMC 8k, CBMC CITE-seq, SCTransform) were rerun
  end-to-end post-merge with no regressions.

Full changelog: v0.1.0...v0.1.1

Shanuz v0.1.0

Shanuz v0.1.0 — First Release

A Python port of the Seurat single-cell RNA-seq analysis framework, algorithmically faithful to Seurat v5.

Features

Core data structures

• Shanuz object mirroring the R Seurat S4 class
• Assay5 — sparse-matrix-backed multi-layer assay with per-layer feature/cell name tracking
• Graph, DimReduc, Neighbor — faithful ports of Seurat's internal structures

Preprocessing

• normalize_data — LogNormalize and CLR (Seurat-exact formula)
• find_variable_features — VST with Seurat-faithful dispersion and LOESS
• scale_data — z-score with ddof=1 (sample SD, matching R)
• percentage_feature_set

Normalization

• sctransform — regularized negative-binomial Pearson residuals; vectorised Poisson IRLS, moment-estimated theta, LOESS regularisation, vars_to_regress support

Signature scoring

• add_module_score — binned control-gene scoring (Tirosh 2016)
• cell_cycle_scoring — S/G2M phase assignment with built-in CC_GENES

Dimensionality reduction & neighbours

• run_pca (scikit-learn, ddof=1 stdev)
• find_neighbors — KNN + fully-sparse SNN (no dense n×n materialisation)
• jack_straw / score_jackstraw — JackStraw permutation test
• run_umap (umap-learn)

Clustering

• find_clusters — Louvain (python-igraph, deterministic igraph RNG seeding) and Leiden (leidenalg)

Differential expression

• find_markers / find_all_markers with test types: wilcox (tie-corrected Mann-Whitney U), t, LR (logistic LRT), negbinom (NB GLM LRT), roc (AUC + power)

Plotting

• dim_plot, feature_plot, vln_plot, dot_plot, elbow_plot, do_heatmap, dim_heatmap, feature_scatter, variable_feature_plot, ridge_plot

AnnData interoperability

• as_anndata, from_anndata

Tutorials

Four end-to-end tutorials validated against the official Seurat vignettes, each pairing R and Python code with side-by-side output plots:

#	Tutorial
1	PBMC 3k — Guided Clustering
2	PBMC 8k — Advanced Subclustering
3	CBMC CITE-seq — Multimodal (RNA + ADT)
4	PBMC 3k — SCTransform

Tests

129 unit tests, all passing.

Installation

git clone https://github.com/GenomicAI/shanuz.git
cd shanuz
pip install -e ".[analysis]"

Algorithms faithfully ported from R Seurat

• Seurat CLR formula (log1p(x / exp(Σ log1p(x>0) / n)))
• VST dispersion with Bessel correction
• Wilcoxon with tie correction (scipy.stats.mannwhitneyu, asymptotic)
• SCTransform NB model (Hafemeister & Satija 2019; Choudhary & Satija 2022)
• AddModuleScore (Tirosh et al. 2016)
• JackStraw permutation test