Merge pull request #555 from theislab/update_readme

Update readme

README.rst

@@ -1,37 +1,46 @@
 |PyPI| |Bioconda| |Downloads| |CI| |Notebooks| |Docs| |Codecov|
 
-CellRank - Probabilistic Fate Mapping using RNA Velocity
-========================================================
+CellRank for directed single-cell fate mapping
+==============================================
 
 .. image:: https://raw.githubusercontent.com/theislab/cellrank/master/resources/images/cellrank_fate_map.png
    :width: 600px
    :align: center
 
-**CellRank** is a toolkit to uncover cellular dynamics based on scRNA-seq data with RNA velocity annotation,
-see `La Manno et al. (2018)`_ and `Bergen et al. (2020)`_. In short, CellRank models cellular dynamics as a
-Markov chain, where transition probabilities are computed based on **RNA velocity and transcriptomic similarity**,
-taking into account **uncertainty in the velocities** and the stochastic nature of cell fate decisions.
-The Markov chain is coarse-grained into a set of macrostates which represent initial and terminal states,
-as well as transient intermediate states using Generalized Perron Cluster Cluster Analysis (G-PCCA) [GPCCA18]_,
-implemented in the novel `pyGPCCA`_ package. For each transient cell, i.e. for each cell that's not assigned to a
-terminal state, we then compute its fate probability of it reaching any of the terminal states.
-We show an example of such a fate map in the figure above, which has been computed using the data
-of `pancreatic endocrinogenesis`_.
-
-CellRank scales to **large cell numbers**, is fully compatible with `scanpy`_ and `scvelo`_ and is **easy to use**.
+**CellRank** is a toolkit to uncover cellular dynamics based on Markov state modeling of single-cell data. It contains
+two main modules: `kernels`_ compute cell-cell transition probabilities and `estimators`_ generate hypothesis based on
+these. Our kernels work with a variety of input data including `RNA velocity`_ (see `La Manno et al. (2018)`_ and
+`Bergen et al. (2020)`_), `cellular similarity`_ (both transcriptomic and spatial) and `pseudotime`_, among others.
+Our `VelocityKernel`_ takes into account **uncertainty in the velocities** and allows you to aggregate the short-range
+fate relations given by RNA velocity into longer trends along the phenotypic manifold. Our main estimator is
+*Generalized Perron Cluster Cluster Analysis* (G-PCCA) [GPCCA18]_ which coarse-grains the Markov chain
+into a set of macrostates which represent initial, terminal and intermediate states. For each transient cell,
+we compute its fate probability towards any terminal state. We show an example of such a fate map in the figure above,
+which has been computed using the data of `pancreatic endocrinogenesis`_. CellRank combines `kernels`_ and `estimators`_
+with a powerful `plotting API`_, enabling you to visualize e.g. smooth `gene expression trends`_ along lineages or
+fate-informed `circular embeddings`_, to name just a few.
+
+CellRank scales to large cell numbers, is fully compatible with `scanpy`_ and `scvelo`_ and is easy to use.
 For **installation instructions**, **documentation** and **tutorials**, visit `cellrank.org`_.
 
+Getting started with CellRank
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you're new to CellRank, make sure to go though the `basic tutorial`_ which introduces you to CellRank's high-level
+API. Most biological systems require a bit more control, so be sure to check out the `kernels and estimators tutorial`_
+which allows to unlock the full power of CellRank. If you want to see individual functions in action, visit our
+`gallery`_.
+
 Manuscript
 ^^^^^^^^^^
 Please see our `preprint`_ on **bioRxiv** to learn more.
 
 CellRank's key applications
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-- compute **initial & terminal** as well as **intermediate** macrostates of your biological system
-- infer **fate probabilities** towards the terminal states for each individual cell
-- visualize **gene expression trends** along specific lineages while accounting for the continuous nature of fate
-  determination
-- identify **potential driver genes** for each identified cellular trajectory
+- compute initial & terminal as well as intermediate `macrostates`_ of your biological system
+- infer `fate probabilities`_ towards the terminal states for each individual cell
+- visualize `gene expression trends`_ along specific lineages while accounting for the continuous nature of
+  fate determination
+- identify potential `driver genes`_ for each identified cellular trajectory
 
 Installation
 ^^^^^^^^^^^^
@@ -58,10 +67,18 @@ website relevance).
 
 Support
 ^^^^^^^
-We welcome your feedback! Feel free to open an `issue <https://github.com/theislab/cellrank/issues/new/choose>`__
-or send us an `email <mailto:info@cellrank.org>`_ if you encounter a bug, need our help or just want to make a
+We welcome your feedback! Feel free to open an `issue <https://github.com/theislab/cellrank/issues/new/choose>`_, send us
+an `email <mailto:info@cellrank.org>`_ or `tweet`_ if you encounter a bug, need our help or just want to make a
 comment/suggestion.
 
+Contributing
+^^^^^^^^^^^^
+We actively encourage any contribution! To get started, please check out both the `contribution guide`_ as well as the
+`external API`_. CellRank's modular structure makes it easy to contribute, be it a new method to compute cell-cell
+transition probabilities (`kernels`_), a new way to analyze a transition matrix (`estimators`_) or an addition to the
+`plotting API`_. If you're thinking of contributing a new kernel, we have a `kernel tutorial`_ that guides you trough
+the process.
+
 CellRank was developed in collaboration between the `Theislab`_ and the `Peerlab`_.
 
 .. |PyPI| image:: https://img.shields.io/pypi/v/cellrank.svg
@@ -92,15 +109,41 @@ CellRank was developed in collaboration between the `Theislab`_ and the `Peerlab
     :target: https://codecov.io/gh/theislab/cellrank
     :alt: Coverage
 
-.. _preprint: https://doi.org/10.1101/2020.10.19.345983
-.. _PageRank: https://en.wikipedia.org/wiki/PageRank#cite_note-1
+
 .. _La Manno et al. (2018): https://doi.org/10.1038/s41586-018-0414-6
 .. _Bergen et al. (2020): https://doi.org/10.1038/s41587-020-0591-3
+.. _GPCCA18: https://doi.org/10.1021/acs.jctc.8b00079
 .. _pancreatic endocrinogenesis: https://doi.org/10.1242/dev.173849
-.. _scanpy: https://scanpy.readthedocs.io/en/latest/
-.. _scvelo: https://scvelo.readthedocs.io/
 .. _cellrank.org: https://cellrank.org
+
+.. _kernels: https://cellrank.readthedocs.io/en/stable/classes.html#kernels
+.. _estimators: https://cellrank.readthedocs.io/en/stable/classes.html#estimators
+.. _plotting API: https://cellrank.readthedocs.io/en/stable/api.html#module-cellrank.pl
+.. _external API: https://cellrank.readthedocs.io/en/stable/external_api.html
+.. _contribution guide: https://github.com/theislab/cellrank/blob/master/CONTRIBUTING.rst
+
+.. _RNA velocity: https://cellrank.readthedocs.io/en/stable/classes.html#velocity-kernel
+.. _VelocityKernel: https://cellrank.readthedocs.io/en/stable/classes.html#velocity-kernel
+.. _cellular similarity: https://cellrank.readthedocs.io/en/stable/classes.html#connectivity-kernel
+.. _pseudotime: https://cellrank.readthedocs.io/en/stable/classes.html#pseudotime-kernel
+
+.. _gene expression trends: https://cellrank.readthedocs.io/en/stable/api/cellrank.pl.gene_trends.html#cellrank.pl.gene_trends
+.. _circular embeddings: https://cellrank.readthedocs.io/en/stable/api/cellrank.pl.circular_projection.html
+
+.. _basic tutorial: https://cellrank.readthedocs.io/en/stable/cellrank_basics.html
+.. _kernel tutorial: https://cellrank.readthedocs.io/en/stable/creating_new_kernel.html
+.. _kernels and estimators tutorial: https://cellrank.readthedocs.io/en/stable/kernels_and_estimators.html
+
+.. _scanpy: https://scanpy.readthedocs.io/en/stable/
+.. _scvelo: https://scvelo.readthedocs.io/
+
 .. _Theislab: https://www.helmholtz-muenchen.de/icb/research/groups/theis-lab/overview/index.html
 .. _Peerlab: https://www.mskcc.org/research/ski/labs/dana-pe-er
-.. _pyGPCCA: https://pygpcca.readthedocs.io/en/latest/
-.. _GPCCA18: https://doi.org/10.1021/acs.jctc.8b00079
+.. _`tweet`: https://twitter.com/MariusLange8
+.. _preprint: https://www.biorxiv.org/content/10.1101/2020.10.19.345983v1
+.. _PageRank: https://en.wikipedia.org/wiki/PageRank#cite_note-1
+
+.. _gallery: https://cellrank.readthedocs.io/en/stable/auto_examples/index.html
+.. _macrostates: https://cellrank.readthedocs.io/en/stable/auto_examples/estimators/compute_macrostates.html
+.. _fate probabilities: https://cellrank.readthedocs.io/en/stable/auto_examples/estimators/compute_abs_probs.html
+.. _driver genes: https://cellrank.readthedocs.io/en/stable/auto_examples/estimators/compute_lineage_drivers.html

docs/source/index.rst

@@ -1,42 +1,50 @@
 |PyPI| |Bioconda| |Downloads| |CI| |Notebooks| |Docs| |Codecov|
 
-CellRank - Probabilistic Fate Mapping using RNA Velocity
-========================================================
+CellRank for directed single-cell fate mapping
+==============================================
 
 .. image:: https://raw.githubusercontent.com/theislab/cellrank/master/resources/images/cellrank_fate_map.png
    :width: 600px
    :align: center
 
-**CellRank** is a toolkit to uncover cellular dynamics based on scRNA-seq data with RNA velocity annotation,
-see [Manno18]_ and [Bergen20]_. In short, CellRank models cellular dynamics as a
-Markov chain, where transition probabilities are computed based on **RNA velocity and transcriptomic similarity**,
-taking into account **uncertainty in the velocities** and the stochastic nature of cell fate decisions.
-The Markov chain is coarse-grained into a set of macrostates which represent initial and terminal states,
-as well as transient intermediate states using Generalized Perron Cluster Cluster Analysis (G-PCCA) [GPCCA18]_,
-implemented in the novel `pyGPCCA`_ package. For each transient cell, i.e. for each cell that's not assigned to a
-terminal state, we then compute its fate probability of it reaching any of the terminal states.
-We show an example of such a fate map in the figure above, which has been computed using the data
-of [Panc19]_.
-
-CellRank scales to large cell numbers, is fully compatible with `scanpy`_ and `scvelo <https://scvelo.readthedocs.io/>`_
-and is easy to use. To get started, see our `tutorial`_.
-
-Manuscript
-^^^^^^^^^^
-Please see our `preprint`_ on **bioRxiv** to learn more.
+**CellRank** is a toolkit to uncover cellular dynamics based on Markov state modeling of single-cell data. It contains
+two main modules: `kernels`_ compute cell-cell transition probabilities and `estimators`_ generate hypothesis based on
+these. Our kernels work with a variety of input data including `RNA velocity`_ (see [Manno18]_ and [Bergen20]_),
+`cellular similarity`_ (both transcriptomic and spatial) and `pseudotime`_, among others. Our `VelocityKernel`_
+takes into account **uncertainty in the velocities** and allows you to aggregate the short-range fate relations
+given by RNA velocity into longer trends along the phenotypic manifold. Our main estimator is
+*Generalized Perron Cluster Cluster Analysis* (G-PCCA) [GPCCA18]_ which coarse-grains the Markov chain
+into a set of macrostates which represent initial, terminal and intermediate states. For each transient cell,
+we compute its fate probability towards any terminal state. We show an example of such a fate map in the figure above,
+which has been computed using the data of [Panc19]_. CellRank combines `kernels`_ and `estimators`_ with a powerful
+`plotting API`_, enabling you to visualize e.g. smooth `gene expression trends`_ along lineages or fate-informed
+`circular embeddings`_, to name just a few.
+
+CellRank scales to large cell numbers, is fully compatible with `scanpy`_ and `scvelo`_ and is easy to use.
+
+Getting started with CellRank
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you're new to CellRank, make sure to go though the `basic tutorial`_ which introduces you to CellRank's high-level
+API. Most biological systems require a bit more control, so be sure to check out the `kernels and estimators tutorial`_
+which allows to unlock the full power of CellRank. If you want to see individual functions in action, visit our
+`gallery`_.
 
 Latest additions
 ^^^^^^^^^^^^^^^^
 
 .. include:: latest_additions.rst
 
+Manuscript
+^^^^^^^^^^
+Please see our `preprint`_ on **bioRxiv** to learn more.
+
 CellRank's key applications
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-- compute initial & terminal as well as intermediate macrostates of your biological system
-- infer fate probabilities towards the terminal states for each individual cell
-- visualize gene expression trends along specific lineages while accounting for the continuous nature of
+- compute initial & terminal as well as intermediate `macrostates`_ of your biological system
+- infer `fate probabilities`_ towards the terminal states for each individual cell
+- visualize `gene expression trends`_ along specific lineages while accounting for the continuous nature of
   fate determination
-- identify potential driver genes for each identified cellular trajectory
+- identify potential `driver genes`_ for each identified cellular trajectory
 
 Why is it called "CellRank"?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -47,10 +55,18 @@ website relevance).
 
 Support
 ^^^^^^^
-We welcome your feedback! Feel free to open an `issue <https://github.com/theislab/cellrank/issues/new/choose>`_
-or send us an `email <mailto:info@cellrank.org>`_ if you encounter a bug, need our help or just want to make a
+We welcome your feedback! Feel free to open an `issue <https://github.com/theislab/cellrank/issues/new/choose>`_, send us
+an `email <mailto:info@cellrank.org>`_ or `tweet`_ if you encounter a bug, need our help or just want to make a
 comment/suggestion.
 
+Contributing
+^^^^^^^^^^^^
+We actively encourage any contribution! To get started, please check out both the `contribution guide`_ as well as the
+`external API`_. CellRank's modular structure makes it easy to contribute, be it a new method to compute cell-cell
+transition probabilities (`kernels`_), a new way to analyze a transition matrix (`estimators`_) or an addition to the
+`plotting API`_. If you're thinking of contributing a new kernel, we have a `kernel tutorial`_ that guides you trough
+the process.
+
 CellRank was developed in collaboration between the `Theislab`_ and the `Peerlab`_.
 
 .. toctree::
@@ -110,10 +126,35 @@ CellRank was developed in collaboration between the `Theislab`_ and the `Peerlab
     :target: https://codecov.io/gh/theislab/cellrank
     :alt: Coverage
 
-.. _preprint: https://www.biorxiv.org/content/10.1101/2020.10.19.345983v1
-.. _PageRank: https://en.wikipedia.org/wiki/PageRank#cite_note-1
-.. _tutorial: https://cellrank.readthedocs.io/en/stable/cellrank_basics.html
+
+.. _kernels: https://cellrank.readthedocs.io/en/stable/classes.html#kernels
+.. _estimators: https://cellrank.readthedocs.io/en/stable/classes.html#estimators
+.. _plotting API: https://cellrank.readthedocs.io/en/stable/api.html#module-cellrank.pl
+.. _external API: https://cellrank.readthedocs.io/en/stable/external_api.html
+.. _contribution guide: https://github.com/theislab/cellrank/blob/master/CONTRIBUTING.rst
+
+.. _RNA velocity: https://cellrank.readthedocs.io/en/stable/classes.html#velocity-kernel
+.. _VelocityKernel: https://cellrank.readthedocs.io/en/stable/classes.html#velocity-kernel
+.. _cellular similarity: https://cellrank.readthedocs.io/en/stable/classes.html#connectivity-kernel
+.. _pseudotime: https://cellrank.readthedocs.io/en/stable/classes.html#pseudotime-kernel
+
+.. _gene expression trends: https://cellrank.readthedocs.io/en/stable/api/cellrank.pl.gene_trends.html#cellrank.pl.gene_trends
+.. _circular embeddings: https://cellrank.readthedocs.io/en/stable/api/cellrank.pl.circular_projection.html
+
+.. _basic tutorial: https://cellrank.readthedocs.io/en/stable/cellrank_basics.html
+.. _kernel tutorial: https://cellrank.readthedocs.io/en/stable/creating_new_kernel.html
+.. _kernels and estimators tutorial: https://cellrank.readthedocs.io/en/stable/kernels_and_estimators.html
+
 .. _scanpy: https://scanpy.readthedocs.io/en/stable/
+.. _scvelo: https://scvelo.readthedocs.io/
+
 .. _Theislab: https://www.helmholtz-muenchen.de/icb/research/groups/theis-lab/overview/index.html
 .. _Peerlab: https://www.mskcc.org/research/ski/labs/dana-pe-er
-.. _pyGPCCA: https://pygpcca.readthedocs.io/en/latest/
+.. _`tweet`: https://twitter.com/MariusLange8
+.. _preprint: https://www.biorxiv.org/content/10.1101/2020.10.19.345983v1
+.. _PageRank: https://en.wikipedia.org/wiki/PageRank#cite_note-1
+
+.. _gallery: https://cellrank.readthedocs.io/en/stable/auto_examples/index.html
+.. _macrostates: https://cellrank.readthedocs.io/en/stable/auto_examples/estimators/compute_macrostates.html
+.. _fate probabilities: https://cellrank.readthedocs.io/en/stable/auto_examples/estimators/compute_abs_probs.html
+.. _driver genes: https://cellrank.readthedocs.io/en/stable/auto_examples/estimators/compute_lineage_drivers.html