Changelog#
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]#
Changed#
The documentation is built with
scverse-docon Sphinx 9 and uses its sidebar layout: Getting started, Guides (tutorials, user guide, developer documentation, architecture, FAQ), Reference (API, models) and Project, with a new citation page, following scvi-tools#4091. The Colab launch button on tutorial pages, the download and full screen buttons, and the tutorial filters are kept, and[source]links now point to GitHub instead of highlighted copies of the code.
Fixed#
ResolVI.setup_anndata(..., prepare_data=True)now stores each cell’s true k nearest spatial neighbors inobsm["index_neighbor"], with squared Euclidean distances inobsm["distance_neighbor"]. Before, the scanpy distance graph was squared with**, which on a sparse matrix is the matrix power, so cells got neighbors of neighbors (almost no overlap with the true spatial kNN). Neighbors cached in an AnnData by an older release are recomputed on the nextsetup_anndatacall. resolVI models trained withprepare_data=Trueshould be retrained. Reported by Giacomo Cinnirella.pip install "scviva-tools[all]"works on macOS and Windows again. The RAPIDS packages in therapids,rapids-cuda12andrapids-cuda13extras (cuML, cuGraph, cuPy, rapids-singlecell) are now installed only on Linux, the only platform RAPIDS supports. Before,[all]pulled incupy, whose source build fails on macOS withError: macOS is no longer supported.import scvivanow loads thedata,external,model,module,trainandutilssubpackages, asimport scvidoes, soscviva.model.ResolVI,scviva.external.Tangramand similar paths work without a separate import. Before, they raisedAttributeError: module 'scviva' has no attribute 'model'unless the submodule had already been imported elsewhere, for example byfrom scviva.model._resolvi import ResolVI.scviva.tl.HarremanAnalysis.setup()is several hundred times faster under pandas 3: about 4 s instead of 20–45 min on a 2,600-spot Visium section with 31k genes. Under pandas 3,AnnData.var_namesis backed by Arrow strings, and the interaction-database builders (extract_lr_pairs,build_LR_matrixandextract_transporter_infoinscviva.tools.harreman.preprocessing.database) calledSeries.isinagainst it once per interaction, which re-converts the whole gene index on every call. Gene membership is now checked against a set. The resulting tables are unchanged.Ligand-receptor interactions are grouped under their CellChat
pathway_nameagain inscviva.tl.HarremanAnalysis.compute_cell_communication(), in both"standard"and"cell_type"mode. The relabeling used a chained assignment, which pandas 3 copy-on-write turns into a silent no-op, so metabolite-level results andadata.uns["gene_pair_dict"]were keyed by individual interaction names (e.g.CCL19_CCR7) instead of pathways.
[0.1.8] - 2026-10-28#
Changed#
Harreman and VISION accessor methods now expose their real arguments. The
ha.hs,ha.vs,ha.tl,ha.pl(HarremanAnalysis) andva.tl(VisionAnalysis) methods were(adata=None, **kwargs)wrappers without docstrings, sohelp(), IDE tooltips and the API docs showed no arguments. They are now built by a newscviva.tools._accessor.adata_delegatehelper that copies the signature and docstring of the forwarded function (adataoptional, remaining arguments keyword-only). Call syntax is unchanged and existing code and tutorials keep working.Accessor classes renamed to public names and exported:
scviva.tools.harreman.HarremanHotspotAccessor,HarremanVisionAccessor,HarremanToolsAccessor,HarremanPlottingAccessor, andscviva.tools.vision.VisionToolsAccessor.Fix
scviva.model.DestVI.from_rna_model()with ascvi.model.CondSCVItrained with the defaultprior="normal": it raised aKeyErrorwhenpriorwas not passed explicitly and aTypeErrorbecause the VampPrior fromscvi.model.CondSCVI.get_vamp_prior()was registered as numpy buffers. The VampPrior ofscviva.module.MRDeconvis now built from its buffers, so it follows the module to GPU and MPS devices.poochandigraphare now imported lazily and guarded with thescvi.utils.dependencies()decorator, soimport scvivano longer requires them.poochis needed only by the Harreman dataset/database loaders (load_visium_mouse_colon_dataset,load_slide_seq_human_lung_dataset,load_metabolic_genes,extract_transporter_info,extract_lr_pairs) andigraphonly by VISION clustering (VisionAnalysis._cluster_cells); calling them without the package installed raises a clearModuleNotFoundErrornaming it.igraphmoved from the core dependencies to thetutorialsextra (poochis already in thespatialextra).
Documentation#
Expanded the installation page following the scvi-tools one: a “Prerequisites” section on creating a virtual environment with
conda(Miniforge/Mamba) orvenv(uv), GPU/PyTorch notes, the full list of optional extras (cuda,metal,tpu,hub,vision,rapids-cuda12, …), Google Colab and Docker sections.Google Colab support for the tutorials: notebook pages now have an “Open in Colab” launch button (
launch_buttonsindocs/conf.py), and every tutorial starts with the same install cell that, only inside Colab, runs the scvi-colab helper and installsscviva-tools[tutorials]plus the tutorial-specific packages. This replaces the previous per-notebook install cells, which either did not install scviva-tools (DiagVI) or installed packages outside of Colab as well.Tutorials no longer require
rapids_singlecell. Each tutorial that uses it has a dedicated cell that setsHAS_RSCwhenrapids_singlecellis importable and a GPU is usable (so a CPU runtime on Google Colab is handled), and the neighbors/UMAP steps fall back to scanpy otherwise. Unusedimport rapids_singlecell as rsclines were removed (cell2location, Stereoscope, Tangram, Harreman).New “Analysis accessors” section in the User API listing the accessor classes.
Added an autosummary class template (
docs/_templates/autosummary/class.rst) so class pages render full documentation for every method and attribute, not only a table of names. Methods thatscviva.module.*classes inherit fromtorch.nn.Moduleare left out to keep those pages readable.User/Developer API pages now list every public object:
DIAGVI, the VISION plotting functions (scviva.pl.vision.*), thescviva.tools.visionfunctions and containers, the Harreman hotspot/tools/preprocessing/datasets functions, andscviva.utils.Docstrings (text only, no signature or behavior changes): documented the missing constructor arguments of
DestVI,ResolVI,Tangram,nicheVAE,NicheDecoder,VisionResultsand the accessor classes; documented where**kwargsare forwarded in model constructors,setup_anndata/from_rna_model/from_spatialdataand other model methods,VisionAnalysis.compute_latent_space/generate_projections/pool_cells, andscviva.tools.vision.rank_genes_groups; fixed parameter names in docstrings that no longer matched the signature (DestVI.from_rna_model**module_kwargs,Tangramsc_adata,NicheDecoder.forward*cat_list).Fixed RST list formatting in the
calculate_super_module_scores,select_significant_interactionsandDIAGVI.traindocstrings, and added theBoyeau19andIonides2008references cited by inherited scvi-tools docstrings, so the docs build (-W) stays warning-free now that every method is rendered.Completed the remaining parameter documentation (text only, no signature changes) for the VISION plotting functions,
plot_interaction_module_correlation,plot_connectivity_distribution,VisionAnalysismethods,SCVIVA.setup_anndataandget_latent_representation,DIAGVI.from_spatialdata/predict_celltype, theJVAEandnicheVAEmodule methods,create_modules,rank_genes_groups,resolve_device/stats_dtype, and thesetup_anndatamethods ofGIMVIand the Stereoscope models; added docstrings toDirichletDecoder.forwardand theget_field_datamethods of the spatial data fields.
Fixed#
GIMVI.save(..., save_anndata=True, **anndata_write_kwargs)now passesanndata_write_kwargs(e.g.compression="gzip") toAnnData.write; they were previously accepted and silently ignored.scviva.tools.vision.rank_genes_groupsnow raises a clearValueErrorformethod="t-test","t-test_overestim_var"or"logreg", which were advertised but never ported (they failed with anAttributeError).method=Nonenow selects"wilcoxon"instead of the unported"t-test". Signatures are unchanged.
[0.1.7] - 2026-09-10#
Added#
Native Apple Silicon (MPS) support for scviva-tools’ own harreman/hotspot code.
scviva.utils.resolve_devicenow resolvesdevice="auto"tomps(previously cuda→cpu only, so Mac GPUs were silently ignored). Since MPS has no float64 kernel support at all (a Metal hardware limitation, not a version gap), every local-correlation/-autocorrelation and cell-cell-communication routine that used to hard-codetorch.float64now uses the newscviva.utils.stats_dtype(device)helper, which returnsfloat32onmpsand keepsfloat64oncpu/cuda. Models that train via scvi-tools’ Lightning trainer (GimVI, DestVI, ResolVI, DiagVI, Stereoscope, Tangram, SCVIVA’s NicheVAE) can train onmpsonce scvi-tools resolvesaccelerator="mps"— either passed explicitly, or viaaccelerator="auto"when theSCVI_ALLOW_MPS_AUTO=1environment variable is set. scvi-tools’ ownautoresolution deliberately keeps defaulting tocpuotherwise (seescvi.model._utils.parse_device_args) so existing users’ behavior doesn’t silently change; the newtest_mps.yamlCI workflow (below) sets that variable so these models are actually exercised onmpsin CI, not just the harreman/hotspot code. Verified end-to-end training on MPS for ResolVI and SCVIVA specifically, since both sample rawtorch/pyroGamma/Dirichlet/Poisson distributions (native MPS kernels as of torch 2.14) outside ofscvi.distributions’ own MPS guards. Also fixedResolVI.compute_dataset_dependent_priorsreturning numpyfloat64scalars (background_ratio,median_distance, etc.) thatRESOLVAEregisters as buffers viatorch.tensor(...); on MPS this silently inherited float64 and crashed on.to("mps")during module setup — now cast to Pythonfloat, matching the existingfloat(...)idiom already used fordownsample_counts_mean/stdin_resolvae.py. Full test suite (271 tests) passes identically on CPU and MPS.Dedicated MPS CI workflow (
.github/workflows/test_mps.yaml), mirroring scvi-tools’ owntest_mps.yaml: runs the full test suite on a real Apple Silicon GitHub-hosted runner (macos-14) withSCVI_ALLOW_MPS_AUTO=1,PYTORCH_ENABLE_MPS_FALLBACK=0, andPYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0soaccelerator="auto"-trained models actually exercisempsinstead of silently staying oncpu. Adds the correspondingtest-metalhatch environment (metal+spatialfeatures) topyproject.toml, mirroring the existingtest-cudaenv. Gated the same way astest_macos.yaml/test_cuda.yaml: PR label (mps tests/all tests), daily schedule, or manual dispatch.DiagVI model (
scviva.external.diagvi.DIAGVI), migrated from scvi-tools, for cross-modality alignment of paired spatial transcriptomics/proteomics data via a shared latent space with graph-guided and optimal-transport (Sinkhorn) losses; ships with two new tutorials (DiagVI_spatial_transcriptomics,DiagVI_spatial_proteomics). Its optionalgeomloss/torch-geometricdependencies are covered by the existingscviva-tools[spatial]extra.Shared
CyclicMultiDataLoader(scviva.model.utils._dataloaders), consolidating the near-identical cyclic-batch dataloader previously duplicated between GIMVI and DiagVI.VISION signature-scoring and differential-expression toolkit (
scviva.tools.vision.VisionAnalysis), ported fromvisionpy/R VISION :cite:p:DeTomaso19into scviva-tools with a subpackage layout mirroring Harreman’s (preprocessing/,tools/,phylo/): per-cell signature scoring, KNN-graph autocorrelation (Geary’s C), one-vs-all/one-vs-one differential expression, gene-importance ranking, signature clustering, and micro-clustering/meta-cluster pooling. Ships with a standaloneVision_tutorialnotebook, a new VISION section inDestVI_tutorial, and adocs/user_guide/models/vision.mdmodel page.Harreman-VISION integration (
scviva.tools.harreman.vision,HarremanAnalysis.vs), letting VISION signature scores be computed on top of an existing Harreman KNN graph and cross-referenced against Harreman’s Hotspot gene modules (integrate_vision_hotspot_results).scviva.plotting.vision: VISION-specific plotting functions, split out ofscviva.plotting.harremanto mirror thetools/visionvstools/harremansplit.
Changed#
DiagVI now built on
SpatialBaseModel(setup_spatialdata(), RAPIDS backend support) instead of a standaloneBaseModelClass.Docs theme: the default Read the Docs search panel was replaced with the scviva-tools logo; project scaffolding updated to scverse cookiecutter v0.8.
CI: GitHub Actions workflows updated for Python 3.14; CUDA workflows no longer cache pip installs, avoiding repeated 10GB cache-quota evictions.
Docs builds now treat warnings as errors (
sphinx-build -W), enforced both on Read the Docs (sphinx.fail_on_warning) and in a new CIdocsjob, mirroring scvi-tools’ own doc-build hardening.myst_heading_anchorsenabled so in-page[text](#anchor)links resolve; deprecatedlogo_onlytheme option removed; PyTorch’s intersphinx inventory URL updated todocs.pytorch.org.
Fixed#
VISION R-fidelity audit: correctness and reproducibility fixes found by auditing the port against the original R VISION implementation:
Protein one-vs-all differential results were computed but discarded (only the storage key was written); now persisted
Degenerate two-site contingency tables now report “not significant” like R’s
matrix_chisq, instead of maximal significanceGene importance now uses covariance (matching R’s
evalSigGeneImportance/sigGeneInner) instead of a scale-free Pearson correlationAdded R’s Wilcoxon continuity correction to one-vs-all differential expression, with a defensive
p<=1clipMeta-variable one-vs-all differential now applies one joint BH-FDR across numeric and categorical tests per group, matching
clusterSigScoresSignature clustering rewritten as a BIC-selected Gaussian mixture over significant signatures (approximating R’s
Mclust“EII”), replacing plain Ward/Euclidean clusteringsig_norm_methodnow threads into the Geary’s C permutation-null background scoring (previously hardcoded), removing an unnormalized raw-matmul code pathMicro-clustering’s
K/filter_thresholddefaults corrected to match R’s actual formulas (5% of cells, no artificial floor)pool_metadatanow reports0.0(notNaN) for categorical levels a pool doesn’t contain, matching R’spoolMetaDataFixed a
visionpy-inherited bug in the dense-matrix path ofcompute_signatures_anndata: the z-score denominator divided variance by gene count before the square root, inflating scores by an extrasqrt(n_genes)factor relative to R and this module’s own sparse pathnorm_data_keyinput is now auto-detected as already log-transformed (and left alone) instead of being re-transformed; docstring corrected (R’s actual contract is the opposite of what was documented)device="cpu"now forces the deterministic scipy sparse path instead of a non-bit-reproducible multi-threaded dense PyTorch path; Louvain clustering, K-means readjustment, and permutation-null background generation are now all seeded via newrandom_stateparameters (default0, so existing calls are unaffected)
VISION correctness: fixed BH-FDR index scrambling and tie-correction/NaN bugs in
diffexp, KNN self-loop bias, and several silentuse_raw/signature-splitting regressionsVISION:
_infer_obs_columns()no longer treats all-unique non-categorical columns (e.g. barcode/identifier columns) as usable metadata, which previously crashed differential expression on real metadata;compute_signature_scores()now restoresadata.uns["signature_varm_key"]after the permutation-null step instead of leaving it pointed at the transient random-signature set (which brokeintegrate_vision_hotspot_results());VisionAnalysisnow tracks whether it builtadata.obsp["weights"]itself, so it correctly reuses an externally-built graph (e.g. from Harreman) instead of silently overwriting itVISION:
import scvivano longer eagerly pulls indiffexp(and therefore scanpy);rank_genes_groupsis now exposed lazily.HarremanAnalysis.vs.compute_vision_signatures()now has explicit defaults instead of forwarding**kwargs, fixing the no-arg legacy call path;load_signatures()now accepts avarm_keyand writes toadata.raw.varm[varm_key]underuse_raw=True, fixing a raw/non-raw gene-count mismatch crash; small (<=5) signature sets now get correctly aligned random-background cluster labelsVISION:
compute_obs_df_scores()/_gearysc_for_dataframe()no longer raiseZeroDivisionErroron constant (zero-variance) numericobscolumns; these are now skipped and reported as “no detectable autocorrelation”Harreman: fixed
use_rawcrashes and silent bugs (.raw.obs, gene-subset views into.raw.X, a database-storage key mismatch) and unseeded RNGs across the hotspot, cell-communication, and KNN modulesDiagVI: corrected reference-batch/libsize imputation,
mapping_dfcollisions, and unlabeled-cell leakage into the classifier loss31 pre-existing Sphinx warnings uncovered by the new
-Wbuild, all docs/type-hint only with no runtime behavior change:Stale
:doc:tutorial cross-refs inDestVI/GIMVI/SCVIVA/RNAStereoscope/SpatialStereoscope/Tangramdocstrings pointed at a scvi-tools-styletutorials/notebooks/...path that doesn’t match this repo’s flatdocs/tutorials/layout; also dropped a reference to an R tutorial that was never ported hereMalformed numpydoc bullet lists (missing blank line before/after) in
nicheVAE’s andSpatialPredictiveMixin’s docstringsnp.array/Union[np.array, None]type annotations corrected tonp.ndarray/np.ndarray | Nonein_de_utils.py/_results_dataclass.py; stray quote removed from a docstring summary lineMissing
Ingelfinger25(CytoVI) BibTeX entry, copied from upstream scvi-tools’references.bibRESOLVAE/MRDeconvremoved from thedocs/api/developer.mdautosummary listing — these classes don’t exist yet (tracked as future work), so autosummary failed to import themdocs/architecture/index.mdadded to the developer-docs toctree (was orphaned)Cross-project refs to scvi-tools’ own MrVI/CytoVI/scVI docs converted from broken local
{doc}roles to plain external linksThree graphical-model SVGs referenced by
diagvi.md/stereoscope.mdwere missing from this repo; imported from upstream scvi-tools’docs/user_guide/models/figures/into the same path here. One broken ref to a never-writtencounterfactual_predictionbackground page dropped
Removed#
Confirmed-dead VISION code with no remaining call sites, found via a post-audit sweep:
tools/diffexp.py::_calc_frac()(logic already computed inline elsewhere) and_analysis.py::_pearson_cols()(orphaned by the gene-importance fix above).
[0.1.6] - 2026-07-08#
Fixed#
Harreman: pandas 3.0 always-on copy-on-write broke three in-place mutation sites that relied on
.valuesreturning a writable view:create_modulesraisedValueError: underlying array is read-onlyonnp.fill_diagonal; now forces a real copy viato_numpy(copy=True)run_cell_communication_analysishit the samefill_diagonalfailure on the symmetric LC Z-score matrix; now mutates a copy and writes it back via.loc[:, :]extract_lr_pairsraisedValueError: Length of indexer and values mismatchbecause pandas 3.0’s default Arrow-backed string dtype no longer allows storing variable-length arrays into single-element slots; ligand/receptor columns now useto_numpy(dtype=object, copy=True)to restore plain, guaranteed-writable object-array semantics
[0.1.5] - 2026-07-06#
Added#
Tangram model for mapping scRNA-seq to spatial transcriptomics (
scviva.external.Tangram), a PyTorch reimplementation supporting “cells” and “constrained” cell-to-spot mapping modesHarreman downstream tool for cell-cell communication and metabolic exchange analysis (
scviva.tl.harreman,scviva.pl.harreman), integrating outputs from DestVI, ResolVI, and SCVIVASpatialPredictiveMixin: unified predictive mixin shared by ResolVI and SCVIVA, replacing the ResolVI-onlyResolVIPredictiveMixinscviva.tl/scviva.pltop-level namespace aliases, mirroring scanpy’ssc.tl/sc.plconventionDedicated CI job for optional/slow integration tests (real model training)
Changed#
Package renamed from
spatialvi-toolstoscviva-toolson PyPI (import namescvivaunchanged); docs and install instructions updated accordingly
Fixed#
Tangram: gene-mismatch validation in
setup_mudata, andget_mapper_matrixfiltering underconstrained=TrueHarreman: import/namespace bugs from the initial port that made the package unimportable, plus a broken plotting accessor and a model-recognition constant typo
[0.1.3] - 2026-04-13#
Changed#
Cleanup: dropped dead code (MLflow/JAX settings, a stale config re-export, a trivial method alias, stale in-source dev comments) and simplified the lazy model map
Refactored
SCVIVA’s predictive methods to share a common decoder helper, and tidied up several module-level imports; moved a few internal modules underutils/for consistency with scvi-tools conventions
Fixed#
scikit-learn>=1.4moved from test-only to core dependencies (required by SCVIVA/ResolVI at runtime); removed redundantanndata/scanpytest-extra pins
Documentation#
Added installation guide, FAQ, API reference stubs, developer/contributing guides, and user-guide background/use-case pages
[0.1.2] - 2026-04-12#
Fixed#
RNADeconv.__init__: readmodel_kwargs['ct_weight']instead of the incorrectmodel_kwargs['ct_prop']; the mismatched key caused aKeyErrorwheneverct_weightwas passed, making class-reweighted training unusableJVAE.generative: replacey.type.squeeze(-1)withy.squeeze(-1).long()for the gene-label dispersion branch;y.typeis Python’s built-intype()bound on the tensor object, so any run withdispersion='gene-label'crashed before reaching theone_hotencodingAdded regression tests for both fixes (all 78 tests pass)
[0.1.1] - 2026-04-12#
Added#
GIMVI model for joint imputation of missing genes across paired scRNA-seq and spatial transcriptomics data, based on :cite:p:
Lopez19Stereoscope model for probabilistic cell-type deconvolution of spatial transcriptomics spots (
spatialvi.external.Stereoscope)Tutorials:
gimvi_tutorial,stereoscope_heart_LV_tutorial,cell2location_lymph_node_spatial_tutorial, andtangram_scvi_toolsRegression test suites for GIMVI and Stereoscope (upstream parity tests)
[0.1.0] - 2026-03-25#
Added#
Initial package with DestVI, ResolVI, and scVIVA models
SpatialBaseModelshared base infrastructureSpatialNeighborhoodMixinfor neighbor graph computation (squidpy + RAPIDS backends)SpatialDeconvolutionMixinfor cell-type deconvolutionSpatialData integration via
setup_spatialdata()andfrom_spatialdata()squidpy neighbor computation backend
RAPIDS acceleration backend (
backend="rapids")Custom AnnData fields:
SpatialCoordsField,NeighborhoodGraphField