Move tutorials to docs and ref docstrings

cantinilab · Feb 29, 2024 · 8b4b319 · 8b4b319
1 parent 0ece899
commit 8b4b319
Show file tree

Hide file tree

Showing 10 changed files with 125 additions and 7 deletions.
diff --git a/docs/source/base_module.rst b/docs/source/base_module.rst
@@ -0,0 +1,4 @@
+.. automodule:: scconfluence.base_module
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/dataset_utils.rst b/docs/source/dataset_utils.rst
@@ -0,0 +1,4 @@
+.. automodule:: scconfluence.dataset_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/distributions.rst b/docs/source/distributions.rst
@@ -0,0 +1,4 @@
+.. automodule:: scconfluence.distributions
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -7,14 +7,108 @@ Welcome to scConfluence's documentation!
 ========================================
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
+   :caption: Tutorials
 
+   tutorials/*.ipynb
+.. toctree::
+   :hidden:
+   :maxdepth: 3
+   :caption: API
+
+scConfluence is a novel method for the integration of unpaired multiomics data combining
+uncoupled autoencoders and Inverse Optimal Transport to learn low-dimensional cell
+embeddings. These embeddings can then be used for visualization and clustering, useful
+for discovering  subpopulations of cells, and for imputation of features across
+modalities.
+`Read the preprint! <https://www.biorxiv.org/content/10.1101/2024.02.26.582051v1>`_
+
+.. image:: ../../model.png
+   :alt: Explanatory figure
+
+
+Install the package
+-------------------
+
+scConfluence is implemented as a Python package seamlessly integrated within the scverse
+ecosystem, in particular Muon and Scanpy.
+
+via PyPI
+^^^^^^^^
+
+On all operating systems, the easiest way to install scConfluence is via PyPI.
+Installation should typically take a minute and is continuously tested with Python 3.10
+on an Ubuntu virtual machine.
+
+.. code-block:: bash
+   pip install scconfluence
+
+
+via GitHub (development version)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+   git clone [email protected]:cantinilab/scconfluence.git
+   cd scconfluence
+   pip install .
+
+
+Test your development installation (optional)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+   pip install pytest
+   pytest .
+
+Getting started
+---------------
+
+scConfluence takes as an input a MuData object and populates its `obsm` field
+with the latent embeddings. See tutorials for more detailed examples of applications of the method.
+
+You may download a preprocessed 10X Multiome demo dataset `here <https://figshare.com/s/b0840d90e42e37fa165f>`_.
+
+A GPU is not required for the method to run, but is strongly recommended.
+
+.. code-block:: python
+   import scconfluence
+   import mudata as md
+   import scanpy as sc
+   from scipy.spatial.distance import cdist
+
+   # Load data into a Muon object.
+   mdata = md.read_h5mu("my_data.h5mu")
+
+   # Compute the cross-modality distance matrix using connected features
+   mdata.uns["cross_modality1+modality2"] = cdist(mdata["modality1"].obsm["cm_features"],
+                                                  mdata["modality2"].obsm["cm_features"])
+   mdata.uns["cross_keys"] = ["cross_modality1+modality2"]
+
+
+   # Initialize and train the model.
+   autoencoders = {"modality1": scconfluence.model.AutoEncoder(mdata["modality1"],
+                                                                modality="modality1"),
+                   "modality2": scconfluence.model.AutoEncoder(mdata["modality2"],
+                                                                modality="modality2")}
+   model = scconfluence.model.ScConfluence(mdata, unimodal_aes=autoencoders)
+   model.fit(save_path="results")
+   mdata.obsm["latent"] = model.get_latent().loc[mdata.obs_names]
+
+   # Visualize the embedding with UMAP.
+   sc.pp.neighbors(mdata, use_rep="latent")
+   sc.tl.umap(mdata)
+   sc.pl.umap(mdata)
 
+Citation
+--------
 
-Indices and tables
-==================
+.. code-block:: bibtex
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   @article {Samaran2024unpaired,
+     author = {Jules Samaran and Gabriel Peyre and Laura Cantini},
+     title = {scConfluence : single-cell diagonal integration with regularized Inverse Optimal Transport on weakly connected features},
+     year = {2024},
+     doi = {10.1101/2024.02.26.582051},
+     publisher = {Cold Spring Harbor Laboratory},
+     journal = {bioRxiv}
+   }
diff --git a/docs/source/model.rst b/docs/source/model.rst
@@ -0,0 +1,4 @@
+.. automodule:: scconfluence.model
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/nn.rst b/docs/source/nn.rst
@@ -0,0 +1,4 @@
+.. automodule:: scconfluence.nn
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/tutorials/RNA_ATAC_pbmc_tutorial.ipynb → ...ce/tutorials/RNA_ATAC_pbmc_tutorial.ipynb b/tutorials/RNA_ATAC_pbmc_tutorial.ipynb → ...ce/tutorials/RNA_ATAC_pbmc_tutorial.ipynb
diff --git a/tutorials/RNA_FISH_tutorial.ipynb → .../source/tutorials/RNA_FISH_tutorial.ipynb b/tutorials/RNA_FISH_tutorial.ipynb → .../source/tutorials/RNA_FISH_tutorial.ipynb
diff --git a/tutorials/RNA_PROT_tutorial.ipynb → .../source/tutorials/RNA_PROT_tutorial.ipynb b/tutorials/RNA_PROT_tutorial.ipynb → .../source/tutorials/RNA_PROT_tutorial.ipynb
diff --git a/docs/source/unimodal.rst b/docs/source/unimodal.rst
@@ -0,0 +1,4 @@
+.. automodule:: scconfluence.unimodal
+   :members:
+   :undoc-members:
+   :show-inheritance: