docs improvements (mainly proteins tuto)

MICS-Lab · Dec 17, 2024 · 1ffda09 · 1ffda09
1 parent ce99ce6
commit 1ffda09
Show file tree

Hide file tree

Showing 8 changed files with 436 additions and 16 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,12 +3,14 @@
 ### Added
 - `load_dataset`: add `custom_filter` and `dry_run` arguments
 - added `min_prototypes_ratio` argument in `fine_tune` to run `init_slide_queue`
+- Added tutorials for proteins data + minor docs improvements
 
 ### Fixed
 - Ensure reset clustering if multiple zero-shot (#9)
 
 ### Changed
 - Removed the docs formatting (better for autocompletion)
+- Reorder parameters in Novae `__init__` (sorted by importance)
 
 ## [0.2.1] - 2024-12-04
 

diff --git a/docs/api/metrics.md b/docs/api/metrics.md
@@ -3,7 +3,3 @@
 ::: novae.monitor.fide_score
 
 ::: novae.monitor.mean_fide_score
-
-::: novae.monitor.svg_score
-
-::: novae.monitor.mean_svg_score
diff --git a/docs/api/utils.md b/docs/api/utils.md
@@ -1,5 +1,7 @@
 ::: novae.utils.spatial_neighbors
 
+::: novae.utils.quantile_scaling
+
 ::: novae.utils.prepare_adatas
 
 ::: novae.utils.load_dataset

diff --git a/docs/faq.md b/docs/faq.md
@@ -20,6 +20,14 @@ from novae import Novae
 model = Novae.from_pretrained("MICS-Lab/novae-human-0") # or any valid model name
 ```
 
+### How to avoid overcorrecting?
+
+By default, Novae corrects the batch-effect to get shared spatial domains across slides.
+The batch information is used only during training (`fit` or `fine_tune`), which should prevent Novae from overcorrecting in `zero_shot` mode.
+
+If not using the `zero_shot` mode, you can provide the `min_prototypes_ratio` parameter to control batch effect correction: either (i) in the `fine_tune` method itself, or (ii) during the model initialization (if retraining a model from scratch).
+
+For instance, if `min_prototypes_ratio=0.5`, Novae expects each slide to contain at least 50% of the prototypes (each prototype can be interpreted as an "elementary spatial domain"). Therefore, the lower `min_prototypes_ratio`, the lower the batch-effect correction. Conversely, if `min_prototypes_ratio=1`, all prototypes are expected to be found in all slides (this doesn't mean the proportions will be the same overall slides, though).
 
 ### How do I save my own model?
 

diff --git a/docs/tutorials/multi_tissue.ipynb b/docs/tutorials/multi_tissue.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Multi-tissue or multi-condition mode\n",
+    "# Multi-tissue/condition mode\n",
     "Coming soon"
    ]
   },

diff --git a/docs/tutorials/proteins.ipynb b/docs/tutorials/proteins.ipynb
diff --git a/docs/tutorials/spot_vs_sc.ipynb → docs/tutorials/resolutions.ipynb b/docs/tutorials/spot_vs_sc.ipynb → docs/tutorials/resolutions.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Spot versus single-cell resolution\n",
+    "# Spot/bin/single-cell resolutions\n",
     "Coming soon"
    ]
   },

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -15,9 +15,9 @@ nav:
   - Tutorials:
     - Main usage: tutorials/main_usage.ipynb
     - Different input modes: tutorials/input_modes.md
-    - Spot vs single-cell resolution: tutorials/spot_vs_sc.ipynb
-    - Multi tissue/condition mode: tutorials/multi_tissue.ipynb
     - Usage on proteins: tutorials/proteins.ipynb
+    - Spot/bin/single-cell resolutions: tutorials/resolutions.ipynb
+    - Multi tissue/condition mode: tutorials/multi_tissue.ipynb
   - API:
     - Novae model: api/Novae.md
     - Utils: api/utils.md