Incorporate use case tutorials (#665)

* Fixed DEG layer retrieval

* Use-case tutorial icons

* Restructure tutorial page

* Subgroup tutorials

docs/conf.py

@@ -195,4 +195,7 @@
  "tutorials/notebooks/differential_gene_expression": "_static/tutorials/dge.png",
  "tutorials/notebooks/metadata_annotation": "_static/tutorials/metadata.png",
  "tutorials/notebooks/ontology_mapping": "_static/tutorials/ontology.png",
+ "tutorials/notebooks/norman_use_case": "_static/tutorials/norman.png",
+ "tutorials/notebooks/mcfarland_use_case": "_static/tutorials/mcfarland.png",
+ "tutorials/notebooks/zhang_use_case": "_static/tutorials/zhang.png",
 }

docs/tutorials/index.md

@@ -11,13 +11,23 @@ Many are also designed to work seamlessly in Google colab.
 For questions about the usage of pertpy use the [scverse discourse](https://discourse.scverse.org/).
 :::
 
-## Quick start
+## Quick start: Tool specific tutorials
 
+### Data transformation
 ```{eval-rst}
 .. nbgallery::
 
  notebooks/guide_rna_assignment
  notebooks/mixscape
+ notebooks/perturbation_space
+ notebooks/metadata_annotation
+ notebooks/ontology_mapping
+```
+
+### Knowledge inference
+```{eval-rst}
+.. nbgallery::
+
  notebooks/augur
  notebooks/sccoda
  notebooks/sccoda_extended
@@ -29,13 +39,23 @@ For questions about the usage of pertpy use the [scverse discourse](https://disc
  notebooks/distance_tests
  notebooks/cinemaot
  notebooks/scgen_perturbation_prediction
- notebooks/perturbation_space
  notebooks/differential_gene_expression
- notebooks/metadata_annotation
- notebooks/ontology_mapping
 ```
 
-### Glossary
+## Use cases
+Our use cases showcase a variety of pertpy tools applied to one dataset.
+They are designed to give you a sense of how to use pertpy in a real-world scenario.
+The use cases featured here are those we present in the pertpy [preprint](https://www.biorxiv.org/content/10.1101/2024.08.04.606516v1).
+
+```{eval-rst}
+.. nbgallery::
+
+ notebooks/norman_use_case
+ notebooks/mcfarland_use_case
+ notebooks/zhang_use_case
+```
+
+## Glossary
 
 ```{eval-rst}
 .. tab-set::

pertpy/metadata/_cell_line.py

@@ -341,8 +341,8 @@ def annotate_bulk_rna(
  # then we can compare these keys and fetch the corresponding metadata.
  if query_id not in adata.obs.columns:
  raise ValueError(
- f"The specified `query_id` {query_id} can't be found in the `adata.obs`.\n"
- "Ensure that you are using one of the available query IDs present in the adata.obs for the annotation.\n"
+ f"The specified `query_id` {query_id} can't be found in the `adata.obs`. \n"
+ "Ensure that you are using one of the available query IDs present in the adata.obs for the annotation."
  "If the desired query ID is not available, you can fetch the cell line metadata "
  "using the `annotate()` function before calling 'annotate_bulk_rna()'. "
  "This ensures that the required query ID is included in your data, e.g. stripped_cell_line_name, DepMap ID."
@@ -359,9 +359,8 @@ def annotate_bulk_rna(
  else:
  reference_id = "DepMap_ID"
  logger.warning(
- "To annotate bulk RNA data from Broad Institue, `DepMap_ID` is used as default reference and query identifier if no `reference_id` is given.\n"
- "Ensure that `DepMap_ID` is available in 'adata.obs'.\n"
- "Alternatively, use `annotate()` to annotate the cell line first "
+ "To annotate bulk RNA data from Broad Institue, `DepMap_ID` is used as default reference and query identifier if no `reference_id` is given."
+ "If `DepMap_ID` isn't available in 'adata.obs', use `annotate()` to annotate the cell line first."
  )
  if self.bulk_rna_broad is None:
  self._download_bulk_rna(cell_line_source="broad")

pertpy/tools/_differential_gene_expression/_base.py

@@ -66,7 +66,7 @@ def data(self):
  if self.layer is None:
  return self.adata.X
  else:
- return self.adata.layer[self.layer]
+ return self.adata.layers[self.layer]
 
  @classmethod
  @abstractmethod