Start documentation

.readthedocs.yml

@@ -0,0 +1,20 @@
+# .readthedocs.yml
+
+version: 2
+
+python:
+   version: 3.8
+   install:
+      - requirements: docs/requirements.txt
+      - method: pip
+        path: .
+   system_packages: true
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+
+
+formats:
+    - epub
+    - pdf

.travis.yml

@@ -0,0 +1,14 @@
+language: python
+dist: xenial
+cache: pip
+python:
+  - "3.6"
+  - "3.7"
+  - "3.8"
+
+install:
+  - pip install -r requirements.txt
+  - python setup.py install
+
+script:
+  - PYTHONPATH=. pytest

docs/Makefile

@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+SOURCEDIR     = .
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/_static/custom.css

@@ -0,0 +1,225 @@
+/* ReadTheDocs theme colors */
+/* Copied from https://github.com/theislab/scvelo */
+
+.wy-nav-top {
+    background-color: #404040
+}
+
+.wy-nav-content {
+    max-width: 950px
+}
+
+.wy-side-nav-search {
+    background-color: transparent
+}
+
+.wy-side-nav-search input[type="text"] {
+    border-width: 0
+}
+
+
+/* Custom classes */
+.small {
+    font-size: 40%
+}
+
+.smaller, .pr {
+    font-size: 70%
+}
+
+
+/* Custom classes with bootstrap buttons */
+
+.tutorial,
+.tutorial:visited,
+.tutorial:hover {
+    /* text-decoration: underline; */
+    font-weight: bold;
+    padding: 2px 5px;
+    white-space: nowrap;
+    max-width: 100%;
+    background: #EF3270;
+    border: solid 1px #EF3270;
+    border-radius: .25rem;
+    font-size: 75%;
+    /* font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace; */
+    color: #404040;
+    overflow-x: auto;
+    box-sizing: border-box;
+}
+
+
+/* Formatting of RTD markup: rubrics and sidebars and admonitions */
+
+/* rubric */
+.rst-content p.rubric {
+    margin-bottom: 6px;
+    font-weight: normal;
+}
+
+.rst-content p.rubric::after {
+    content: ":"
+}
+
+/* sidebar */
+.rst-content .sidebar {
+    /* margin: 0px 0px 0px 12px; */
+    padding-bottom: 0px;
+}
+
+.rst-content .sidebar p {
+    margin-bottom: 12px;
+}
+
+.rst-content .sidebar p,
+.rst-content .sidebar ul,
+.rst-content .sidebar dl {
+    font-size: 13px;
+}
+
+/* less space after bullet lists in admonitions like warnings and notes */
+.rst-content .section .admonition ul {
+    margin-bottom: 6px;
+}
+
+
+/* Code: literals and links */
+
+.rst-content tt.literal,
+.rst-content code.literal {
+    color: #404040;
+}
+
+/* slim font weight for non-link code */
+.rst-content tt:not(.xref),
+.rst-content code:not(.xref),
+.rst-content *:not(a) > tt.xref,
+.rst-content *:not(a) > code.xref,
+.rst-content a > tt.xref,
+.rst-content a > code.xref,
+.rst-content dl:not(.docutils) a > tt.xref,
+
+
+    /* Just one box for annotation code for a less noisy look */
+
+.rst-content .annotation {
+    padding: 2px 5px;
+    background-color: white;
+    border: 1px solid #e1e4e5;
+}
+
+.rst-content .annotation tt,
+.rst-content .annotation code {
+    padding: 0 0;
+    background-color: transparent;
+    border: 0 solid transparent;
+}
+
+
+/* Parameter lists */
+
+.rst-content dl:not(.docutils) dl dt {
+    /* mimick numpydoc’s blockquote style */
+    font-weight: normal;
+    background: none transparent;
+    border-left: none;
+    margin: 0 0 12px;
+    padding: 3px 0 0;
+    font-size: 100%;
+}
+
+.rst-content dl:not(.docutils) dl dt code {
+    font-size: 100%;
+    font-weight: normal;
+    background: none transparent;
+    border: none;
+    padding: 0 2px;
+}
+
+.rst-content dl:not(.docutils) dl dt a.reference > code {
+    text-decoration: underline;
+}
+
+/* Mimick rubric style used for other headings */
+.rst-content dl:not(.docutils) dl > dt {
+    font-weight: bold;
+    background: none transparent;
+    border-left: none;
+    margin: 0 0 12px;
+    padding: 3px 0 0;
+    font-size: 100%;
+}
+
+/* Parameters contain <strong> parts and don’t need bold font */
+.rst-content dl.field-list dl > dt {
+    font-weight: unset
+}
+
+/* Add colon between return tuple element name and type */
+.rst-content dl:not(.docutils) dl > dt .classifier::before {
+    content: ' : '
+}
+
+/* Function headers */
+
+.rst-content dl:not(.docutils) dt {
+    background: #edf0f2;
+    color: #404040;
+    border-top: solid 3px #343131;
+}
+
+.rst-content .section ul li p:last-child {
+    margin-bottom: 0;
+    margin-top: 0;
+}
+
+/* Copy buttons */
+a.copybtn {
+    position: absolute;
+    top: -6.5px;
+    right: 0px;
+    width: 1em;
+    height: 1em;
+    padding: .15em;
+    opacity: .4;
+    transition: opacity 0.5s;
+}
+
+
+/* Remove prompt line numbers */
+.nbinput > :first-child,
+.nboutput > :first-child {
+    min-width: 0 !important;
+}
+
+/* Adjust width of navigation bar on mobile */
+@media screen and (max-width: 768px) {
+    .header-bar {
+        display: none;
+    }
+
+    .wy-nav-content-wrap {
+        margin-left: 0px;
+    }
+
+    .wy-nav-side {
+        width: 300px;
+    }
+
+    .wy-nav-side.shift {
+        max-width: 320px;
+    }
+
+    /* Fix sidebar adjust */
+    .rst-versions {
+        width: 40%;
+        max-width: 320px;
+    }
+}
+
+/* Handle landscape */
+@media screen and (min-width: 377px) {
+    .wy-nav-content-wrap.shift {
+        left: 320px;
+    }
+}

docs/about.rst

@@ -0,0 +1,72 @@
+|PyPI| |travis| |Docs|
+
+scArches (PyTorch) - single-cell architecture surgery
+=========================================================================
+.. raw:: html
+
+ <img src="https://user-images.githubusercontent.com/33202701/89729020-15f7c200-da32-11ea-989b-1b9a3283f642.png" width="700px" align="center">
+
+scArches is a package to integrate newly produced single-cell datasets into integrated reference atlases. Our method can facilitate large collaborative projects with decentralized training and integration of multiple datasets by different groups. scArches is compatible with `scanpy <https://scanpy.readthedocs.io/en/stable/>`_. and hosts efficient implementations of all conditional generative models for single-cell data.
+
+.. note::
+
+  expiMap has been added to scArches code base. It allows interpretable representation learning from scRNA-seq data and also reference mapping. Try it in the tutorial section. 
+
+What can you do with scArches?
+-------------------------------
+- Construct single or multi-modal (CITE-seq) reference atlases and share the trained model and the data (if possible).
+- Download a pre-trained model for your atlas of interest, update it with new datasets and share with your collaborators.
+- Project and integrate query datasets on the top of a reference and use latent representation for downstream tasks, e.g.:diff testing, clustering, classification
+
+What are the different models?
+---------------
+scArches is itself an algorithm to map to project query on the top of reference datasets and applies
+to different models. Here we provide a short explanation and hints on when to use which model. Our models are divided into
+three categories:
+
+Unsupervised
+ This class of algorithms require no `cell type` labels, meaning that you can create a reference and project a query without having access to cell type labels.
+ We implemented two algorithms:
+
+ - **scVI**  (`Lopez et al., 2018 <https://www.nature.com/articles/s41592-018-0229-2>`_): Requires access to raw counts values for data integration and assumes
+ count distribution on the data (NB, ZINB, Poisson).
+
+ - **trVAE** (`Lotfollahi et al.,2019 <https://arxiv.org/abs/1910.01791>`_): It supports both normalized log transformed or count data as input and applies additional MMD loss to have better merging in the latent space.
+
+Supervised and Semi-supervised
+ This class of algorithms assumes the user has access to `cell type` labels when creating the reference data and usually perform better integration compared to. unsupervised methods. However, query data still can be unlabeled. In addition to integration, you can classify your query cells using
+ these methods.
+
+ - **scANVI** (`Xu et al., 2019 <https://www.biorxiv.org/content/10.1101/532895v1>`_): It needs cell type labels for reference data. Your query data can be either unlabeled or labeled. In the case of unlabeled query data, you can use this method to also classify your query cells using reference labels.
+
+ - **scGen** (`Lotfollahi et al., 2019 <https://www.nature.com/articles/s41592-019-0494-8>`_): This method requires cell-type labels for both reference building and query mapping. The query mapping for this method solely relies on the integrated reference and requre no fine-tuning. 
+
+Multi-modal
+ These algorithms can be used to construct multi-modal references atlas and map query data from either modality on the top of the reference.
+
+ - **totalVI** (`Gayoso al., 2019 <https://www.biorxiv.org/content/10.1101/532895v1>`_): This model can be used to build multi-modal  CITE-seq reference atalses.
+   Query datasets can be either from sc-RNAseq or CITE-seq. In addition to integrating query with reference, one can use this model to impute the Proteins
+   in the query datasets.
+
+
+Where to start?
+---------------
+To get a sense of how the model works please go through `this <https://scarches.readthedocs.io/en/latest/trvae_surgery_pipeline.html>`__ tutorial.
+To find out how to construct and share or use pre-trained models example sections. 
+
+Reference
+-------------------------------
+If scArches is useful in your research, please consider citing the `preprint <https://www.biorxiv.org/content/10.1101/2020.07.16.205997v1/>`_.
+
+
+.. |PyPI| image:: https://img.shields.io/pypi/v/scarches.svg
+   :target: https://pypi.org/project/scarches
+
+.. |PyPIDownloads| image:: https://pepy.tech/badge/scarches
+   :target: https://pepy.tech/project/scarches
+
+.. |Docs| image:: https://readthedocs.org/projects/scarches/badge/?version=latest
+   :target: https://scarches.readthedocs.io
+
+.. |travis| image:: https://travis-ci.com/theislab/scarches.svg?branch=master
+    :target: https://travis-ci.com/theislab/scarches

docs/api/dataset.rst

@@ -0,0 +1,7 @@
+Data Processing
+===============
+
+.. automodule:: scarches.dataset
+    :members:
+    :undoc-members:
+    :show-inheritance: