From f50bf485781cd00fbfea7b2e9fd0b2d8fc49c829 Mon Sep 17 00:00:00 2001 From: moinfar Date: Thu, 9 Jul 2026 14:26:53 +0200 Subject: [PATCH 1/4] Add identification tutorials --- README.md | 6 ++++++ docs/tutorials/external | 2 +- docs/tutorials/index.md | 30 ++++++++++++++++++++++++++++++ pyproject.toml | 29 ++++++++++++++++++++++++++++- 4 files changed, 65 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 657d254..a3dea34 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,12 @@ Please refer to the [documentation][]. In particular, the - [Tutorials][], specially - [Train DRVI and interpret the latent dimensions](https://drvi.readthedocs.io/latest/tutorials/external/general_pipeline.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/general_pipeline.ipynb) - [Mapping query data into a DRVI reference](https://drvi.readthedocs.io/latest/tutorials/external/query_to_reference_mapping.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/query_to_reference_mapping.ipynb) + - [Finding rare cell types with DRVI](https://drvi.readthedocs.io/latest/tutorials/external/find_rare_cell_types.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/find_rare_cell_types.ipynb) + - Identifying and interpreting factors: + - [Cell types](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_1_cell_types.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_1_cell_types.ipynb) + - [Biological processes](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_2_biological_processes.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_2_biological_processes.ipynb) + - [LLM tools](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_3_llm_tools.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_3_llm_tools.ipynb) + - [Curation](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_4_curation.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_4_curation.ipynb) - [API documentation][], specially - [DRVI Model](https://drvi.readthedocs.io/latest/api/generated/drvi.model.DRVI.html) - [DRVI utility functions (tools)](https://drvi.readthedocs.io/latest/api/tools.html) diff --git a/docs/tutorials/external b/docs/tutorials/external index 25739d2..d4a8ea9 160000 --- a/docs/tutorials/external +++ b/docs/tutorials/external @@ -1 +1 @@ -Subproject commit 25739d29315da4e3f4012f7170bc64e11b458322 +Subproject commit d4a8ea9e2bee137169a0b18c70ab4d877370478f diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 6db3c5c..2bab55a 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -7,4 +7,34 @@ Our tutorials demonstrate the practical application of DRVI across different use external/general_pipeline external/query_to_reference_mapping +external/find_rare_cell_types +external/identification_of_factors_1_cell_types +external/identification_of_factors_2_biological_processes +external/identification_of_factors_3_llm_tools +external/identification_of_factors_4_curation +external/porting_drvi_to_scvi_tools +``` + + +## Installing tutorial dependencies + +The tutorials need a few packages on top of the core DRVI stack. These are +provided as optional-dependency extras so you only install what a given tutorial +needs: + +| Extra | Install | Covers | +| --- | --- | --- | +| `tutorials` | `pip install "drvi-py[tutorials]"` | Common packages for the general tutorials (e.g. general pipeline, rare cell types, query-to-reference mapping). | +| `tutorials-cell-types` | `pip install "drvi-py[tutorials-cell-types]"` | Identification of factors — cell types (adds `celltypist`, `networkx`). | +| `tutorials-biological-processes` | `pip install "drvi-py[tutorials-biological-processes]"` | Identification of factors — biological processes (adds `decoupler`, `gprofiler-official`, `gseapy`, `statsmodels`). | +| `tutorials-llm` | `pip install "drvi-py[tutorials-llm]"` | Identification of factors — LLM tools (adds `anthropic`, `cassia`, `claude-agent-sdk`, `google-genai`, `gs2txt`, `nest-asyncio`, `openai`). Most backends need an API key. | +| `tutorials-all` | `pip install "drvi-py[tutorials-all]"` | Everything for every tutorial, including all identification notebooks and the LLM backends. | + +Extras can be combined, e.g. `pip install "drvi-py[tutorials,tutorials-cell-types]"`. + +```{note} +The `tutorials-llm` backends are optional — you only need the one(s) you actually +use. Most require an API key, except `claude-agent-sdk`, which uses a logged-in +`claude` CLI. The "identification of factors — curation" tutorial reads results +produced by the earlier notebooks, so it needs no extra packages beyond core DRVI. ``` diff --git a/pyproject.toml b/pyproject.toml index 5f555cc..9b538d7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,10 +44,37 @@ dependencies = [ "session-info2", "torch>=2.1", ] +# Tutorial extras +# Notebook: identification_of_factors_1_cell_types +optional-dependencies.tutorials-cell-types = [ + "celltypist>=1.7.1", + "networkx>=3", +] +# Notebook: identification_of_factors_2_biological_processes +optional-dependencies.tutorials-biological-processes = [ + "decoupler>=2.1.6", + "gprofiler-official>=1", + "gseapy>=1.3", + "statsmodels>=0.14", +] +# Notebook: identification_of_factors_3_llm_tools +optional-dependencies.tutorials-llm = [ + "anthropic>=0.116", + "cassia>=1.3.9", + "claude-agent-sdk>=0.2.113", + "google-genai>=2.10", + "gs2txt[enrichment]>=0.1.2", + "nest-asyncio>=1.6", + "openai>=2.44", +] +# Minimal tutorial extra optional-dependencies.tutorials = [ - "gprofiler-official>=0.3.5", "leidenalg", ] +# Everything for every tutorial +optional-dependencies.tutorials-all = [ + "drvi-py[tutorials,tutorials-biological-processes,tutorials-cell-types,tutorials-llm]", +] # https://docs.pypi.org/project_metadata/#project-urls urls.Documentation = "https://drvi.readthedocs.io/" urls.Homepage = "https://github.com/theislab/drvi" From 0c58bbc9ced355f91251819ba5600c289280839f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 9 Jul 2026 12:39:00 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- pyproject.toml | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 9b538d7..4ead3a8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,11 +44,13 @@ dependencies = [ "session-info2", "torch>=2.1", ] -# Tutorial extras -# Notebook: identification_of_factors_1_cell_types -optional-dependencies.tutorials-cell-types = [ - "celltypist>=1.7.1", - "networkx>=3", +# Minimal tutorial extra +optional-dependencies.tutorials = [ + "leidenalg", +] +# Everything for every tutorial +optional-dependencies.tutorials-all = [ + "drvi-py[tutorials,tutorials-biological-processes,tutorials-cell-types,tutorials-llm]", ] # Notebook: identification_of_factors_2_biological_processes optional-dependencies.tutorials-biological-processes = [ @@ -57,6 +59,12 @@ optional-dependencies.tutorials-biological-processes = [ "gseapy>=1.3", "statsmodels>=0.14", ] +# Tutorial extras +# Notebook: identification_of_factors_1_cell_types +optional-dependencies.tutorials-cell-types = [ + "celltypist>=1.7.1", + "networkx>=3", +] # Notebook: identification_of_factors_3_llm_tools optional-dependencies.tutorials-llm = [ "anthropic>=0.116", @@ -67,14 +75,6 @@ optional-dependencies.tutorials-llm = [ "nest-asyncio>=1.6", "openai>=2.44", ] -# Minimal tutorial extra -optional-dependencies.tutorials = [ - "leidenalg", -] -# Everything for every tutorial -optional-dependencies.tutorials-all = [ - "drvi-py[tutorials,tutorials-biological-processes,tutorials-cell-types,tutorials-llm]", -] # https://docs.pypi.org/project_metadata/#project-urls urls.Documentation = "https://drvi.readthedocs.io/" urls.Homepage = "https://github.com/theislab/drvi" From 62be6b02e67a34e85aba46a71c7ea734e4463f10 Mon Sep 17 00:00:00 2001 From: moinfar Date: Thu, 9 Jul 2026 15:13:17 +0200 Subject: [PATCH 3/4] Update README --- README.md | 4 ++-- docs/tutorials/external | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9506fd0..c0c5471 100644 --- a/README.md +++ b/README.md @@ -34,8 +34,8 @@ Please refer to the [documentation][]. In particular, the - Identifying and interpreting factors: - [Cell types](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_1_cell_types.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_1_cell_types.ipynb) - [Biological processes](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_2_biological_processes.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_2_biological_processes.ipynb) - - [LLM tools](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_3_llm_tools.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_3_llm_tools.ipynb) - - [Curation](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_4_curation.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_4_curation.ipynb) + - [Using LLM tools](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_3_llm_tools.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_3_llm_tools.ipynb) + - [Curation of factor annotations](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_4_curation.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_4_curation.ipynb) - [API documentation][], specially - [DRVI Model](https://drvi.readthedocs.io/latest/api/generated/drvi.model.DRVI.html) - [DRVI utility functions (tools)](https://drvi.readthedocs.io/latest/api/tools.html) diff --git a/docs/tutorials/external b/docs/tutorials/external index d4a8ea9..8e633e6 160000 --- a/docs/tutorials/external +++ b/docs/tutorials/external @@ -1 +1 @@ -Subproject commit d4a8ea9e2bee137169a0b18c70ab4d877370478f +Subproject commit 8e633e6b816620540de246a187291fb002a31a83 From 53480818bf3ba8e4d32eaac55fb0538d09dfddf5 Mon Sep 17 00:00:00 2001 From: moinfar Date: Thu, 9 Jul 2026 15:15:29 +0200 Subject: [PATCH 4/4] Minor change --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c0c5471..2189ccd 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Please refer to the [documentation][]. In particular, the - [Train DRVI and interpret the latent dimensions](https://drvi.readthedocs.io/latest/tutorials/external/general_pipeline.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/general_pipeline.ipynb) - [Mapping query data into a DRVI reference](https://drvi.readthedocs.io/latest/tutorials/external/query_to_reference_mapping.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/query_to_reference_mapping.ipynb) - [Finding rare cell types with DRVI](https://drvi.readthedocs.io/latest/tutorials/external/find_rare_cell_types.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/find_rare_cell_types.ipynb) - - Identifying and interpreting factors: + - Identification and annotation of factors: - [Cell types](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_1_cell_types.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_1_cell_types.ipynb) - [Biological processes](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_2_biological_processes.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_2_biological_processes.ipynb) - [Using LLM tools](https://drvi.readthedocs.io/latest/tutorials/external/identification_of_factors_3_llm_tools.html). [![Open In Colab][open-in-colab]](https://colab.research.google.com/github/theislab/DRVI_tutorials/blob/main/identification_of_factors_3_llm_tools.ipynb)