Add tutorial for attention martix analysis

.gitignore

@@ -20,6 +20,7 @@ docs/api/generated
 figures/
 wandb/
 logs/
+data/
 lightning_logs/
 artifacts/
 results/

.readthedocs.yaml

@@ -12,5 +12,6 @@ build:
       - asdf global uv latest
     build:
       html:
+        - export UV_FIND_LINKS=https://data.pyg.org/whl/torch-2.11.0+cpu.html
         - uvx hatch run docs:build
         - mv docs/_build $READTHEDOCS_OUTPUT

README.md

@@ -14,6 +14,7 @@ InterScale is a package for cell interaction analysis in spatial transcriptomics
 
 ## Resources
 - An installation guide, tutorials and API documentation is available in the [documentation](https://interscale.readthedocs.io/).
+- Check out our seperate [reproduciblity repository](https://github.com/theislab/InterScale_reproducibility/) to reproduce the figures for the manuscript
 - Please use [issues](https://github.com/theislab/interscale/issues) to submit bug reports.
 - If you would like to contribute, check out the [contributing guide](https://interscale.readthedocs.io/en/latest/contributing.html).
 - If you find InterScale useful for your research, please consider citing the InterScale preprint.

config_files/legnini_example.yaml

@@ -0,0 +1,28 @@
+model:
+  local_component:
+    name: GCN
+  global_component:
+    name: self-attn-transformer
+    parameters:
+      max_seq_len: 4299
+  decoder:
+    type: linear
+    dual_decoder: True
+  save: /Users/francesca.drummer/Documents/1_Projects/A3-InterScale/results/legnini23/ #Options: local, wandb, None
+optim:
+  lr: 0.001
+  loss: SmoothL1
+  seed: 44
+  accelerator: cpu
+dataset:
+  h5ad_data: /Users/francesca.drummer/Documents/1_Projects/A3-InterScale/data/legnini23.h5ad
+  name: legnini23
+  prediction_task: regression
+  prediction_level: node
+  layer_key: log1p_norm
+  sample_key: ['sample']
+  spatial_neigbors_kwargs:
+    radius: 200
+    library_key: sample
+  batch_size: 3
+  pct_mask_nodes: 0.3

docs/api/model.md

@@ -2,6 +2,8 @@
 
 InterScale is a model descigned for spatial transcpriptomics analysis. It provides, 1) **local and global embeddings** for gene level analysis and 2) **attention matrix** for cell-to-cell analysis.
 
+![InterScale concept](../_static/img/InterScale_model.png)
+
 ## Overview
 
 InterScale is a two component model. The local model learns cell representation of a local, spatial neighborhood and the global compponent learns tissue wide interactions between these neighborhoods.

docs/api/tools.md

@@ -4,6 +4,8 @@ InterScale tools provides utilities for analyzing and interpreting 1) local and
 
 Downstream InterScale's output can be used for gene, cell and tissue level analysis.
 
+![InterScale concept](../_static/img/InterScale_tools.png)
+
 ## Tissue level
 
 ```{eval-rst}

docs/conf.py

@@ -67,6 +67,12 @@
 
 autosummary_generate = True
 autodoc_member_order = "groupwise"
+autodoc_inherit_docstrings = False
+autodoc_type_aliases = {
+    "AnnData": "anndata.AnnData",
+    "pd.DataFrame": "pandas.DataFrame",
+    "np.ndarray": "numpy.ndarray",
+}
 default_role = "literal"
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
@@ -104,7 +110,7 @@
     "pytorch_lightning": ("https://lightning.ai/docs/pytorch/stable/", None),
     "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
     "scvi": ("https://docs.scvi-tools.org/en/stable/", None),
-    "torch": ("https://pytorch.org/docs/stable/", None),
+    # "torch": ("https://pytorch.org/docs/stable/", None),
 }
 
 # List of patterns, relative to source directory, that match files and
@@ -136,26 +142,27 @@
 katex_prerender = shutil.which(katex.NODEJS_BINARY) is not None
 
 nitpick_ignore = [
-    # If building the documentation fails because of a missing link that is outside your control,
-    # you can add an exception to this list.
-    #     ("py:class", "igraph.Graph"),
     ("py:class", "yacs.config.CfgNode"),
+    ("py:class", "optional"),
+    # Type aliases used in docstring text that napoleon converts to cross-references;
+    # these can’t be resolved by intersphinx since the inventory uses fully qualified names.
+    ("py:class", "AnnData"),
+    ("py:class", "pd.DataFrame"),
+    ("py:class", "np.ndarray"),
+    # Undefined cross-doc labels in torch’s own documentation
+    ("ref", "locally-disable-grad-doc"),
+    ("ref", "nn-init-doc"),
 ]
-# Regex-based ignores for references inherited from third-party packages whose
-# Sphinx inventories use module paths that don’t match what their own
-# docstrings reference (e.g. `pytorch_lightning.*` vs the documented
-# `lightning.pytorch.*`, or torch internals not exposed in the public inv).
+# Suppress all cross-reference warnings from third-party inherited docstrings
+# (torch, pytorch_lightning, lightning_fabric) — these are upstream issues.
 nitpick_ignore_regex = [
-    # pytorch_lightning inherited members
     (r"py:.*", r"pytorch_lightning\..*"),
     (r"py:.*", r"LightningModule"),
-    # torch inherited members not in the public inventory
-    (r"py:.*", r"torch\.jit(\..*)?"),
-    (r"py:.*", r"torch\.ScriptModule"),
-    (r"py:.*", r"torch\.nn\.Parameter"),
-    (r"py:.*", r"torch\.utils\.hooks\..*"),
-    (r"py:meth", r"torch\.mean"),
-    # Bare names referenced in inherited torch.nn.Module / Lightning docstrings
+    (r"py:.*", r"torch\..*"),
+    (r"py:.*", r"torch"),
+    (r"py:.*", r"lightning_fabric\..*"),
+    (r"py:.*", r"pandas\.core\..*"),
+    # Bare names from inherited torch.nn.Module / Lightning docstrings
     (r"py:class", r"Module"),
     (r"py:class", r"Dropout"),
     (r"py:class", r"BatchNorm"),
@@ -178,6 +185,4 @@
     (r"py:attr", r"grad_output"),
     (r"py:attr", r"checkpoint_path"),
 ]
-# Suppress docutils-level parse warnings emitted from third-party docstrings
-# (torch / pytorch_lightning) — they’re upstream issues we can’t fix.
-suppress_warnings = ["docutils"]
+suppress_warnings = ["docutils", "intersphinx"]

docs/index.md

@@ -1,6 +1,6 @@
 # InterScale
 
-InterScale is a package for multi-scale analysis of cellular interactions in spatial transcriptomics data. It is built on top of [geome](https://github.com/theislab/geome) (single-cell building on top of [PyG](https://pytorch-geometric.readthedocs.io/en/latest/)), [AnnData](https://anndata.readthedocs.io/en/latest/) and [scvi-toold](https://scvi-tools.org/).
+InterScale is a package for multi-scale analysis of cellular interactions in spatial transcriptomics data. It is built on top of [geome](https://github.com/theislab/geome) (single-cell building on top of [PyG](https://pytorch-geometric.readthedocs.io/en/latest/)), [AnnData](https://anndata.readthedocs.io/en/latest/) and [scvi-tools](https://scvi-tools.org/).
 
 ![InterScale concept](_static/img/InterScale_concept.png)