Release 0.1.9

.github/workflows/test.yaml

@@ -83,6 +83,8 @@ jobs:
         run: uvx hatch run ${{ matrix.env.name }}:coverage xml
       - name: Upload coverage
         uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
 
   # Check that all tests defined above pass. This makes it easy to set a single "required" test in branch
   # protection instead of having to update it frequently. See https://github.com/re-actors/alls-green#why.

.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
     hooks:
       - id: prettier
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.13
+    rev: v0.12.2
     hooks:
       - id: ruff
         types_or: [python, pyi, jupyter]

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [0.1.9] - 2025-07-01
+
+- Add DRVI-APnoEXP baseline
+- Imorove documnetation for all classes and functions in repository
+
 ## [0.1.8] - 2025-06-22
 
 - Discretize latent dimension values in MI for benchmarking due to [this bug](https://github.com/scikit-learn/scikit-learn/issues/30772).

README.md

@@ -37,7 +37,7 @@ Please refer to the [documentation][link-docs]. In particular, the
 We recommend running DRVI on a recent Linux distribution.
 DRVI is actively tested on the latest LTS version of Ubuntu (currently 24.04 LTS).
 
-[//]: # "TODO: remove ubuntu version later"
+<!-- TODO: remove ubuntu version later -->
 
 For optimal performance, we highly recommend using a GPU with CUDA capabilities.
 While CPU-based systems are supported, GPU-powered systems are strongly recommended for optimal performance.
@@ -49,7 +49,7 @@ Python installed, we recommend installing [Mambaforge](https://github.com/conda-
 
 There are several options to install drvi:
 
-[//]: # "TODO: remove install time!"
+<!-- TODO: remove install time! -->
 
 1. Install the latest release of `drvi-py` from [PyPI][link-pypi], which should take around two minutes:
 
@@ -74,8 +74,8 @@ See the [changelog][changelog].
 
 ## Contact
 
-[//]: # "TODO: make clear where to ask questions:"
-[//]: # "For questions and help requests, you can reach out in the [scverse discourse][scverse-discourse]."
+<!-- TODO: make clear where to ask questions: -->
+<!-- For questions and help requests, you can reach out in the [scverse discourse][scverse-discourse]. -->
 
 If you found a bug, please use the [issue tracker][issue-tracker].
 

docs/api/metrics.md

@@ -4,6 +4,7 @@ We have implemented a user-friendly class for evaluation of disentanglement with
 
 ```{eval-rst}
 .. module:: drvi.utils.metrics
+    :no-index:
 .. currentmodule:: drvi.utils
 
 .. autosummary::
@@ -17,6 +18,7 @@ The following functions represent the similarity functions used in benchmarking:
 
 ```{eval-rst}
 .. module:: drvi.utils.metrics
+    :no-index:
 .. currentmodule:: drvi.utils
 
 .. autosummary::
@@ -32,6 +34,7 @@ The following functions represent the aggregation functions used in benchmarking
 
 ```{eval-rst}
 .. module:: drvi.utils.metrics
+    :no-index:
 .. currentmodule:: drvi.utils
 
 .. autosummary::

docs/api/model.md

@@ -1,13 +1,81 @@
 # Model
 
+The DRVI (Disentangled Representation Variational Inference) model is a model designed for single-cell omics data analysis. It provides disentangled latent representations that separate individual biological processes, enabling better interpretation and downstream analysis.
+
+## Overview
+
+DRVI extends the standard variational autoencoder architecture with specialized decoder architecture. The model learns disentangled representations and separates different sources of variation in the data, such as:
+
+- **Biological factors**: Cell types, developmental processes, perturbation responses, signaling pathways
+- **Technical factors**: Background expressions, technical stress responses
+
+## Core Components
+
+### DRVI model
+
+This is the main model class that can be used to define, train, and evaluate the model on an anndata. `DRVI` passes any extra argument to `DRVIModule` in initialization. Accordingly, we suggest to check its documentation (below) for additional configurations.
+
 ```{eval-rst}
 .. module:: drvi.model
+    :no-index:
 .. currentmodule:: drvi
 
 .. autosummary::
     :nosignatures:
     :toctree: generated
 
     model.DRVI
+```
+
+### DRVIModule
+
+This is the pytorch neural network module and contains DRVI logic.
+
+```{eval-rst}
+.. module:: drvi.model
+.. currentmodule:: drvi
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
     model.DRVIModule
 ```
+
+## Usage Example
+
+```python
+import anndata as ad
+from drvi.model import DRVI
+
+# Load your data
+adata = ad.read_h5ad("your_data.h5ad")
+
+# Setup anndata
+DRVI.setup_anndata(
+    adata,
+    layer="counts",
+    categorical_covariate_keys=["batch"],
+    is_count_data=True,
+)
+
+# Initialize the model
+model = DRVI(
+    adata,
+    categorical_covariates=["batch"],
+    n_latent=64,
+    encoder_dims=[128, 128],
+    decoder_dims=[128, 128],
+)
+
+# Train the model
+model.train(
+    max_epochs=400,
+    early_stopping=False,
+)
+
+# Get disentangled representations
+latent = model.get_latent_representation()
+
+# Please check tutorials for more details and downstream steps
+```

docs/api/plotting.md

@@ -1,7 +1,22 @@
 # Plotting
 
+The DRVI plotting module provides visualization tools for analyzing latent representations and interpretability. These functions help researchers understand the disentangled representations learned by the DRVI model and their biological implications.
+
+## Overview
+
+The plotting module is organized into several categories:
+
+- **Latent Visualization**: Functions for exploring and visualizing latent dimensions
+- **Interpretability Analysis**: Tools for understanding how latent dimensions affect gene expression
+- **Utility Functions**: Additional utility functions.
+
+## Latent Dimension Analysis
+
+The core functions are:
+
 ```{eval-rst}
 .. module:: drvi.utils.plotting
+    :no-index:
 .. currentmodule:: drvi.utils
 
 .. autosummary::
@@ -11,9 +26,142 @@
     plotting.plot_latent_dimension_stats
     plotting.plot_latent_dims_in_umap
     plotting.plot_latent_dims_in_heatmap
-    plotting.make_heatmap_groups
-    plotting.differential_vars_heatmap
+```
+
+### plot_latent_dimension_stats
+
+Analyzes and visualizes statistics of latent dimensions to understand their properties and importance.
+
+- Plots multiple statistics (reconstruction effect, max value, mean, std) across dimension ranking
+- Distinguishes between vanished and non-vanished dimensions
+
+**Use Cases:**
+
+- Identify which latent dimensions are most important for reconstruction
+- Understand the distribution of activation values across dimensions
+- Detect vanished dimensions that contribute little to the model
+
+### plot_latent_dims_in_umap
+
+Visualizes latent dimensions as continuous variables on UMAP embeddings to understand their spatial distribution.
+For each latent dimension, one UMAP plot wil be generated.
+
+**Use Cases:**
+
+- Understand how latent dimensions relate to cell clustering
+- Identify spatial patterns in latent dimension activation
+
+### plot_latent_dims_in_heatmap
+
+Creates heatmap visualizations of latent dimensions across different cell groups or conditions.
+
+- Groups cells by categorical variables (e.g., cell types, conditions)
+- Supports balanced sampling for better visualization
+- Configurable ordering and filtering of dimensions
+
+**Use Cases:**
+
+- Compare latent dimension activation across cell types
+- Identify condition-specific latent patterns
+
+## Interpretability and Differential Effects
+
+The core functions are:
+
+```{eval-rst}
+.. module:: drvi.utils.plotting
+    :no-index:
+.. currentmodule:: drvi.utils
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
     plotting.show_top_differential_vars
-    plotting.show_differential_vars_scatter_plot
     plotting.plot_relevant_genes_on_umap
+    plotting.show_differential_vars_scatter_plot
+    plotting.differential_vars_heatmap
+```
+
+### show_top_differential_vars
+
+Displays bar plots of the top relevant expressed genes for each latent dimension.
+
+- Shows top N genes with highest score per dimension
+- Support for gene symbol mapping
+
+**Use Cases:**
+
+- Identify the most important genes for each biological process
+- Compare gene effects across different latent dimensions
+
+### plot_relevant_genes_on_umap
+
+Visualizes the expression of top relevant genes for each dimension on UMAP embeddings.
+
+- Shows genes most affected by selected latent dimensions
+- Automatic title generation and layout
+
+**Use Cases:**
+
+- Understand expression patterns of key genes
+- Validate biological interpretation of latent dimensions
+
+### show_differential_vars_scatter_plot
+
+Creates scatter plots, allowing users to understand the scoring function under the hood.
+
+- Compares two main effect values (min_possible and max_possible)
+- Colors genes by the combined effect
+
+**Use Cases:**
+
+- Visualize max_possible and min_possible effects
+- Understand the scoring function
+
+### differential_vars_heatmap
+
+Generates comprehensive heatmaps showing how genes respond to latent dimension traversals.
+
+- Shows stepwise effects across all latent dimensions and genes
+- Groups genes by their maximum effect dimension
+
+**Use Cases:**
+
+- Observe the sparsity of the identified modules
+
+## Utility Functions
+
+The core functions are:
+
+```{eval-rst}
+.. module:: drvi.utils.plotting
+    :no-index:
+.. currentmodule:: drvi.utils
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
+    plotting.make_balanced_subsample
+    plotting.cmap
 ```
+
+### make_balanced_subsample
+
+Creates balanced subsamples of AnnData objects with respect to a categorical variable.
+
+- Equal sampling from each category
+- Configurable minimum sample size per category
+
+**Use Cases:**
+
+- Create balanced samples for heatmap visualization
+
+## Custom Colormaps
+
+The module provides specialized colormaps designed for biological data visualization:
+
+- **cmap.saturated_red_blue_cmap**: Enhanced red-blue diverging colormap for differential effects
+- **cmap.saturated_just_sky_cmap**: Sky-blue colormap for positive-only effects
+- **cmap.saturated_sky_cmap**: Sky-blue colormap on the positive side and gray colormap for the negative side