Add identification tutorials

README.md

@@ -31,6 +31,11 @@ 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)
+    - 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)
+        - [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)

docs/tutorials/index.md

@@ -8,5 +8,33 @@ 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.
+```

pyproject.toml

@@ -44,10 +44,37 @@ dependencies = [
   "session-info2",
   "torch>=2.1",
 ]
+# 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]",
+]
+# 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",
+]
+# 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",
+  "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",
+]
 # https://docs.pypi.org/project_metadata/#project-urls
 urls.Documentation = "https://drvi.readthedocs.io/"
 urls.Homepage = "https://github.com/theislab/drvi"