Feature/update installation (#1081)

* Simplify installation instructions

* Improve docs/imports, add developer API

* Fix typo

* Fix datasets' docstring

* Enable `sphinx_tippy`

* Better link to notebooks

* Fix role

* Change title

* Use `~`

* Better phrasing

* Fix docstring in the datasets

* Link to OT

docs/about/cite.rst

@@ -1,5 +1,5 @@
-How to cite us
-==============
+Citing CellRank
+===============
 If you find CellRank useful for your research, please consider citing :cite:`lange:22` as:
 
 .. code-block:: bibtex
@@ -16,10 +16,10 @@ If you find CellRank useful for your research, please consider citing :cite:`lan
         publisher = {Nature Publishing Group}
     }
 
-In addition, if you use :class:`cellrank.estimators.GPCCA` to compute initial, terminal or intermediate states, you are
-using the `pyGPCCA package <https://github.com/msmdev/pyGPCCA>`_ :cite:`reuter:22` under the hood, which implements the
-Generalized Perron Cluster Cluster Analysis (GPCCA) algorithm. Thus, additionally to CellRank, please cite GPCCA
-:cite:`reuter:19` as:
+In addition, if you use the :class:`~cellrank.estimators.GPCCA` estimator to compute initial, terminal or intermediate
+states, you are using the `pyGPCCA package <https://github.com/msmdev/pyGPCCA>`_ :cite:`reuter:22` under the hood,
+which implements the Generalized Perron Cluster Cluster Analysis (GPCCA) algorithm. Thus, additionally to CellRank,
+please cite GPCCA :cite:`reuter:19` as:
 
 .. code-block:: bibtex
 

docs/about/index.rst

@@ -43,7 +43,7 @@ estimated. The general structure of the framework, corresponding to steps **(i)*
 Our main (and recommended!) estimator is based on *Generalized Perron Cluster Cluster Analysis* (GPCCA)
 :cite:`reuter:18,reuter:19`, a method originally developed to study molecular dynamics. CellRank uses a
 robust implementation of GPCCA through the `pyGPCCA`_ package. Please don't forget to cite both CellRank and GPCCA when
-using the :class:`cellrank.estimators.GPCCA` estimator, see :doc:`citing CellRank <cite>`.
+using the :class:`~cellrank.estimators.GPCCA` estimator, see :doc:`citing CellRank <cite>`.
 
 We use fate probabilities to visualize trajectory-specific gene expression trends, infer putative driver genes,
 arrange cells in a :func:`circular embedding <cellrank.pl.circular_projection>` :cite:`velten:17`, visualize

docs/about/version2.rst

@@ -1,36 +1,48 @@
 Moving to CellRank 2
 ====================
-The original CellRank version (v1) :cite:`lange:22` was a framework to analyze cellular dynamics based on RNA velocity :cite:`manno:18,bergen:20` and
-gene expression similarity. Based on a `Markov chain <https://en.wikipedia.org/wiki/Markov_chain>`_ formulation, it combined these two data modalities in a
-high-dimensional space and used the `GPCCA algorithm <https://pygpcca.readthedocs.io/en/latest/index.html>`_ :cite:`reuter:18,reuter:22` to compute initial and terminal states, fate probabilities, and driver
-genes.
+The original CellRank version (v1) :cite:`lange:22` was a framework to analyze cellular dynamics based on RNA velocity
+:cite:`manno:18,bergen:20` and gene expression similarity. Based on a
+`Markov chain <https://en.wikipedia.org/wiki/Markov_chain>`_ formulation, it combined these two data modalities
+in a high-dimensional space and used the :class:`GPCCA algorithm <pygpcca.GPCCA>` :cite:`reuter:18,reuter:22`
+to compute initial and terminal states, fate probabilities, and driver genes.
 
-With version 2, we are generalizing CellRank beyond RNA velocity data and turn it into a general framework for single-cell
-fate mapping based on various data modalities (see :doc:`index`). This required us to make substantial changes to CellRank's API, many of
-which are **backward-compatability breaking**. CellRank 2 can do everything that version 1 could do (and much more);
-however, it does it differently. We outline the most important changes here and refer to the :doc:`../release_notes` for a detailed
-account.
+With version 2, we are generalizing CellRank beyond RNA velocity data and turn it into a general framework for
+single-cell fate mapping based on various data modalities (see :doc:`index`). This required us to make substantial
+changes to CellRank's API, many of which are **backward-compatibility breaking**. CellRank 2 can do everything that
+version 1 could do (and much more); however, it does it differently.
+
+.. important::
+    We outline the most important changes here. For a more detailed account, please refer to the
+    :doc:`../release_notes`.
 
 Important changes in version 2
 ------------------------------
-* Deprecation of high level `.tl` functions, including `cellrank.tl.terminal_states` and `cellrank.tl.lineages`: we realized
-  that this mode of interacting with CellRank is not flexible enough to accomodate various data modalities and analysis paradigms.
-  Thus, we switched to a more modular structure: :mod:`~cellrank.kernels` to compute cell-cell transition matrices,
-  and :mod:`~cellrank.estimators` to compute initial and terminal states, fate probabilities, and more. See :doc:`../notebooks/tutorials/general/100_getting_started`.
-* Introduction of a :meth:`~cellrank.estimators.GPCCA.fit` :meth:`~cellrank.estimators.GPCCA.predict` workflow for estimators:
-  given that we removed the old `.tl` high-level functions, we wanted to make it easier to interact with estimators. Thus,
-  every estimator now has a `.fit` method, which computes macrostates, and a `.predict` method, which classifies some of these as
-  terminal states. The new :meth:`~cellrank.estimators.GPCCA.fit` :meth:`~cellrank.estimators.GPCCA.predict` workflow complements our fully-flexible low-level mode of interacting with estimators.
+* Deprecation of high level ``cellrank.tl`` functions, including ``cellrank.tl.terminal_states`` and
+  ``cellrank.tl.lineages``: we realized that this mode of interacting with CellRank is not flexible enough to
+  accommodate various data modalities and analysis paradigms. Thus, we switched to a more modular structure:
+  :mod:`cellrank.kernels` to compute cell-cell transition matrices, and :mod:`cellrank.estimators` to compute initial
+  and terminal states, fate probabilities, and more. See :doc:`../notebooks/tutorials/general/100_getting_started`.
+* Introduction of a :meth:`~cellrank.estimators.GPCCA.fit`/:meth:`~cellrank.estimators.GPCCA.predict` workflow for
+  estimators: given that we removed the old ``cellrank.tl`` high-level functions, we wanted to make it easier to
+  interact with estimators. Thus, every :mod:`estimator <cellrank.estimators>` now has a ``.fit`` method, which computes
+  macrostates, and a ``.predict`` method, which classifies some of these as terminal states.
+  The new :meth:`~cellrank.estimators.GPCCA.fit`/:meth:`~cellrank.estimators.GPCCA.predict` workflow complements our
+  fully-flexible low-level mode of interacting with estimators.
   See :doc:`../notebooks/tutorials/estimators/600_initial_terminal`.
-* Renaming of `absorption_probabilities` to `fate_probabilities` everwhere, for example in :meth:`~cellrank.estimators.GPCCA.compute_fate_probabilities`:
-  while we still compute `absorption probabilities <https://en.wikipedia.org/wiki/Absorbing_Markov_chain>`_ on the Markov chain under the hood, we realized that the term is somewhat technical and decided
-  to replace it with the more intuitive `fate probabilities`. See :doc:`../notebooks/tutorials/estimators/700_fate_probabilities`.
-* Removal of the `external API`: anyone wishing to contribute to CellRank can do this now directly via :mod:`~cellrank.kernels` and
-  :mod:`~cellrank.estimators`. We welcome any contribution to CellRank, see our :doc:`contribution guide <../contributing>`, and feel free to
-  get in touch via an `issue <https://github.com/theislab/cellrank/issues/new/choose>`_ or `email <mailto:info@cellrank.org>`_.
-* Replacement of the old `WOTKernel` with a new :class:`~cellrank.kernels.RealTimeKernel`: this is CellRank's interface
-  with `moscot <https://moscot-tools.org>`_, enabling us to analyze large-scale time-course studies with additional spatial or lineage readout :cite:`klein:23,lange:23`. In addition,
-  the :class:`~cellrank.kernels.RealTimeKernel` interfaces with `Waddington-OT <https://broadinstitute.github.io/wot/>`_ :cite:`schiebinger:19`.
+* Renaming of ``absorption_probabilities`` to :attr:`~cellrank.estimators.GPCCA.fate_probabilities` everywhere,
+  for example in :meth:`~cellrank.estimators.GPCCA.compute_fate_probabilities`: while we still compute
+  `absorption probabilities <https://en.wikipedia.org/wiki/Absorbing_Markov_chain>`_ on the Markov chain under the hood,
+  we realized that the term is somewhat technical and decided to replace it with the more intuitive
+  "fate probabilities". See :doc:`../notebooks/tutorials/estimators/700_fate_probabilities`.
+* Removal of the ``cellrank.external``: anyone wishing to contribute to CellRank can do this now directly via
+  :mod:`cellrank.kernels` and :mod:`cellrank.estimators`. We welcome any contribution to CellRank,
+  see our :doc:`contribution guide <../contributing>`, and feel free to get in touch via an
+  `issue <https://github.com/theislab/cellrank/issues/new/choose>`_ or `email <mailto:info@cellrank.org>`_.
+* Replacement of the old ``cellrank.external.WOTKernel`` with a new :class:`cellrank.kernels.RealTimeKernel`: this is
+  CellRank's interface with :mod:`moscot`, enabling us to analyze large-scale time-course studies with additional
+  spatial or lineage readout :cite:`klein:23,lange:23`. In addition, the :class:`~cellrank.kernels.RealTimeKernel`
+  interfaces with `Waddington-OT <https://broadinstitute.github.io/wot/>`_ :cite:`schiebinger:19`.
 
-There are many more changes and improvements in CellRank 2. For example, the computation of fate probabilities is 30x faster compared
-to version 1, we fixed many bugs, and improved and extended our documentation and :doc:`tutorials <../notebooks/tutorials/index>`.
+There are many more changes and improvements in CellRank 2. For example, the computation of fate probabilities is
+**30x** faster compared to version 1, we fixed many bugs, and improved and extended our documentation and
+:doc:`tutorials <../notebooks/tutorials/index>`.

docs/api/datasets.rst

@@ -3,7 +3,7 @@
 Datasets
 ========
 CellRank comes with a number of datasets that make it easy for you to get started. Our dataset API enables you to
-automatically download these datasets; see our tutorials for examples.
+automatically download these datasets; see our :doc:`tutorials <../notebooks/tutorials/index>`.
 
 .. currentmodule:: cellrank
 

docs/api/developer.rst

@@ -1,3 +1,69 @@
 Developer API
 =============
-Under construction.
+
+Kernels
+-------
+.. autoclass:: cellrank.kernels.Kernel
+    :members:
+    :inherited-members:
+
+.. autoclass:: cellrank.kernels.UnidirectionalKernel
+    :members:
+    :inherited-members:
+
+.. autoclass:: cellrank.kernels.BidirectionalKernel
+    :members:
+    :inherited-members:
+
+Similarity
+~~~~~~~~~~
+.. autoclass:: cellrank.kernels.utils.SimilarityABC
+    :members:
+    :special-members: __call__
+    :inherited-members:
+
+.. autoclass:: cellrank.kernels.utils.Cosine
+    :members: __call__, hessian
+
+.. autoclass:: cellrank.kernels.utils.Correlation
+    :members: __call__, hessian
+
+.. autoclass:: cellrank.kernels.utils.DotProduct
+    :members: __call__, hessian
+
+Threshold Scheme
+~~~~~~~~~~~~~~~~
+.. autoclass:: cellrank.kernels.utils.ThresholdSchemeABC
+    :members:
+    :special-members: __call__
+    :inherited-members:
+
+.. autoclass:: cellrank.kernels.utils.HardThresholdScheme
+    :members:
+    :special-members: __call__
+
+.. autoclass:: cellrank.kernels.utils.SoftThresholdScheme
+    :members:
+    :special-members: __call__
+
+.. autoclass:: cellrank.kernels.utils.CustomThresholdScheme
+    :members:
+    :special-members: __call__
+
+Estimators
+----------
+.. autoclass:: cellrank.estimators.BaseEstimator
+    :members:
+
+.. autoclass:: cellrank.estimators.TermStatesEstimator
+    :members:
+
+Models
+------
+.. autoclass:: cellrank.models.BaseModel
+    :members:
+
+Lineage
+-------
+.. autoclass:: cellrank.Lineage
+    :members: priming_degree, reduce, plot_pie, from_adata, X, T, view, names, colors

docs/api/estimators.rst

@@ -4,7 +4,7 @@ Estimators
 ==========
 Estimators enable quantitative analysis of Markov transition matrices computed using CellRank
 :doc:`kernels <kernels>`, including automatic detection of initial and terminal states, and computation
-of fate probabilities. Our recommended estimator is :class:`cellrank.estimators.GPCCA`.
+of fate probabilities. Our recommended estimator is the :class:`~cellrank.estimators.GPCCA` estimator.
 
 .. currentmodule:: cellrank
 

docs/api/index.rst

@@ -1,3 +1,5 @@
+.. module:: cellrank
+
 API
 ===
 Import CellRank as::
@@ -11,12 +13,9 @@ CellRank has a modular API, organized around kernels and estimators:
 - :mod:`cellrank.estimators` use the cell-cell transition matrix to derive insights about cellular dynamics,
   for example, they compute initial and terminal states, fate probabilities, and driver genes. Our recommended
   estimator is the :class:`~cellrank.estimators.GPCCA` estimator.
-- In addition, there are :mod:`cellrank.models` for gene trend fitting, :mod:`plotting <cellrank.pl>`
+- In addition, there are :mod:`cellrank.models` for gene trend fitting, :mod:`cellrank.pl`
   for visualization, and :mod:`cellrank.datasets` that help you getting started with CellRank.
 
-If you are new to CellRank, check out our :doc:`about CellRank <../about/index>` page, and take a look at our
-:doc:`tutorials <../notebooks/tutorials/index>`.
-
 .. toctree::
     :caption: API
     :maxdepth: 1

docs/api/kernels.rst

@@ -4,10 +4,11 @@ Kernels
 =======
 Kernels compute cell-cell transition probabilities based on various input data modalities, including molecular
 similarity, RNA velocity :cite:`manno:18`, experimental time points, and many more. They come with methods
-for high-level, qualitative visualization, including vector field- or random walk plots. For quantitative analysis of
-kernel-computed transition matrices, we recommend using :doc:`estimators <estimators>`.
+for high-level, qualitative visualization, including vector field or random walk plots. For quantitative analysis of
+kernel-computed transition matrices, we recommend taking look at the :doc:`estimators <estimators>`.
 
-We don't use the term "kernel" in the way it is used in mathematics, but rather colloquially, to refer to a class that
+We don't use the term "kernel" in the way it is used in
+`mathematics <https://en.wikipedia.org/wiki/Kernel_(algebra)>`_, but rather colloquially, to refer to a class that
 takes in multi-view single-cell data and outputs a cell-cell transition matrix.
 
 .. currentmodule:: cellrank

docs/api/models.rst

@@ -3,7 +3,8 @@
 Models
 ======
 Models fit gene expression trends in pseudotime; they assume some parametric form for the gene trend and estimate
-parameters using an objective function. Note that some models require you to have R and rpy2 installed.
+parameters using an objective function. Note that some models require you to have `R <https://cran.r-project.org/>`_
+and `rpy2 <https://rpy2.github.io>`_ installed.
 
 .. currentmodule:: cellrank
 

docs/conf.py

@@ -39,29 +39,30 @@
     "sphinx_copybutton",
     "sphinx_autodoc_typehints",
     "myst_nb",
-    "sphinx_design",  # for cards
+    "sphinx_tippy",
+    "sphinx_design",
     "typed_returns",
 ]
 intersphinx_mapping = {
-    "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
-    "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
-    "squidpy": ("https://squidpy.readthedocs.io/en/latest/", None),
-    "scvelo": ("https://scvelo.readthedocs.io/en/latest/", None),
     "python": ("https://docs.python.org/3", None),
-    "numpy": ("https://docs.scipy.org/doc/numpy/", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
-    "networkx": ("https://networkx.org/documentation/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "jax": ("https://jax.readthedocs.io/en/latest/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "sklearn": ("https://scikit-learn.org/stable/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "statsmodels": ("https://www.statsmodels.org/stable/", None),
-    "matplotlib": ("https://matplotlib.org/stable/", None),
-    "joblib": ("https://joblib.readthedocs.io/en/latest/", None),
-    "sklearn": ("https://scikit-learn.org/stable/", None),
-    "seaborn": ("https://seaborn.pydata.org/", None),
     "pygam": ("https://pygam.readthedocs.io/en/latest/", None),
-    "jax": ("https://jax.readthedocs.io/en/latest/", None),
     "pygpcca": ("https://pygpcca.readthedocs.io/en/latest/", None),
-    "ot": ("https://pythonot.github.io/", None),
+    "networkx": ("https://networkx.org/documentation/stable/", None),
+    "joblib": ("https://joblib.readthedocs.io/en/latest/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "seaborn": ("https://seaborn.pydata.org/", None),
+    "anndata": ("https://anndata.readthedocs.io/en/latest/", None),
+    "scanpy": ("https://scanpy.readthedocs.io/en/latest/", None),
+    "scvelo": ("https://scvelo.readthedocs.io/en/latest/", None),
+    "squidpy": ("https://squidpy.readthedocs.io/en/latest/", None),
     "moscot": ("https://moscot.readthedocs.io/en/latest/", None),
+    "ot": ("https://pythonot.github.io/", None),
 }
 master_doc = "index"
 pygments_style = "tango"
@@ -90,6 +91,12 @@
 ]
 myst_heading_anchors = 2
 
+# hover
+tippy_anchor_parent_selector = "div.content"
+tippy_enable_mathjax = True
+# no need because of sphinxcontrib-bibtex
+tippy_enable_doitips = False
+
 # autodoc + napoleon
 autosummary_generate = True
 autodoc_member_order = "alphabetical"
@@ -144,7 +151,7 @@
 html_show_sourcelink = False
 html_theme_options = {
     "announcement": "If you're moving from CellRank v1 to v2, "
-    "see our <a href='about/version2.html'>notes on important changes</a>.",
+    "see our <a href='https://cellrank.readthedocs.io/en/latest/about/version2.html'>notes on important changes</a>.",
     "sidebar_hide_name": True,
     "light_logo": "img/light_mode_logo.png",
     "dark_logo": "img/dark_mode_logo.png",

docs/contributing.rst

@@ -1,3 +1,5 @@
-Contributing guide
+Contributing Guide
 ==================
-Under construction.
+Under reconstruction, please feel to reach out via opening a new issue_.
+
+.. _issue: https://github.com/theislab/cellrank/issues/new/choose

docs/index.rst

@@ -1,7 +1,5 @@
 |PyPI| |Downloads| |CI| |Docs| |Codecov| |Discourse|
 
-.. module:: cellrank
-
 CellRank: dynamics from multi-view single-cell data
 ===================================================
 .. image:: _static/img/light_mode_overview.png
@@ -22,24 +20,26 @@ backend, it is powered by the `pyGPCCA package <https://github.com/msmdev/pyGPCC
 free to open an `issue`_ or send us an `email <mailto:info@cellrank.org>`_ if you encounter a bug, need our help or
 just want to make a comment/suggestion.
 
-CellRank's key applications
+.. important::
+    If you're moving from CellRank 1 to CellRank 2, check out :doc:`../about/version2`.
+
+CellRank's Key Applications
 ---------------------------
 - estimate differentiation direction based on a varied number of biological priors, including
   :doc:`pseudotime <notebooks/tutorials/kernels/300_pseudotime>`,
   :doc:`developmental potential <notebooks/tutorials/kernels/400_cytotrace>`,
   :doc:`RNA velocity <notebooks/tutorials/kernels/200_rna_velocity>`,
-  :doc:`experimental time points <notebooks/tutorials/kernels/500_real_time>`, and :class:`more <cellrank.kernels>`.
+  :doc:`experimental time points <notebooks/tutorials/kernels/500_real_time>`, and :mod:`more <cellrank.kernels>`.
 - compute initial, terminal and intermediate :doc:`macrostates <notebooks/tutorials/estimators/600_initial_terminal>`
   :cite:`reuter:19,reuter:22`.
 - infer :doc:`fate probabilities and driver genes <notebooks/tutorials/estimators/700_fate_probabilities>`.
 - visualize and cluster :doc:`gene expression trends <notebooks/tutorials/estimators/800_gene_trends>`.
 - ... and much more, check out our :doc:`API <api/index>`.
 
-Getting started with CellRank
+Getting Started with CellRank
 -----------------------------
 We have :doc:`notebooks/tutorials/index` to help you getting started. To see CellRank in action, explore our
-manuscript :cite:`lange:22` in Nature Methods. If you're moving from CellRank v1 to v2, see our
-:doc:`notes on important changes <about/version2>`.
+manuscript :cite:`lange:22` in Nature Methods.
 
 Contributing
 ------------