docs: change order and add quickstart

mkdocs.yml

@@ -18,7 +18,7 @@ theme:
   palette:
     scheme: default
     primary: white
-    accent: amber
+    accent: orange
 extra_css:
   - stylesheets/extra.css
 markdown_extensions:
@@ -28,17 +28,20 @@ markdown_extensions:
 nav:
   - Home:
     - About: index.md
-    - Quickstart: quickstart.md
-  - HNOCA-tools API:
+    - HNOCA-tools: quickstart.md
+    - ArchMap: archmap.md
+  - Vignettes:
+    - Get started: vignettes/get_started.md
+  - API Reference:
+      - map:
+        - AtlasMapper: api/map/AtlasMapper.md
       - snapseed:
         - annotate: api/snapseed/annotate.md
         - annotate_hierarchy: api/snapseed/annotate_hierarchy.md
         - find_markers: api/snapseed/find_markers.md
       - stats:
         - test_de: api/stats/test_de.md
         - test_de_paired: api/stats/test_de_paired.md
-      - map:
-        - AtlasMapper: api/map/AtlasMapper.md
 plugins:
   - search
   - mkdocstrings:
@@ -48,7 +51,7 @@ plugins:
             docstring_style: google
             show_root_heading: true
             parameter_headings: false
-            heading_level: 3
+            heading_level: 2
             show_source: false
             merge_init_into_class: true
             docstring_options:

site/archmap.md

@@ -0,0 +1 @@
+# How to map query data to the HNOCA using ArchMap

site/index.md

@@ -1,17 +1,4 @@
-# Welcome to MkDocs
+# Welcome the Website of the Human Neural Organoid Cell Atlas (HNOCA)
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+The Human Neural Organoid Cell Atlas (HNOCA) is a collection of single-cell RNA-seq data from human brain organoids. The HNOCA is a resource for the scientific community to explore the cellular composition of human brain organoids and to understand the molecular mechanisms underlying brain development and disease.
 
-## Commands
-
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
-
-## Project layout
-
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.

site/quickstart.md

@@ -1,7 +1,6 @@
 # Human Neural Organoid Cell Atlas Toolbox
-#### 🛠️ The Swiss Army Knive of the Single Cell Cartographer
 
-This package provides a set of tools we used to generate and analyze the Human Neural Organoid Cell Atlas. Among other things, it provides functions to:
+The HNOCA-tools provides a set of tools we used to generate and analyze the Human Neural Organoid Cell Atlas. Among other things, it provides functions to:
 
 - Rapidly annotate cell types based on marker genes
 - Map query data to the reference atlas

site/vignettes/get_started.md

@@ -0,0 +1,100 @@
+# Get started with the Human Neural Organoid Cell Atlas Toolbox
+
+The HNOCA-tools provides a set of tools we used to generate and analyze the Human Neural Organoid Cell Atlas. Among other things, it provides functions to:
+
+- Rapidly annotate cell types based on marker genes
+- Map query data to the reference atlas
+- Transfer annotations between datasets
+- Compute 'presence scores' for query data based on the reference atlas
+- Perform differential expression analysis
+
+Here is a quick start guide to the basic functions. More detailed vignettes will be available soon.
+
+### 🖋️ Annotation 
+
+We developed [snapseed](https://github.com/devsystemslab/snapseed) to rapidly annotate the HNOCA. It annotates cells based on manually defined sets of marker genes for individual cell types or cell type hierarchies. It is fast (i.e. GPU-accelerated) and simple to enable annotation of very large datasets.
+
+```python
+import hnoca.snapseed as snap
+from hnoca.snapseed.utils import read_yaml
+
+# Read in the marker genes
+marker_genes = read_yaml("marker_genes.yaml")
+
+# Annotate anndata objects
+snap.annotate(
+    adata,
+    marker_genes,
+    group_name="clusters",
+    layer="lognorm",
+)
+
+# Or for more complex hierarchies
+snap.annotate_hierarchy(
+    adata,
+    marker_genes,
+    group_name="clusters",
+    layer="lognorm",
+)
+```
+
+### 🗺️ Mapping
+
+For reference mapping, we mostly rely on [scPoli](https://docs.scarches.org/en/latest/scpoli_surgery_pipeline.html) and [scANVI](https://docs.scvi-tools.org/en/1.1.1/user_guide/models/scanvi.html). Based on pretrained models, we here provide a simple interface to map query data to the reference atlas.
+
+```python
+import scvi
+import hnoca.map as mapping
+
+# Load the reference model
+ref_model = scvi.model.SCANVI.load(
+    os.path.join("model.pt"),
+    adata=ref_adata,
+)
+
+# Map query data
+mapper = mapping.AtlasMapper(ref_model)
+mapper.map_query(query_adata, retrain="partial", max_epochs=100, batch_size=1024)
+```
+
+Now that the query dataset is mapped, we can perform kNN-based label transfer and presence score calculation.
+
+```python
+# Compute the weighted kNN
+mapper.compute_wknn(k=100)
+
+# Transfer labels
+celltype_transfer = mapper.transfer_labels(label_key="cell_type")
+presence_scores = mapper.get_presence_scores(split_by="batch")
+```
+
+### 📊 Differential expression
+
+We have used ANOVA for DE analysis between the HNOCA and the reference atlas. Here, this is implemented as the `test_de()` function.
+
+```python
+import hnoca.stats as stats
+
+# Perform DE analysis
+de_df = stats.test_de(
+    joint_adata,
+    group_key="origin",
+    return_coef_group="organoid",
+    adjust_method="holm",
+)
+```
+
+In addition to DE testing on the atlas itself, we found it useful to treat the atlas as a universal "control" and test for DE w.r.t query datasets. For this, we first compute the matched expression profile for each cell in the query dataset and then test for DE using an F-test.
+
+```python
+# Compute matched expression profiles based on mapped data
+matched_adata = mapper.get_matched_expression()
+
+# Perform DE analysis
+de_df = stats.test_de_paired(
+    query_adata,
+    matched_adata,
+    adjust_method="holm",
+)
+```
+