Release 0.2.3

.gitignore

@@ -21,5 +21,5 @@ __pycache__/
 /.coverage*
 
 # docs
-/docs/generated/
+/docs/**/generated/
 /docs/_build/

CHANGELOG.md

@@ -10,15 +10,19 @@ and this project adheres to [Semantic Versioning][].
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-02-27
+
 ### Added
 - Added within distribution interpretability
 - An efficient implementation of out-of-distribution interpretability is added
 - plotting and getting relevant genes is now possible in DRVI model interface.
 - Setting latent dimension stats is now done in model interface. Previous util functions still work, but will show a deprecation warning.
+- Add tutorial for query to reference mapping
 
 ### Changed
-- The default value for vanished threshold in new the interface of `set_latent_dimension_stats` is 1.0 (previously 0.1).
+- The default value for vanished threshold in new the interface of `set_latent_dimension_stats` is 0.5 (previously 0.1).
 - Interpretability scores for the other direction of a non-vanished dimension is not shown if that direction is meaningless.
+- Main tutorial updated with the new interpretability interface
 
 ## [0.2.2] - 2026-02-11
 

README.md

@@ -84,7 +84,7 @@ If you found a bug, please use the [issue tracker][].
 If DRVI is helpful in your research, please consider citing the following paper:
 
 > Moinfar, A. A. & Theis, F. J.
-> **Unsupervised deep disentangled representation of single-cell omics.**
+> **Disentangling cellular heterogeneity into interpretable biological factors through structured latent representations.**
 > bioRxiv 2024.11.06.622266 (2024) [doi:10.1101/2024.11.06.622266](https://doi.org/10.1101/2024.11.06.622266).
 
 ## Reproducibility

docs/tutorials/index.md

@@ -6,4 +6,5 @@ Our tutorials demonstrate the practical application of DRVI across different use
 :maxdepth: 1
 
 external/general_pipeline
+external/query_to_reference_mapping
 ```

pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "drvi-py"
-version = "0.2.2"
+version = "0.2.3"
 description = "Unsupervised Deep Disentangled Representation of Single-Cell Omics"
 readme = "README.md"
 license = { file = "LICENSE" }

src/drvi/scvi_tools_based/model/base/_interpretability_mixin.py

@@ -213,6 +213,8 @@ def get_reconstruction_effect_of_each_split(
     def set_latent_dimension_stats(
         self,
         embed: AnnData,
+        adata: AnnData | None = None,
+        datamodule: LightningDataModule | None = None,
         vanished_threshold: float = 0.5,
     ) -> AnnData | None:
         """Set the latent dimension statistics of a DRVI embedding into var of an AnnData.
@@ -226,6 +228,11 @@ def set_latent_dimension_stats(
         embed
             AnnData object containing the latent representation (embedding) of the model.
             The latent dimensions should be in the `.X` attribute.
+        adata
+            AnnData object with equivalent structure to initial AnnData.
+            If None, defaults to the AnnData object used to initialize the model.
+        datamodule
+            LightningDataModule object with equivalent structure to initial AnnData. adata will be ignored if
         vanished_threshold
             Threshold for determining if a latent dimension has "vanished" (become inactive).
             Dimensions with max absolute values below this threshold are marked as vanished.
@@ -262,7 +269,7 @@ def set_latent_dimension_stats(
 
         embed.var["reconstruction_effect"] = 0.0
         embed.var.loc[embed.var.sort_values("original_dim_id").index, "reconstruction_effect"] = (
-            self.get_reconstruction_effect_of_each_split()
+            self.get_reconstruction_effect_of_each_split(adata=adata, datamodule=datamodule)
         )
         embed.var["order"] = (-embed.var["reconstruction_effect"]).argsort().argsort()
 

src/drvi/scvi_tools_based/module/_drvi.py

@@ -90,10 +90,11 @@ class DRVIModule(BaseModuleClass):
         Dropout rate to apply to each of the decoder hidden layers.
     gene_likelihood
         Gene likelihood model. Options include:
-        - "normal", "normal_v", "normal_sv" : Normal distributions
         - "poisson" : Poisson distributions
         - "nb" : Negative binomial distributions
         - "pnb": Log negative binomial distributions
+        - "normal" : Normal distributions
+        - "normal_unit_var" : Normal distributions with unit variance
     dispersion
         Dispersion parameter modeling strategy for negative binomial distributions.
         Options:
@@ -153,7 +154,7 @@ def __init__(
         input_dropout_rate: float = 0.0,
         encoder_dropout_rate: float = 0.1,
         decoder_dropout_rate: float = 0.0,
-        gene_likelihood: Literal["normal", "normal_v", "normal_sv", "poisson", "nb", "pnb"] = "pnb",
+        gene_likelihood: Literal["pnb", "nb", "poisson", "normal", "normal_unit_var"] = "pnb",
         dispersion: Literal["gene", "gene-batch", "gene-cell"] = "gene",
         prior: Literal["normal"] = "normal",
         var_activation: Callable | Literal["exp", "pow2", "2sig"] = "exp",

src/drvi/utils/tools/_latent.py

@@ -13,7 +13,7 @@ def set_latent_dimension_stats(
     model: DRVI,
     embed: AnnData,
     inplace: bool = True,
-    vanished_threshold: float = 0.1,
+    vanished_threshold: float = 0.5,
 ) -> AnnData | None:
     """Set the latent dimension statistics of a DRVI embedding into var of an AnnData.