Release notes

Starting from version 0.20.1, this format is based on Keep a Changelog, and this project adheres to Semantic Versioning. Full commit history is available in the commit logs.

Version 1.2

1.2.0 (2024-09-26)

Added

• Add support for Python 3.12 #2966.

• Add support for categorial covariates in scArches in scvi.model.archesmixin #2936.

• Add assertion error in cellAssign for checking duplicates in celltype markers #2951.

• Add scvi.external.poissonvi.get_region_factors #2940.

• scvi.settings.dl_persistent_workers allows using persistent workers in scvi.dataloaders.AnnDataLoader #2924.

• Add option for using external indexes in data splitting classes that are under scvi.dataloaders by passing external_indexing=list[train_idx,valid_idx,test_idx] as well as in all models available #2902.

• Add warning if creating data splits in scvi.dataloaders that create last batch with less than 3 cells #2916.

• Add new experimental functional API for hyperparameter tuning with scvi.autotune.run_autotune() and scvi.autotune.AutotuneExperiment to replace scvi.autotune.ModelTuner, scvi.autotune.TunerManager, and scvi.autotune.TuneAnalysis #2561.

• Add experimental class scvi.nn.Embedding implementing methods for extending embeddings #2574.

• Add experimental support for representing batches with continuously-valued embeddings by passing in batch_representation="embedding" to scvi.model.SCVI #2576.

• Add experimental mixin classes scvi.model.base.EmbeddingMixin and scvi.module.base.EmbeddingModuleMixin #2576.

• Add option to generate synthetic spatial coordinates in scvi.data.synthetic_iid() with argument generate_coordinates #2603.

• Add experimental support for using custom lightning.pytorch.core.LightningDataModules in scvi.autotune.run_autotune() #2605.

• Add scvi.external.VELOVI for RNA velocity estimation using variational inference #2611.

• Add unsigned argument to scvi.hub.HubModel.pull_from_s3() to allow for unsigned downloads of models from AWS S3 #2615.

• Add support for batch_key in scvi.model.CondSCVI.setup_anndata() #2626.

• Add support for scvi.model.base.RNASeqMixin() in scvi.model.CondSCVI #2915.

• Add load_best_on_end argument to scvi.train.SaveCheckpoint to load the best model state at the end of training #2672.

• Add experimental class scvi.distributions.BetaBinomial implementing the Beta-Binomial distribution with mean-dispersion parameterization for modeling scBS-seq methylation data #2692.

• Add support for custom dataloaders in scvi.model.base.VAEMixin methods by specifying the dataloader argument #2748.

• Add option to use a normal distribution in the generative model of scvi.model.SCVI by passing in gene_likelihood="normal" #2780.

• Add scvi.external.MRVI for modeling sample-level heterogeneity in single-cell RNA-seq data #2756.

• Add support for reference mapping with mudata.MuData models to scvi.model.base.ArchesMixin #2578.

• Add argument return_mean to scvi.model.base.VAEMixin.get_reconstruction_error() and scvi.model.base.VAEMixin.get_elbo() to allow computation without averaging across cells #2362.

• Add support for setting weights="importance" in scvi.model.SCANVI.differential_expression() #2362.

Changed

• Deprecate scvi.data.cellxgene(), to be removed in v1.3. Please directly use the cellxgene-census instead #2542.

• Deprecate scvi.nn.one_hot(), to be removed in v1.3. Please directly use the one_hot function in PyTorch instead #2608.

• Deprecate scvi.train.SaveBestState, to be removed in v1.3. Please use scvi.train.SaveCheckpoint instead #2673.

• Deprecate save_best argument in scvi.model.PEAKVI.train() and scvi.model.MULTIVI.train(), to be removed in v1.3. Please pass in enable_checkpointing or specify a custom checkpointing procedure with scvi.train.SaveCheckpoint instead #2673.

• Move scvi.model.base._utils._load_legacy_saved_files() to scvi.model.base._save_load._load_legacy_saved_files() #2731.

• Move scvi.model.base._utils._load_saved_files() to scvi.model.base._save_load._load_saved_files() #2731.

• Move scvi.model.base._utils._initialize_model() to scvi.model.base._save_load._initialize_model() #2731.

• Move scvi.model.base._utils._validate_var_names() to scvi.model.base._save_load._validate_var_names() #2731.

• Move scvi.model.base._utils._prepare_obs() to scvi.model.base._de_core._prepare_obs() #2731.

• Move scvi.model.base._utils._de_core() to scvi.model.base._de_core._de_core() #2731.

• Move scvi.model.base._utils._fdr_de_prediction() to scvi.model.base._de_core_._fdr_de_prediction() #2731.

• scvi.data.synthetic_iid() now generates unique variable names for protein and accessibility data #2739.

• The data_module argument in scvi.model.base.UnsupervisedTrainingMixin.train() has been renamed to datamodule for consistency #2749.

• Change the default saving method of variable names for mudata.MuData based models (e.g. scvi.model.TOTALVI) to a dictionary of per-mod variable names instead of a concatenated array of all variable names. Users may replicate the previous behavior by passing in legacy_mudata_format=True to scvi.model.base.BaseModelClass.save() #2769.

• Changed internal activation function in scvi.nn.DecoderTOTALVI to Softplus to increase numerical stability. This is the new default for new models. Previously trained models will be loaded with exponential activation function #2913.

Fixed

• Fix logging of accuracy for cases with 1 sample per class in scANVI #2938.

• Disable adversarial classifier if training with a single batch. Previously this raised a None error #2914.

• get_normalized_expression() fixed for Poisson distribution and Negative Binomial with latent_library_size #2915.

• Fix scvi.module.VAE.marginal_ll() when n_mc_samples_per_pass=1 #2362.

• scvi.module.VAE.marginal_ll() when n_mc_samples_per_pass=1 #2362.

• Enable option to drop_last minibatch during training by datasplitter_kwargs={"drop_last": True} #2926.

• Fix JAX to be deterministic on CUDA when seed is manually set #2923.

Removed

• Remove scvi.autotune.ModelTuner, scvi.autotune.TunerManager, and scvi.autotune.TuneAnalysis in favor of new experimental functional API with scvi.autotune.run_autotune() and scvi.autotune.AutotuneExperiment #2561.

• Remove feed_labels argument and corresponding code paths in scvi.module.SCANVAE.loss() #2644.

• Remove scvi.train._callbacks.MetricsCallback and argument additional_val_metrics in scvi.train.Trainer #2646.

Version 1.1

1.1.6 (2024-08-19)

Fixed

• Breaking change: In scvi.autotune._manager we changed the parameter in RunConfig from local_dir to storage_path see issue 2908 #2689.

1.1.5 (2024-06-30)

1.1.4 (2024-06-30)

Added

• Add argument return_logits to scvi.external.SOLO.predict() that allows returning logits instead of probabilities when passing in soft=True to replicate the buggy behavior previous to v1.1.3 #2870.

1.1.3 (2024-06-26)

Fixed

• Breaking change: Fix scvi.external.SOLO.predict() to correctly return probabiities instead of logits when passing in soft=True (the default option) #2689.

• Breaking change: Fix scvi.dataloaders.SemiSupervisedDataSplitter to properly sample unlabeled observations without replacement #2816.

1.1.2 (2024-03-01)

Changed

• Address AnnData >= 0.10 deprecation warning for anndata.read() by replacing instances with anndata.read_h5ad() #2531.

• Address AnnData >= 0.10 deprecation warning for anndata._core.sparse_dataset.SparseDataset by replacing instances with anndata.experimental.CSCDataset and anndata.experimental.CSRDataset #2531.

1.1.1 (2024-02-19)

Fixed

• Correctly apply non-default user parameters in scvi.external.POISSONVI #2522.

1.1.0 (2024-02-13)

Added

• Add scvi.external.ContrastiveVI for contrastiveVI #2242.

• Add scvi.dataloaders.BatchDistributedSampler for distributed training #2102.

• Add additional_val_metrics argument to scvi.train.Trainer, allowing to specify additional metrics to compute and log during the validation loop using scvi.train._callbacks.MetricsCallback #2136.

• Expose accelerator and device arguments in scvi.hub.HubModel.load_model() pr{2166}.

• Add load_sparse_tensor argument in scvi.data.AnnTorchDataset for directly loading SciPy CSR and CSC data structures to their PyTorch counterparts, leading to faster data loading depending on the sparsity of the data #2158.

• Add per-group LFC information to scvi.criticism.PosteriorPredictiveCheck.differential_expression(). metrics["diff_exp"] is now a dictionary where summary stores the summary dataframe, and lfc_per_model_per_group stores the per-group LFC #2173.

• Expose torch.save() keyword arguments in scvi.model.base.BaseModelClass.save and scvi.external.GIMVI.save #2200.

• Add model_kwargs and train_kwargs arguments to scvi.autotune.ModelTuner.fit() #2203.

• Add datasplitter_kwargs to model train methods #2204.

• Add use_posterior_mean argument to scvi.model.SCANVI.predict() for stochastic prediction of celltype labels #2224.

• Add support for Python 3.10+ type annotations in scvi.autotune.ModelTuner #2239.

• Add option to log device statistics in scvi.autotune.ModelTuner.fit() with argument monitor_device_stats #2260.

• Add option to pass in a random seed to scvi.autotune.ModelTuner.fit() with argument seed #2260.

• Automatically log the learning rate when reduce_lr_on_plateau=True in training plans #2280.

• Add scvi.external.POISSONVI to model scATAC-seq fragment counts with a Poisson distribution #2249

• scvi.train.SemiSupervisedTrainingPlan now logs the classifier calibration error #2299.

• Passing enable_checkpointing=True into train methods is now compatible with our model saves. Additional options can be specified by initializing with scvi.train.SaveCheckpoint #2317.

• scvi.settings.dl_num_workers is now correctly applied as the default num_workers in scvi.dataloaders.AnnDataLoader #2322.

• Passing in indices to scvi.criticism.PosteriorPredictiveCheck allows for running metrics on a subset of the data #2361.

• Add seed argument to scvi.model.utils.mde() for reproducibility #2373.

• Add scvi.hub.HubModel.save() and scvi.hub.HubMetadata.save() #2382.

• Add support for Optax 0.1.8 by renaming instances of optax.additive_weight_decay() to optax.add_weight_decay() #2396.

• Add support for hosting scvi.hub.HubModel on AWS S3 via scvi.hub.HubModel.pull_from_s3() and scvi.hub.HubModel.push_to_s3() #2378.

• Add clearer error message for scvi.data.poisson_gene_selection() when input data does not contain raw counts #2422.

• Add API for using custom dataloaders with scvi.model.SCVI by making adata argument optional on initialization and adding optional argument data_module to scvi.model.base.UnsupervisedTrainingMixin.train() #2467.

• Add support for Ray 2.8-2.9 in scvi.autotune.ModelTuner #2478.

Fixed

• Fix bug where n_hidden was not being passed into scvi.nn.Encoder in scvi.model.AmortizedLDA #2229

• Fix bug in scvi.module.SCANVAE where classifier probabilities were interpreted as logits. This is backwards compatible as loading older models will use the old code path #2301.

• Fix bug in scvi.external.GIMVI where batch_size was not properly used in inference methods #2366.

• Fix error message formatting in scvi.data.fields.LayerField.transfer_field() #2368.

• Fix ambiguous error raised in scvi.distributions.NegativeBinomial.log_prob() and scvi.distributions.ZeroInflatedNegativeBinomial.log_prob() when scale not passed in and value not in support #2395.

• Fix initialization of scvi.distributions.NegativeBinomial and scvi.distributions.ZeroInflatedNegativeBinomial when validate_args=True and optional parameters not passed in #2395.

• Fix error when re-initializing scvi.external.GIMVI with the same datasets #2446.

Changed

• Replace sparse with sparse_format argument in scvi.data.synthetic_iid() for increased flexibility over dataset format #2163.

• Revalidate devices when automatically switching from MPS to CPU accelerator in scvi.model._utils.parse_device_args() #2247.

• Refactor scvi.data.AnnTorchDataset, now loads continuous data as numpy.float32 and categorical data as numpy.int64 by default #2250.

• Support fractional GPU usage in scvi.autotune.ModelTuner pr{2252}.

• Tensorboard is now the default logger in scvi.autotune.ModelTuner pr{2260}.

• Match momentum and epsilon in scvi.module.JaxVAE to the default values in PyTorch #2309.

• Change scvi.train.SemiSupervisedTrainingPlan and scvi.train.ClassifierTrainingPlan accuracy and F1 score computations to use "micro" reduction rather than "macro" #2339.

• Internal refactoring of scvi.module.VAE.sample() and scvi.model.base.RNASeqMixin.posterior_predictive_sample() #2377.

• Change xarray and sparse from mandatory to optional dependencies #2480.

• Use anndata.experimental.CSCDataset and anndata.experimental.CSRDataset instead of the deprecated anndata._core.sparse_dataset.SparseDataset for type checks #2485.

• Make use_observed_lib_size argument adjustable in scvi.module.LDVAE pr{2494}.

Removed

• Remove deprecated use_gpu argument in favor of PyTorch Lightning arguments accelerator and devices #2114.

• Remove deprecated scvi._compat.Literal class #2115.

• Remove chex dependency #2482.

Version 1.0

1.0.4 (2023-10-13)

Added

• Add support for AnnData 0.10.0 #2271.

1.0.3 (2023-08-13)

Changed

• Disable the default selection of MPS when accelerator="auto" in Lightning #2167.

• Change JAX models to use dict instead of flax.core.FrozenDict according to the Flax migration guide google/flax#3191 #2222.

Fixed

• Fix bug in scvi.model.base.PyroSviTrainMixin where training_plan argument is ignored #2162.

• Fix missing docstring for unlabeled_category in scvi.model.SCANVI.setup_anndata and reorder arguments #2189.

• Fix Pandas 2.0 unpickling error in scvi.model.base.BaseModelClas.convert_legacy_save() by switching to pandas.read_pickle() for the setup dictionary #2212.

1.0.2 (2023-07-05)

Fixed

• Fix link to Scanpy preprocessing in introduction tutorial #2154.

• Fix link to Ray Tune search API in autotune tutorial #2154.

1.0.1 (2023-07-04)

Added

• Add support for Python 3.11 #1977.

Changed

• Upper bound Chex dependency to 0.1.8 due to NumPy installation conflicts #2132.

1.0.0 (2023-06-02)

Added

• Add scvi.criticism.PosteriorPredictiveCheck for model evaluation #2058.

• Add scvi.data.reads_to_fragments() for scATAC data #1946

• Add default stacklevel for warnings in scvi.settings #1971.

• Add scBasset motif injection procedure #2010.

• Add importance sampling based differential expression procedure #1872.

• Raise clearer error when initializing scvi.external.SOLO from scvi.model.SCVI with extra categorical or continuous covariates #2027.

• Add option to generate mudata.MuData in scvi.data.synthetic_iid() #2028.

• Add option for disabling shuffling prior to splitting data in scvi.dataloaders.DataSplitter #2037.

• Add scvi.data.AnnDataManager.create_torch_dataset() and expose custom sampler ability #2036.

• Log training loss through Lightning’s progress bar #2043.

• Filter Jax undetected GPU warnings #2044.

• Raise warning if MPS backend is selected for PyTorch, see pytorch/pytorch#77764 #2045.

• Add deregister_manager function to scvi.model.base.BaseModelClass, allowing to clear scvi.data.AnnDataManager instances from memory #2060.

• Add option to use a linear classifier in scvi.model.SCANVI #2063.

• Add lower bound 0.12.1 for Numpyro dependency #2078.

• Add new section in scBasset tutorial for motif scoring #2079.

Fixed

• Fix creation of minified adata by copying original uns dict #2000. This issue arises with anndata>=0.9.0.

• Fix scvi.model.TOTALVI scvi.model.MULTIVI handling of missing protein values #2009.

• Fix bug in scvi.distributions.NegativeBinomialMixture.sample() where theta and mu arguments were switched around #2024.

• Fix bug in scvi.dataloaders.SemiSupervisedDataLoader.resample_labels() where the labeled dataloader was not being reinitialized on subsample #2032.

• Fix typo in scvi.model.JaxSCVI example snippet #2075.

Changed

• Use sphinx book theme for documentation #1673.

• scvi.model.base.RNASeqMixin.posterior_predictive_sample() now outputs 3-d sparse.GCXS matrices #1902.

• Add an option to specify dropout_ratio in scvi.data.synthetic_iid() #1920.

• Update to lightning 2.0 #1961

• Hyperopt is new default searcher for tuner #1961

• scvi.train.AdversarialTrainingPlan no longer encodes data twice during a training step, instead uses same latent for both optimizers #1961, #1980

• Switch back to using sphinx autodoc typehints #1970.

• Disable default seed, run scvi.settings.seed after import for reproducibility #1976.

• Deprecate use_gpu in favor of PyTorch Lightning arguments accelerator and devices, to be removed in v1.1 #1978.

• Docs organization #1983.

• Validate training data and code URLs for scvi.hub.HubMetadata and scvi.hub.HubModelCardHelper #1985.

• Keyword arguments for encoders and decoders can now be passed in from the model level #1986.

• Expose local_dir as a public property in scvi.hub.HubModel #1994.

• Use anndata.concat() internally inside scvi.external.SOLO.from_scvi_model() #2013.

• scvi.train.SemiSupervisedTrainingPlan and scvi.train.ClassifierTrainingPlan now log accuracy, F1 score, and AUROC metrics #2023.

• Switch to cellxgene census for backend for cellxgene data function #2030.

• Change default max_cells and truncation in scvi.model.base.RNASeqMixin._get_importance_weights() #2064.

• Refactor heuristic for default max_epochs as a separate function scvi.model._utils.get_max_epochs_heuristic() #2083.

Removed

• Remove ability to set up ST data in from_rna_model, which was deprecated. ST data should be set up using setup_anndata #1949.

• Remove custom reusable doc decorator which was used for de docs #1970.

• Remove drop_last as an integer from AnnDataLoader, add typing and code cleanup #1975.

• Remove seqfish and seqfish plus datasets #2017.

• Remove support for Python 3.8 (NEP 29) #2021.

Version 0.20

0.20.3 (2023-03-21)

Fixed

• Fix totalVI differential expression when integer sequential protein names are automatically used #1951.

• Fix peakVI scArches test case #1962.

Changed

• Allow passing in map_location into from_dir() and from_dir() and set default to "cpu" #1960.

• Updated tutorials #1966.

0.20.2 (2023-03-10)

Fixed

• Fix return_dist docstring of scvi.model.base.VAEMixin.get_latent_representation() #1932.

• Fix hyperlink to pymde docs #1944

Changed

• Use ruff for fixing and linting #1921, #1941.

• Use sphinx autodoc instead of sphinx-autodoc-typehints #1941.

• Remove .flake8 and .prospector files #1923.

• Log individual loss terms in scvi.module.MULTIVAE.loss() #1936.

• Setting up ST data in from_rna_model is deprecated. ST data should be set up using setup_anndata #1803.

0.20.1 (2023-02-21)

Fixed

• Fixed computation of ELBO during training plan logging when using global kl terms. #1895

• Fixed usage of scvi.train.SaveBestState callback, which affected scvi.model.PEAKVI training. If using PEAKVI, please upgrade. #1913

• Fixed original seed for jax-based models to work with jax 0.4.4. #1907, #1909

New in 0.20.0 (2023-02-01)

Major changes

• Model hyperparameter tuning is available through ModelTuner (beta) #1785,#1802,#1831.

• Pre-trained models can now be uploaded to and downloaded from Hugging Face models using the hub module #1779,#1812,#1828,#1841, #1851,#1862.

• AnnData .var and .varm attributes can now be registered through new fields in fields #1830,#1839.

• SCBASSET, a reimplementation of the original scBasset model, is available for representation learning of scATAC-seq data (experimental) #1839,#1844, #1867,#1874,#1882.

• LowLevelPyroTrainingPlan and PyroModelGuideWarmup added to allow the use of vanilla PyTorch optimization on Pyro models #1845,#1847.

• Add scvi.data.cellxgene() function to download cellxgene datasets #1880.

Minor changes

• Latent mode support changed so that user data is no longer edited in-place #1756.

• Minimum supported PyTorch Lightning version is now 1.9 #1795,#1833,#1863.

• Minimum supported Python version is now 3.8 #1819.

• Poetry removed in favor of Hatch for builds and publishing #1823.

• setup_anndata docstrings fixed, setup_mudata docstrings added #1834,#1837.

• add_dna_sequence() adds DNA sequences to AnnData objects using genomepy #1839,#1842.

• Update tutorial formatting with pre-commit #1850

• Expose accelerators and devices arguments in Trainer #1864.

• Development in GitHub Codespaces is now supported #1836.

Breaking changes

• LossRecorder has been removed in favor of LossOutput #1869.

Bug Fixes

• JaxTrainingPlan now correctly updates global_step through PyTorch Lightning by using a dummy optimizer. #1791.

• CUDA compatibility issue fixed in sample() #1813.

• Device-backed AnnTorchDataset fixed to work with sparse data #1824.

• Fix bug compute_reconstruction_error() causing the first batch to be ignored, see more details in #1854 #1857.

Contributors

• @adamgayoso

• @eroell

• @gokceneraslan

• @macwiatrak

• @martinkim0

• @saroudant

• @vitkl

• @watiss

Version 0.19

New in 0.19.0 (2022-10-31)

Major Changes

• TrainingPlan allows custom PyTorch optimizers #1747.

• Improvements to JaxTrainingPlan #1747 #1749.

• LossRecorder is deprecated. Please substitute with LossOutput #1749

• All training plans require keyword args after the first positional argument #1749

• JaxBaseModuleClass absorbed features from the JaxModuleWrapper, rendering the JaxModuleWrapper obsolote, so it was removed. #1751

• Add scvi.external.Tangram and scvi.external.tangram.TangramMapper that implement Tangram for mapping scRNA-seq data to spatial data #1743.

Minor changes

• Remove confusing warning about kl warmup, log kl weight instead #1773

Breaking changes

• LossRecorder no longer allows access to dictionaries of values if provided during initialization #1749.

• JaxModuleWrapper removed. #1751

Bug Fixes

• Fix n_proteins usage in MULTIVI #1737.

• Remove unused param in MULTIVI #1741.

• Fix random seed handling for Jax models #1751.

Contributors

• @watiss

• @adamgayoso

• @martinkim0

• @marianogabitto

Version 0.18

New in 0.18.0 (2022-10-12)

Major Changes

• Add latent mode support in SCVI #1672. This allows for loading a model using latent representations only (i.e. without the full counts). Not only does this speed up inference by using the cached latent distribution parameters (thus skipping the encoding step), but this also helps in scenarios where the full counts are not available but cached latent parameters are. We provide utility functions and methods to dynamically convert a model to latent mode.

• Added SCAR as an external model for ambient RNA removal #1683.

Minor changes

• Faster inference in PyTorch with torch.inference_mode #1695.

• Upgrade to Lightning 1.6 #1719.

• Update CI workflow to separate static code checking from pytest #1710.

• Add Python 3.10 to CI workflow #1711.

• Add register_new_fields() #1689.

• Use sphinxcontrib-bibtex for references #1731.

• get_latent_representation(): more explicit and better docstring #1732.

• Replace custom attrdict with ml_collections implementation #1696.

Breaking changes

• Add weight support to MULTIVI #1697. Old models can’t be loaded anymore.

Bug Fixes

• Fix links for breast cancer and mouse datasets #1709.

• fix quick start notebooks not showing #1733.

Contributors

• @watiss

• @adamgayoso

• @martinkim0

• @ricomnl

• @marianogabitto

Version 0.17

New in 0.17.4 (2021-09-20)

Changes

• Support for PyTorch Lightning 1.7 #1622.

• Allow flax to use any mutable states used by a model generically with TrainStateWithState #1665, #1700.

• Update publication links in README #1667.

• Docs now include floating window cross references with hoverxref, external links with linkcode, and grid #1678.

Bug Fixes

• Fix get_likelihood_parameters() failure when gene_likelihood != "zinb" in RNASeqMixin #1618.

• Fix exception logic when not using the observed library size in VAE initialization #1660.

• Replace instances of super().__init__() with an argument in super(), causing autoreload extension to throw errors #1671.

• Change cell2location tutorial causing docs build to fail #1674.

• Replace instances of max_epochs as ints for new PyTorch Lightning #1686.

• Catch case when torch.backends.mps is not implemented #1692.

• Fix Poisson sampling in sample() #1702.

Contributors

• @adamgayoso

• @watiss

• @mkarikom

• @tommycelsius

• @ricomnl

New in 0.17.3 (2022-08-26)

Changes

• Pin sphinx_gallery to fix tutorial cards on docs #1657

• Use latest tutorials in release #1657

Contributors

• @watiss

• @adamgayoso

New in 0.17.2 (2022-08-26)

Changes

• Move training argument in JaxVAE constructor to a keyword argument into the call method. This simplifies the JaxModuleWrapper logic and avoids the reinstantiation of JaxVAE during evaluation #1580.

• Add a static method on the BaseModelClass to return the AnnDataManger’s full registry #1617.

• Clarify docstrings for continuous and categorical covariate keys #1637.

• Remove poetry lock, use newer build system #1645.

Bug Fixes

• Fix CellAssign to accept extra categorical covariates #1629.

• Fix an issue where max_epochs is never determined heuristically for totalvi, instead it would always default to 400 #1639.

Breaking Changes

• Fix an issue where max_epochs is never determined heuristically for totalvi, instead it would always default to 400 #1639.

Contributors

• @watiss

• @RK900

• @adamgayoso

• @jjhong922

New in 0.17.1 (2022-07-14)

Make sure notebooks are up to date for real this time :).

Contributors

• @jjhong922

• @adamgayoso

New in 0.17.0 (2022-07-14)

Major Changes

• Experimental MuData support for TOTALVI via the method setup_mudata(). For several of the existing AnnDataField classes, there is now a MuData counterpart with an additional mod_key argument used to indicate the modality where the data lives (e.g. LayerField to MuDataLayerField). These modified classes are simply wrapped versions of the original AnnDataField code via the new scvi.data.fields.MuDataWrapper method #1474.

• Modification of the generative() method’s outputs to return prior and likelihood properties as Distribution objects. Concerned modules are AmortizedLDAPyroModule, AutoZIVAE, MULTIVAE, PEAKVAE, TOTALVAE, SCANVAE, VAE, and VAEC. This allows facilitating the manipulation of these distributions for model training and inference #1356.

• Major changes to Jax support for scvi-tools models to generalize beyond JaxSCVI. Support for Jax remains experimental and is subject to breaking changes:

  • Consistent module interface for Flax modules (Jax-backed) via JaxModuleWrapper, such that they are compatible with the existing BaseModelClass #1506.

  • JaxTrainingPlan now leverages Pytorch Lightning to factor out Jax-specific training loop implementation #1506.

  • Enable basic device management in Jax-backed modules #1585.

Minor changes

• Add on_load() callback which is called on load() prior to loading the module state dict #1542.

• Refactor metrics code and use MetricCollection to update metrics in bulk #1529.

• Add max_kl_weight and min_kl_weight to TrainingPlan #1595.

• Add a warning to UnsupervisedTrainingMixin that is raised if max_kl_weight is not reached during training #1595.

Breaking changes

• Any methods relying on the output of inference and generative from existing scvi-tools models (e.g. SCVI, SCANVI) will need to be modified to accept torch.Distribution objects rather than tensors for each parameter (e.g. px_m, px_v) #1356.

• The signature of compute_and_log_metrics() has changed to support the use of MetricCollection. The typical modification required will look like changing self.compute_and_log_metrics(scvi_loss, self.elbo_train) to self.compute_and_log_metrics(scvi_loss, self.train_metrics, "train"). The same is necessary for validation metrics except with self.val_metrics and the mode "validation" #1529.

Bug Fixes

• Fix issue with get_normalized_expression() with multiple samples and additional continuous covariates. This bug originated from generative() failing to match the dimensions of the continuous covariates with the input when n_samples>1 in inference() in multiple module classes #1548.

• Add support for padding layers in prepare_query_anndata() which is necessary to run load_query_data() for a model setup with a layer instead of X #1575.

Contributors

• @jjhong922

• @adamgayoso

• @PierreBoyeau

• @RK900

• @FlorianBarkmann

Version 0.16

New in 0.16.4 (2022-06-14)

Note: When applying any model using the AdversarialTrainingPlan (e.g. TOTALVI, MULTIVI), you should make sure to use v0.16.4 instead of v0.16.3 or v0.16.2. This release fixes a critical bug in the training plan.

Changes

Breaking changes

Bug Fixes

• Fix critical issue in AdversarialTrainingPlan where kl_weight was overwritten to 0 at each step (#1566). Users should avoid using v0.16.2 and v0.16.3 which both include this bug.

Contributors

• @jjhong922

• @adamgayoso

New in 0.16.3 (2022-06-04)

Changes

• Removes sphinx max version and removes jinja dependency (#1555).

Breaking changes

Bug Fixes

• Upper bounds protobuf due to pytorch lightning incompatibilities (#1556). Note that #1556 has unique changes as PyTorch Lightning >=1.6.4 adds the upper bound in their requirements.

Contributors

• @jjhong922

• @adamgayoso

New in 0.16.2 (2022-05-10)

Changes

Breaking changes

Bug Fixes

• Raise appropriate error when backup_url is not provided and file is missing on load() (#1527).

• Pipe loss_kwargs properly in AdversarialTrainingPlan, and fix incorrectly piped kwargs in TOTALVI and MULTIVI (#1532).

Contributors

• @jjhong922

• @adamgayoso

New in 0.16.1 (2022-04-22)

Changes

• Update scArches Pancreas tutorial, DestVI tutorial (#1520).

Breaking changes

• SemiSupervisedDataLoader and SemiSupervisedDataSplitter no longer take unlabeled_category as an initial argument. Instead, the unlabeled_category is fetched from the labels state registry, assuming that the AnnDataManager object is registered with a LabelsWithUnlabeledObsField (#1515).

Bug Fixes

• Bug fixed in SCANVI where self._labeled_indices was being improperly set (#1515).

• Fix issue where load_query_data would not properly add an obs column with the unlabeled category when the labels_key was not present in the query data.

• Disable extension of categories for labels in load_query_data (#1519).

• Fix an issue with prepare_query_data() to ensure it does nothing when genes are completely matched (#1520).

Contributors

• @jjhong922

• @adamgayoso

New in 0.16.0 (2022-04-12)

This release features a refactor of DestVI (#1457):

1. Bug fix in cell type amortization, which leads to on par performance of cell type amortization V_encoder with free parameter for cell type proportions V.

2. Bug fix in library size in CondSCVI, that lead to downstream dependency between sum over cell type proportions v_ind and library size library in DestVI.

3. neg_log_likelihood_prior is not computed anymore on random subset of single cells but cell type specific subclustering using cluster variance var_vprior, cluster mean mean_vprior and cluster mixture proportion mp_vprior for computation. This leads to more stable results and faster computation time. Setting vamp_prior_p in from_rna_model() to the expected resolution is critical in this algorithm.

4. The new default is to also use dropout dropout during the decoder of CondSCVI and subsequently dropout_decoder in DestVI, we found this to be beneficial after bug fixes listed above.

5. We changed the weighting of the loss on the variances of beta and the prior of eta.

Note

Due to bug fixes listed above this version of DestVI is not backwards compatible. Despite instability in training in the outdated version, we were able to reproduce results generated with this code. We therefore do not strictly encourage to rerun old experiments.

We published a new tutorial. This new tutorial incorporates a new utility package destvi_utils that generates exploratory plots of the results of DestVI. We refer to the manual of this package for further documentation.

Changes

• Docs changes (installation #1498, DestVI user guide #1501 and #1508, dark mode code cells #1499).

• Add backup_url to the load() method of each model class, enabling automatic downloading of model save file (#1505).

Breaking changes

• Support for loading legacy loading is removed from load(). Utility to convert old files to the new file as been added convert_legacy_save() (#1505).

• Breaking changes to DestVI as specified above (#1457).

Bug Fixes

• get_likelihood_parameters() fix for n_samples > 1 and dispersion="gene_cell" #1504.

• Fix backwards compatibility for legacy TOTALVI models #1502.

Contributors

• @cane11

• @jjhong922

• @adamgayoso

• @romain-lopez

Version 0.15

New in 0.15.5 (2022-04-06)

Changes

• Add common types file #1467.

• New default is to not pin memory during training when using a GPU. This is much better for shared GPU environments without any performance regression #1473.

Bug fixes

• Fix LDA user guide bugs #1479.

• Fix unnecessary warnings, double logging #1475.

Contributors

• @jjhong922

• @adamgayoso

New in 0.15.4 (2022-03-28)

Changes

• Add peakVI publication reference #1463.

• Update notebooks with new install functionality for Colab #1466.

• Simplify changing the training plan for pyro #1470.

• Optionally scale ELBO by a scalar in PyroTrainingPlan #1469.

Bug fixes

Contributors

• @jjhong922

• @adamgayoso

• @vitkl

New in 0.15.3 (2022-03-24)

Changes

Bug fixes

• Raise NotImplementedError when categorical_covariate_keys are used with scvi.model.SCANVI.load_query_data(). (#1458).

• Fix behavior when continuous_covariate_keys are used with scvi.model.SCANVI.classify(). (#1458).

• Unlabeled category values are automatically populated when scvi.model.SCANVI.load_query_data() run on adata_target missing labels column. (#1458).

• Fix dataframe rendering in dark mode docs (#1448)

• Fix variance constraint in AmortizedLDA that set an artifical bound on latent topic variance (#1445).

• Fix scvi.model.base.ArchesMixin.prepare_query_data() to work cross device (e.g., model trained on cuda but method used on cpu; see #1451).

Contributors

• @jjhong922

• @adamgayoso

New in 0.15.2 (2022-03-15)

Changes

• Remove setuptools pinned requirement due to new PyTorch 1.11 fix (#1436).

• Switch to myst-parsed markdown for docs (#1435).

• Add prepare_query_data(adata, reference_model) to ArchesMixin to enable query data cleaning prior to reference mapping (#1441).

• Add Human Lung Cell Atlas tutorial (#1442).

Bug fixes

• Errors when arbitrary kwargs are passed into setup_anndata() (#1439).

• Fix scvi.external.SOLO to use train_size=0.9 by default, which enables early stopping to work properly (#1438).

• Fix scArches version warning (#1431).

• Fix backwards compat for SCANVI loading (#1441).

Contributors

• @jjhong922

• @adamgayoso

• @grst

New in 0.15.1 (2022-03-11)

Changes

• Remove labels_key from MULTIVI as it is not used in the model (#1393).

• Use scvi-tools mean/inv_disp parameterization of negative binomial for JaxSCVI likelihood (#1386).

• Use setup for Flax-based modules (#1403).

• Reimplement JaxVAE using inference/generative paradigm with JaxBaseModuleClass (#1406).

• Use multiple particles optionally in JaxSCVI (#1385).

• SOLO no longer warns about count data (#1411).

• Class docs are now one page on docs site (#1415).

• Copied AnnData objects are assigned a new uuid and transfer is attempted (#1416).

Bug fixes

• Fix an issue with using gene lists and proteins lists as well as transform_batch for TOTALVI (#1413).

• Error gracefully when NaNs present in CategoricalJointObsmField (#1417).

Contributors

• @jjhong922

• @adamgayoso

New in 0.15.0 (2022-02-28)

In this release, we have completely refactored the logic behind our data handling strategy (i.e. setup_anndata) to allow for:

1. Readable data handling for existing models.

2. Modular code for easy addition of custom data fields to incorporate into models.

3. Avoidance of unexpected edge cases when more than one model is instantiated in one session.

Important Note: This change will not break pipelines for model users (with the exception of a small change to SCANVI). However, there are several breaking changes for model developers. The data handling tutorial goes over these changes in detail.

This refactor is centered around the new AnnDataManager class which orchestrates any data processing necessary for scvi-tools and stores necessary information, rather than adding additional fields to the AnnData input.

Schematic of data handling strategy with AnnDataManager

We also have an exciting new experimental Jax-based scVI implementation via JaxSCVI. While this implementation has limited functionality, we have found it to be substantially faster than the PyTorch-based implementation. For example, on a 10-core Intel CPU, Jax on only a CPU can be as fast as PyTorch with a GPU (RTX3090). We will be planning further Jax integrations in the next releases.

Changes

• Major refactor to data handling strategy with the introduction of AnnDataManager (#1237).

• Prevent clobbering between models using the same AnnData object with model instance specific AnnDataManager mappings (#1342).

• Add size_factor_key to SCVI, MULTIVI, SCANVI, and TOTALVI (#1334).

• Add references to the scvi-tools journal publication to the README (#1338, #1339).

• Addition of scvi.model.utils.mde() (#1372) for accelerated visualization of scvi-tools embeddings.

• Documentation and user guide fixes (#1364, #1361)

• Fix for SOLO when SCVI was setup with a labels_key (#1354)

• Updates to tutorials (#1369, #1371)

• Furo docs theme (#1290)

• Add scvi.model.JaxSCVI and scvi.module.JaxVAE, drop Numba dependency for checking if data is count data (#1367).

Breaking changes

• The keyword argument run_setup_anndata has been removed from built-in datasets since there is no longer a model-agnostic setup_anndata method (#1237).

• The function scvi.model._metrics.clustering_scores has been removed due to incompatbility with new data handling (#1237).

• SCANVI now takes unlabeled_category as an argument to setup_anndata() rather than on initialization (#1237).

• setup_anndata is now a class method on model classes and requires specific function calls to ensure proper AnnDataManager setup and model save/load. Any model inheriting from BaseModelClass will need to re-implement this method (#1237).

  • To adapt existing custom models to v0.15.0, one can references the guidelines below. For some examples of how this was done for the existing models in the codebase, please reference the following PRs: (#1301, #1302).

  • scvi._CONSTANTS has been changed to scvi.REGISTRY_KEYS.

  • setup_anndata() functions are now class functions and follow a specific structure. Please refer to setup_anndata() for an example.

  • scvi.data.get_from_registry() has been removed. This method can be replaced by scvi.data.AnnDataManager.get_from_registry().

  • The setup dict stored directly on the AnnData object, adata["_scvi"], has been deprecated. Instead, this information now lives in scvi.data.AnnDataManager.registry.

  • The data registry can be accessed at scvi.data.AnnDataManager.data_registry.

  • Summary stats can be accessed at scvi.data.AnnDataManager.summary_stats.

  • Any field-specific information (e.g. adata.obs["categorical_mappings"]) now lives in field-specific state registries. These can be retrieved via the function get_state_registry().

  • register_tensor_from_anndata() has been removed. To register tensors with no relevant AnnDataField subclass, create a new a new subclass of BaseAnnDataField and add it to appropriate model’s setup_anndata() function.

Contributors

• @jjhong922

• @adamgayoso

• @watiss

Version 0.14

New in 0.14.6 (2021-02-05)

Bug fixes, minor improvements of docs, code formatting.

Changes

• Update black formatting to stable release (#1324)

• Refresh readme, move tasks image to docs (#1311).

• Add 0.14.5 release note to index (#1296).

• Add test to ensure extra SCANVI training of a pre-trained SCVI model does not change original model weights (#1284).

• Fix issue in TOTALVI protein background prior initialization to not include protein measurements that are known to be missing (#1282).

• Upper bound setuptools due to PyTorch import bug (#1309).

Contributors

• @adamgayoso

• @watiss

• @jjhong922

New in 0.14.5 (2021-11-22)

Bug fixes, new tutorials.

Changes

• Fix kl_weight floor for Pytorch-based models (#1269).

• Add support for more Pyro guides (#1267).

• Update scArches, harmonization tutorials, add basic R tutorial, tabula muris label transfer tutorial (#1274).

Contributors

• @adamgayoso

• @jjhong922

• @watiss

• @vitkl

New in 0.14.4 (2021-11-16)

Bug fixes, some tutorial improvements.

Changes

• kl_weight handling for Pyro-based models (#1242).

• Allow override of missing protein inference in TOTALVI (#1251). This allows to treat all 0s in a particular batch for one protein as biologically valid.

• Fix load documentation (e.g., load(), load()) (#1253).

• Fix model history on load with Pyro-based models (#1255).

• Model construction tutorial uses new static setup anndata (#1257).

• Add codebase overview figure to docs (#1231).

Contributors

• @adamgayoso

• @jjhong922

• @watiss

New in 0.14.3 (2021-10-19)

Bug fix.

Changes

• Bug fix to BaseModelClass() to retain tensors registered by register_tensor_from_anndata (#1235).

• Expose an instance of our DocstringProcessor to aid in documenting derived implementations of setup_anndata method (#1235).

Contributors

• @adamgayoso

• @jjhong922

• @watiss

New in 0.14.2 (2021-10-18)

Bug fix and new tutorial.

Changes

• Bug fix in RNAStereoscope where loss was computed with mean for a minibatch instead of sum. This ensures reproducibility with the original implementation (#1228).

• New Cell2location contributed tutorial (#1232).

Contributors

• @adamgayoso

• @jjhong922

• @vitkl

• @watiss

New in 0.14.1 (2021-10-11)

Minor hotfixes.

Changes

• Filter out mitochrondrial genes as a preprocessing step in the Amortized LDA tutorial (#1213)

• Remove verbose=True argument from early stopping callback (#1216)

Contributors

• @adamgayoso

• @jjhong922

• @watiss

New in 0.14.0 (2021-10-07)

In this release, we have completely revamped the scvi-tools documentation website by creating a new set of user guides that provide:

1. The math behind each method (in a succinct, online methods-like way)

2. The relationship between the math and the functions associated with each model

3. The relationship between math variables and code variables

Our previous User Guide guide has been renamed to Tutorials and contains all of our existing tutorials (including tutorials for developers).

Another noteworthy addition in this release is the implementation of the (amortized) Latent Dirichlet Allocation (aka LDA) model applied to single-cell gene expression data. We have also prepared a tutorial that demonstrates how to use this model, using a PBMC 10K dataset from 10x Genomics as an example application.

Lastly, in this release we have made a change to reduce user and developer confusion by making the previously global setup_anndata method a static class-specific method instead. This provides more clarity on which parameters are applicable for this call, for each model class. Below is a before/after for the DESTVI and TOTALVI model classes:

setup_anndata before and after

Changes

• Added fixes to support PyTorch Lightning 1.4 (#1103)

• Simplified data handling in R tutorials with sceasy and addressed bugs in package installation (#1122).

• Moved library size distribution computation to model init (#1123)

• Updated Contribution docs to describe how we backport patches (#1129)

• Implemented Latent Dirichlet Allocation as a PyroModule (#1132)

• Made setup_anndata a static method on model classes rather than one global function (#1150)

• Used Pytorch Lightning’s seed_everything method to set seed (#1151)

• Fixed a bug in PyroSampleMixin for posterior sampling (#1158)

• Added CITE-Seq datasets (#1182)

• Added user guides to our documentation (#1127, #1157, #1180, #1193, #1183, #1204)

• Early stopping now prints the reason for stopping when applicable (#1208)

Breaking changes

• setup_anndata is now an abstract method on model classes. Any model inheriting from BaseModelClass will need to implement this method (#1150)

Contributors

• @adamgayoso

• @PierreBoyeau

• @talashuach

• @jjhong922

• @watiss

• @mjayasur

• @vitkl

• @galenxing

Version 0.13

New in 0.13.0 (2021-08-23)

Changes

• Added MULTIVI (#1115, #1118).

• Documentation CSS tweaks (#1116).

Breaking changes

None!

Contributors

• @adamgayoso

• @talashuach

• @jjhong922

Version 0.12

New in 0.12.2 (2021-08-11)

Changes

• Updated OrderedDict typing import to support all Python 3.7 versions (#1114).

Breaking changes

None!

Contributors

• @adamgayoso

• @galenxing

• @jjhong922

New in 0.12.1 (2021-07-29)

Changes

• Update Pytorch Lightning version dependency to >=1.3,<1.4 (#1104).

Breaking changes

None!

Contributors

• @adamgayoso

• @galenxing

New in 0.12.0 (2021-07-15)

This release adds features for tighter integration with Pyro for model development, fixes for SOLO, and other enhancements. Users of SOLO are strongly encouraged to upgrade as previous bugs will affect performance.

Enchancements

• Add scvi.model.base.PyroSampleMixin for easier posterior sampling with Pyro (#1059).

• Add scvi.model.base.PyroSviTrainMixin for automated training of Pyro models (#1059).

• Ability to pass kwargs to Classifier when using SOLO (#1078).

• Ability to get doublet predictions for simulated doublets in SOLO (#1076).

• Add “comparison” column to differential expression results (#1074).

• Clarify CellAssign size factor usage. See class docstring.

Changes

• Update minimum Python version to 3.7.2 (#1082).

• Slight interface changes to PyroTrainingPlan. "elbo_train" and "elbo_test" are now the average over minibatches as ELBO should be on scale of full data and optim_kwargs can be set on initialization of training plan (#1059, #1101).

• Use pandas read pickle function for pbmc dataset metadata loading (#1099).

• Adds n_samples_overall parameter to functions for denoised expression/accesibility/etc. This is used in during differential expression (#1090).

• Ignore configure optimizers warning when training Pyro-based models (#1064).

Bug fixes

• Fix scale of library size for simulated doublets and expression in SOLO when using observed library size to train original SCVI model (#1078, #1085). Currently, library sizes in this case are not appropriately put on the log scale.

• Fix issue where anndata setup with a layer led to errors in SOLO (#1098).

• Fix adata parameter of scvi.external.SOLO.from_scvi_model(), which previously did nothing (#1078).

• Fix default max_epochs of SCANVI when initializing using pre-trained model of SCVI (#1079).

• Fix bug in predict() function of SCANVI, which only occurred for soft predictions (#1100).

Breaking changes

None!

Contributors

• @vitkl

• @adamgayoso

• @galenxing

• @PierreBoyeau

• @Munfred

• @njbernstein

• @mjayasur

Version 0.11

New in 0.11.0 (2021-05-23)

From the user perspective, this release features the new differential expression functionality (to be described in a manuscript). For now, it is accessible from differential_expression(). From the developer perspective, we made changes with respect to scvi.dataloaders.DataSplitter and surrounding the Pyro backend. Finally, we also made changes to adapt our code to PyTorch Lightning version 1.3.

Changes

• Pass n_labels to VAE from SCVI (#1055).

• Require PyTorch lightning > 1.3, add relevant fixes (#1054).

• Add DestVI reference (#1060).

• Add PeakVI links to README (#1046).

• Automatic delta and eps computation in differential expression (#1043).

• Allow doublet ratio parameter to be changed for used in SOLO (#1066).

Bug fixes

• Fix an issue where transform_batch options in TOTALVI was accidentally altering the batch encoding in the encoder, which leads to poor results (#1072). This bug was introduced in version 0.9.0.

Breaking changes

These breaking changes do not affect the user API; though will impact model developers.

• Use PyTorch Lightning data modules for scvi.dataloaders.DataSplitter (#1061). This induces a breaking change in the way the data splitter is used. It is no longer callable and now has a setup method. See TrainRunner and its source code, which is straightforward.

• No longer require training plans to be initialized with n_obs_training argument (#1061). n_obs_training is now a property that can be set before actual training to rescale the loss.

• Log Pyro loss as train_elbo and sum over steps (#1071)

Contributors

• @adamgayoso

• @romain-lopez

• @PierreBoyeau

• @talashuach

• @cataclysmus

• @njbernstein

Version 0.10

New in 0.10.1 (2021-05-04)

Changes

• Includes new optional variance parameterization for the Encoder module (#1037).

• Provides new way to select subpopulations for DE using Pandas queries (#1041).

• Update reference to peakVI (#1046).

• Pin Pytorch Lightning version to <1.3

Contributors

• @adamgayoso

• @PierreBoyeau

• @talashuach

New in 0.10.0 (2021-04-20)

Changes

• PeakVI minor enhancements to differential accessibility and fix scArches support (#1019)

• Add DestVI to the codebase (#1011)

• Versioned tutorial links (#1005)

• Remove old VAEC (#1006)

• Use .numpy() to convert torch tensors to numpy ndarrays (#1016)

• Support backed AnnData (#1017), just load anndata with scvi.data.read_h5ad(path, backed='r+')

• Solo interface enhancements (#1009)

• Updated README (#1028)

• Use Python warnings instead of logger warnings (#1021)

• Change totalVI protein background default to False is fewer than 10 proteins used (#1034)

Bug fixes

• Fix SaveBestState warning (#1024)

• New default SCANVI max epochs if loaded with pretrained SCVI model (#1025), restores old <v0.9 behavior.

• Fix marginal log likelihood computation, which was only being computed on final minibatch of a dataloader. This bug was introduced in the 0.9.X versions (#1033).

• Fix bug where extra categoricals were not properly extended in transfer_anndata_setup (#1030).

Contributors

• @adamgayoso

• @romain-lopez

• @talashuach

• @mjayasur

• @wukathy

• @PierreBoyeau

• @morris-frank

Version 0.9

New in 0.9.1 (2021-03-20)

Changes

• Update Pyro module backend to better enfore usage of model and guide, automate passing of number of training examples to Pyro modules (#990)

• Minimum Pyro version bumped (#988)

• Improve docs clarity (#989)

• Add glossary to developer user guide (#999)

• Add num threads config option to scvi.settings (#1001)

• Add CellAssign tutorial (#1004)

Contributors

• @adamgayoso

• @galenxing

• @mjayasur

• @wukathy

New in 0.9.0 (2021-03-03)

This release features our new software development kit for building new probabilistic models. Our hope is that others will be able to develop new models by importing scvi-tools into their own packages.

Important changes

From the user perspective, there are two package-wide API breaking changes and one SCANVI specific breaking change enumerated below. From the method developer perspective, the entire model backend has been revamped using PyTorch Lightning, and no old code will be compatible with this and future versions. Also, we dropped support for Python 3.6.

Breaking change: The train method

• n_epochs is now max_epochs for consistency with PytorchLightning and to better relect the functionality of the parameter.

• use_cuda is now use_gpu for consistency with PytorchLightning.

• frequency is now check_val_every_n_epoch for consistency with PytorchLightning.

• train_fun_kwargs and kwargs throughout the train() methods in the codebase have been removed and various arguments have been reorganized into plan_kwargs and trainer_kwargs. Generally speaking, plan_kwargs deal with model optimization like kl warmup, while trainer_kwargs deal with the actual training loop like early stopping.

Breaking change: GPU handling

• use_cuda was removed from the init of each model and was not replaced by use_gpu. By default every model is intialized on CPU but can be moved to a device via model.to_device(). If a model is trained with use_gpu=True the model will remain on the GPU after training.

• When loading saved models, scvi-tools will always attempt to load the model on GPU unless otherwise specified.

• We now support specifying which GPU device to use if there are multiple available GPUs.

Breaking change: SCANVI

• SCANVI no longer pretrains an SCVI model by default. This functionality however is preserved via the new from_scvi_model() method.

• n_epochs_unsupervised and n_epochs_semisupervised have been removed from train. It has been replaced with max_epochs for semisupervised training.

• n_samples_per_label is a new argument which will subsample the number of labelled training examples to train on per label each epoch.

New Model Implementations

• PEAKVI implementation (#877, #921)

• SOLO implementation (#923, #933)

• CellAssign implementation (#940)

• RNAStereoscope and SpatialStereoscope implementation (#889, #959)

• Pyro integration via PyroBaseModuleClass (#895 #903, #927, #931)

Enhancements

• SCANVI bug fixes (#879)

• GIMVI moved to external api (#885)

• TOTALVI, SCVI, and SCANVI now support multiple covariates (#886)

• Added callback for saving the best state of a model (#887)

• Option to disable progress bar (#905)

• load() documentation improvements (#913)

• updated tutorials, guides, documentation (#924, #925, #929, #934, #947, #971)

• track is now public (#938)

• SCANVI now logs classficiation loss (#966)

• get_likelihood_parameter() bug (#967)

• model.history are now pandas DataFrames (#949)

Contributors

• @adamgayoso

• @galenxing

• @romain-lopez

• @wukathy

• @giovp

• @njbernstein

• @saketkc

Version 0.8

New in 0.8.1 (2020-12-23)

Enhancements

• freeze_classifier option in load_query_data() for the case when

• weight_decay passed to train() also passes to ClassifierTrainer

New in 0.8.0 (2020-12-17)

Enhancements

Online updates of SCVI, SCANVI, and TOTALVI with the scArches method

It is now possible to iteratively update these models with new samples, without altering the model for the “reference” population. Here we use the scArches method. For usage, please see the tutorial in the user guide.

To enable scArches in our models, we added a few new options. The first is encode_covariates, which is an SCVI option to encode the one-hotted batch covariate. We also allow users to exchange batch norm in the encoder and decoder with layer norm, which can be though of as batch norm but per cell. As the layer norm we use has no parameters, it’s a bit faster than models with batch norm. We don’t find many differences between using batch norm or layer norm in our models, though we have kept defaults the same in this case. To run scArches effectively, batch norm should be exhanged with layer norm.

Empirical initialization of protein background parameters with totalVI

The learned prior parameters for the protein background were randomly initialized. Now, they can be set with the empirical_protein_background_prior option in TOTALVI. This option fits a two-component Gaussian mixture model per cell, separating those proteins that are background for the cell and those that are foreground, and aggregates the learned mean and variance of the smaller component across cells. This computation is done per batch, if the batch_key was registered. We emphasize this is just for the initialization of a learned parameter in the model.

Use observed library size option

Many of our models like SCVI, SCANVI, and TOTALVI learn a latent library size variable. The option use_observed_lib_size may now be passed on model initialization. We have set this as True by default, as we see no regression in performance, and training is a bit faster.

Important changes

• To facilitate these enhancements, saved TOTALVI models from previous versions will not load properly. This is due to an architecture change of the totalVI encoder, related to latent library size handling.

• The default latent distribtuion for TOTALVI is now "normal".

• Autotune was removed from this release. We could not maintain the code given the new API changes and we will soon have alternative ways to tune hyperparameters.

• Protein names during setup_anndata are now stored in adata.uns["_scvi"]["protein_names"], instead of adata.uns["scvi_protein_names"].

Bug fixes

• Fixed an issue where the unlabeled category affected the SCANVI architecture prior distribution. Unfortunately, by fixing this bug, loading previously trained (<v0.8.0) SCANVI models will fail.

Version 0.7

New in 0.7.1 (2020-10-20)

This small update provides access to our new Discourse forum from the documentation.

New in 0.7.0 (2020-10-14)

scvi is now scvi-tools. Version 0.7 introduces many breaking changes. The best way to learn how to use scvi-tools is with our documentation and tutorials.

• New high-level API and data loading, please see tutorials and examples for usage.

• GeneExpressionDataset and associated classes have been removed.

• Built-in datasets now return AnnData objects.

• scvi-tools now relies entirely on the [AnnData] format.

• scvi.models has been moved to scvi.core.module.

• Posterior classes have been reduced to wrappers on DataLoaders

• scvi.inference has been split to scvi.core.data_loaders for AnnDataLoader classes and scvi.core.trainers for trainer classes.

• Usage of classes like Trainer and AnnDataLoader now require the AnnData data object as input.

Pre-Version 0.7

scvi History

The scvi-tools package used to be scvi. This page commemorates all the hard work on the scvi package by our numerous contributors.

Contributors

• @romain

• @adam

• @eddie

• @jeff

• @pierre

• @max

• @yining

• @gabriel

• @achille

• @chenling

• @jules

• @david-kelley

• @william-yang

• @oscar

• @casey-greene

• @jamie-morton

• @valentine-svensson

• @stephen-flemming

• @michael-raevsky

• @james-webber

• @galen

• @francesco-brundu

• @primoz-godec

• @eduardo-beltrame

• @john-reid

• @han-yuan

• @gokcen-eraslan

0.6.7 (2020-8-05)

• downgrade anndata>=0.7 and scanpy>=1.4.6 @galen

• make loompy optional, raise sckmisc import error @adam

• fix PBMCDataset download bug @galen

• fix AnnDatasetFromAnnData _X in adata.obs bug @galen

0.6.6 (2020-7-08)

• add tqdm to within cluster DE genes @adam

• restore tqdm to use simple bar instead of ipywidget @adam

• move to numpydoc for doctstrings @adam

• update issues templates @adam

• Poisson variable gene selection @valentine-svensson

• BrainSmallDataset set defualt save_path_10X @gokcen-eraslan

• train_size must be float between 0.0 and 1.0 @galen

• bump dependency versions @galen

• remove reproducibility notebook @galen

• fix scanVI dataloading @pierre

0.6.5 (2020-5-10)

• updates to totalVI posterior functions and notebooks @adam

• update seurat v3 HVG selection now using skmisc loess @adam

0.6.4 (2020-4-14)

• add back Python 3.6 support @adam

• get_sample_scale() allows gene selection @valentine-svensson

• bug fix to the dataset to anndata method with how cell measurements are stored @adam

• fix requirements @adam

0.6.3 (2020-4-01)

• bug in version for Louvian in setup.py @adam

0.6.2 (2020-4-01)

• update highly variable gene selection to handle sparse matrices @adam

• update DE docstrings @pierre

• improve posterior save load to also handle subclasses @pierre

• Create NB and ZINB distributions with torch and refactor code accordingly @pierre

• typos in autozivae @achille

• bug in csc sparse matrices in anndata data loader @adam

0.6.1 (2020-3-13)

• handles gene and cell attributes with the same name @han-yuan

• fixes anndata overwriting when loading @adam, @pierre

• formatting in basic tutorial @adam

0.6.0 (2020-2-28)

• updates on TotalVI and LDVAE @adam

• fix documentation, compatibility and diverse bugs @adam, @pierre @romain

• fix for external module on scanpy @galen

0.5.0 (2019-10-17)

• do not automatically upper case genes @adam

• AutoZI @oscar

• Made the intro tutorial more user friendly @adam

• Tests for LDVAE notebook @adam

• black codebase @achille @gabriel @adam

• fix compatibility issues with sklearn and numba @romain

• fix Anndata @francesco-brundu

• docstring, totalVI, totalVI notebook and CITE-seq data @adam

• fix type @eduardo-beltrame

• fixing installation guide @jeff

• improved error message for dispersion @stephen-flemming

0.4.1 (2019-08-03)

• docstring @achille

• differential expression @oscar @pierre

0.4.0 (2019-07-25)

• gimVI @achille

• synthetic correlated datasets, fixed bug in marginal log likelihood @oscar

• autotune, dataset enhancements @gabriel

• documentation @jeff

• more consistent posterior API, docstring, validation set @adam

• fix anndataset @michael-raevsky

• linearly decoded VAE @valentine-svensson

• support for scanpy, fixed bugs, dataset enhancements @achille

• fix filtering bug, synthetic correlated datasets, docstring, differential expression @pierre

• better docstring @jamie-morton

• classifier based on library size for doublet detection @david-kelley

0.3.0 (2019-05-03)

• corrected notebook @jules

• added UMAP and updated harmonization code @chenling @romain

• support for batch indices in csvdataset @primoz-godec

• speeding up likelihood computations @william-yang

• better anndata interop @casey-greene

• early stopping based on classifier accuracy @david-kelley

0.2.4 (2018-12-20)

• updated to torch v1 @jules

• added stress tests for harmonization @chenling

• fixed autograd breaking @romain

• make removal of empty cells more efficient @john-reid

• switch to os.path.join @casey-greene

0.2.2 (2018-11-08)

• added baselines and datasets for sMFISH imputation @jules

• added harmonization content @chenling

• fixing bugs on DE @romain

0.2.0 (2018-09-04)

• annotation notebook @eddie

• Memory footprint management @jeff

• updated early stopping @max

• docstring @james-webber

0.1.6 (2018-08-08)

• MMD and adversarial inference wrapper @eddie

• Documentation @jeff

• smFISH data imputation @max

0.1.5 (2018-07-24)

• Dataset additions @eddie

• Documentation @yining

• updated early stopping @max

0.1.3 (2018-06-22)

• Notebook enhancement @yining

• Semi-supervision @eddie

0.1.2 (2018-06-13)

• First release on PyPi

• Skeleton code & dependencies @jeff

• Unit tests @max

• PyTorch implementation of scVI @eddie @max

• Dataset preprocessing @eddie @max @yining

0.1.0 (2017-09-05)

• First scVI TensorFlow version @romain