Added documentation template

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_static/custom.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 1200px !important;
+}

docs/source/conf.py

@@ -0,0 +1,43 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'Cytopath'
+copyright = '2022, Revant Gupta'
+author = 'Revant Gupta'
+
+release = '0.1.9'
+version = '0.1.9'
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+github_repo = "cytopath"
+github_nb_repo = "cytopath-notebooks"
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'
+
+# Width
+html_static_path = ['_static']
+
+def setup(app):
+    app.add_css_file('custom.css')

docs/source/index.rst

@@ -0,0 +1,24 @@
+Simulation-based inference of differentiation trajectories from RNA velocity fields
+=============================================================================================
+
+.. note::
+
+   This project is under active development.
+
+Cytopath is a method for trajectory inference with single-cell RNA sequencing data. Transcriptional activity information from RNA velocity of single cells is used to define a Markov chain model; simulation of this model yields an ensemble of possible differentiation trajectories that are used to estimate the lineage path.
+
+Cytopath can infer trajectories with or without root/terminal state supervision. No topological constraints (e.g. a tree structure) are placed on the inference as each trajectory is modelled independently. The number of trajectories to be inferred can either be defined or estimated in an unsupervised fashion. Subsequent statistical analysis reveals the topological and molecular characteristics of the differentiation process.
+
+Cytopath can model complex behaviours like cycling and convergence as well as co-occurring combinations of multiple processes. Read more `here <https://doi.org/10.1016/j.crmeth.2022.100359>`_.
+
+Check out the :doc:`notebooks` section for a demonstration of Cytopath on publicly available datasets.
+
+.. image:: https://user-images.githubusercontent.com/25486108/166925895-25fde8d1-c25f-4927-93ad-0331871ef319.png
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   installation
+   usage
+   notebooks

docs/source/installation.rst

@@ -0,0 +1,39 @@
+Installation
+============
+
+Cytopath requires Python 3.9. We recommend using `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_ and setting up a new conda environment.
+
+.. code-block:: console
+
+   conda create -y -n cytopath_env python==3.9
+   conda activate cytopath_env
+
+PyPI
+----
+
+Install cytopath from PyPI using pip
+
+.. code-block:: console
+
+   pip install cytopath
+
+Dependencies
+------------
+
+Direct dependencies of Cytopath will be installed automatically in the step above however, additional dependencies of scvelo will need to be installed manually.
+
+.. code-block:: console
+
+   conda install -c conda-forge python-igraph louvain
+
+Jupyter notebook
+----------------
+
+To run the tutorials install jupyter notebooks.
+
+.. code-block:: console
+
+   conda install notebook
+
+
+

docs/source/notebooks.rst

@@ -0,0 +1,5 @@
+
+Notebooks
+=========
+
+Demonstration of Cytopath on publicly available single cell RNA sequencing datasets:  `cytopath-notebooks <https://github.com/aron0093/cytopath-notebooks>`_

docs/source/usage.rst

@@ -0,0 +1,110 @@
+Usage
+====
+
+The entire process of inferring trajectories with Cytopath is divided into two steps. In the first step, a transition probability matrix is used to simulate possible differentiation paths. In the second step, the simulations are used to estimate trajectories from root states to each terminal region (cluster containing terminal states).  
+
+Pre-processing
+--------------
+
+We assume that the user has already performed `velocity analysis <https://scvelo.readthedocs.io/>`_ at this point and has the processed anndata object in memory. Following is an example of an anndata processed with scvelo.
+
+.. code-block:: console
+
+   AnnData object with n_obs × n_vars = n_cells × n_genes
+       obs: 'root_cells', 'end_points', 'louvain'
+       var: 'velocity_gamma', 'velocity_qreg_ratio', 'velocity_r2', 'velocity_genes'
+       uns: 'neighbors', 'pca', 'umap', 'velocity_graph', 'velocity_graph_neg', 'velocity_params'
+       obsm: 'X_pca', 'X_umap', 'velocity_umap'
+       varm: 'PCs'
+       layers: 'Ms', 'Mu', 'ambiguous', 'matrix', 'spliced', 'unspliced', 'variance_velocity', 'velocity'
+       obsp: 'connectivities', 'distances'
+
+Store the transition probability matrix,
+
+.. code-block:: console
+
+   adata.uns['T_forward'] = scv.utils.get_transition_matrix(adata)
+
+Markov chain sampling
+---------------------
+
+The sampling procedure requires a transition probability matrix (parameter: matrix_key), a clustering that will be used to define terminal regions (parameter: cluster_key) and root/terminal state probabilities (stored under root_cells and end_points obs keys). If a clustering is not specified then Louvain is used by default. 
+
+The auto_adjust parameter will automatically and dynamically select values for technical parameters of the sampling process based on the properties of the dataset. We advise keeping this parameter set to True.
+
+Additionally, set the number of vCPUs (parameter: num_cores) for significantly faster performance. If you wish to return a copy of the anndata object then set copy parameter to True.
+
+.. code-block:: console
+
+   import os
+   import cytopath
+
+   cytopath.sampling(adata, auto_adjust=True, matrix_key = 'T_forward', cluster_key = 'louvain', 
+                     num_cores=os.cpu_count()-1, copy=False)
+
+If the user wishes to manually specify root and terminal cell states, then use the following,
+
+.. code-block:: console
+
+   end_points = np.array(adata.obs.end_points > 0.99)[0] # Numerical index; use any selection criteria
+   root_cells = np.array(adata.obs.root_cells > 0.99)[0] # Numerical index; use any selection criteria
+
+   cytopath.sampling(adata, auto_adjust=True, matrix_key = 'T_forward', cluster_key = 'louvain', 
+                     end_points=end_points, root_cells=root_cells, num_cores=os.cpu_count()-1, copy=False)
+
+Finally, entire clusters can be designated as root or terminal regions as a means of incorporating biological know-how not reflected in velocity-based selection of root/terminal states
+
+.. code-block:: console
+
+   # Example designation of root/terminal clusters
+   end_clusters = ['end_cluster_1', 'end_cluster_2'] 
+   root_clusters = ['root_cluster_1']
+
+   cytopath.sampling(adata, auto_adjust=True, matrix_key = 'T_forward', cluster_key = 'louvain', 
+                     end_clusters=end_clusters, root_clusters=root_clusters, num_cores=os.cpu_count()-1, copy=False)
+
+Trajectory inference
+--------------------
+
+Trajectory inference with default parameters will require the anndata to contain a PCA embedding (uns: 'X_pca') and UMAP (uns: 'X_umap'). The latter can be substituted for any 2D embedding being used to visualise the data (parameter: basis).
+
+.. code-block:: console
+
+   cytopath.trajectories(adata, num_cores=os.cpu_count()-1)
+
+Plotting
+--------
+
+.. code-block:: console
+
+   cytopath.plot_trajectories(adata, basis='umap')
+
+Inference output
+----------------
+
+The trajectories inferred by Cytopath are composed of segments. Cells are aligned to these trajectory segments to determine their relative position along the trajectory (pseudotime) and relative association with multiple trajectories (cell-fate). 
+
+The complete inference output containing all cell-trajectory alignments is stored under the following key,
+
+.. code-block:: console
+
+   adata.uns['trajectories']['cells_along_trajectories_each_step']
+
+Inference output summarised at the single cell level is stored under.
+
+.. code-block:: console
+
+   adata.uns['trajectories']['cells_along_trajectories']
+
+Simulations are stored under,
+
+.. code-block:: console
+
+   adata.uns['samples']
+
+Trajectory coordinates are stored under,
+
+.. code-block:: console
+
+   adata.uns['trajectories']
+

pyproject.toml

@@ -0,0 +1,8 @@
+[build-system]
+requires = [""]
+build-backend = ""
+
+[project]
+name = "cytopath"
+authors = [{name = "Revant Gupta", email = "revant.gupta.93@gmail.com"}]
+dynamic = ["version", "description"]