diff --git a/docs/about/cite.rst b/docs/about/cite.rst index 77c3701e3..18ed3e410 100644 --- a/docs/about/cite.rst +++ b/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 `_ :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 `_ :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 diff --git a/docs/about/index.rst b/docs/about/index.rst index 97c158e36..8b83cf43a 100644 --- a/docs/about/index.rst +++ b/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 `. +using the :class:`~cellrank.estimators.GPCCA` estimator, see :doc:`citing CellRank `. We use fate probabilities to visualize trajectory-specific gene expression trends, infer putative driver genes, arrange cells in a :func:`circular embedding ` :cite:`velten:17`, visualize diff --git a/docs/about/version2.rst b/docs/about/version2.rst index e34be2945..8b36d370b 100644 --- a/docs/about/version2.rst +++ b/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 `_ formulation, it combined these two data modalities in a -high-dimensional space and used the `GPCCA algorithm `_ :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 `_ formulation, it combined these two data modalities +in a high-dimensional space and used the :class:`GPCCA algorithm ` :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 ` 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 `_ 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 `_ or `email `_. -* Replacement of the old `WOTKernel` with a new :class:`~cellrank.kernels.RealTimeKernel`: this is CellRank's interface - with `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 `_ :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 `_ 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 `_ or `email `_. +* 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 `_ :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>`. diff --git a/docs/api/datasets.rst b/docs/api/datasets.rst index bedb28645..a135cbf39 100644 --- a/docs/api/datasets.rst +++ b/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 diff --git a/docs/api/developer.rst b/docs/api/developer.rst index bb4e9dd9a..8bcec629d 100644 --- a/docs/api/developer.rst +++ b/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 diff --git a/docs/api/estimators.rst b/docs/api/estimators.rst index b18609a9a..df2afcb8f 100644 --- a/docs/api/estimators.rst +++ b/docs/api/estimators.rst @@ -4,7 +4,7 @@ Estimators ========== Estimators enable quantitative analysis of Markov transition matrices computed using CellRank :doc:`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 diff --git a/docs/api/index.rst b/docs/api/index.rst index 948ab853b..3083cf3a2 100644 --- a/docs/api/index.rst +++ b/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 ` +- 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 diff --git a/docs/api/kernels.rst b/docs/api/kernels.rst index 6e7c219ac..fb7e47692 100644 --- a/docs/api/kernels.rst +++ b/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 `. +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 `. -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 `_, 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 diff --git a/docs/api/models.rst b/docs/api/models.rst index a30755254..c0da1e6fb 100644 --- a/docs/api/models.rst +++ b/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 `_ +and `rpy2 `_ installed. .. currentmodule:: cellrank diff --git a/docs/conf.py b/docs/conf.py index 62ddd0b0e..623da00bf 100644 --- a/docs/conf.py +++ b/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 notes on important changes.", + "see our notes on important changes.", "sidebar_hide_name": True, "light_logo": "img/light_mode_logo.png", "dark_logo": "img/dark_mode_logo.png", diff --git a/docs/contributing.rst b/docs/contributing.rst index 629007dfb..30ad40a84 100644 --- a/docs/contributing.rst +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index 523461fc7..7afbcceb3 100644 --- a/docs/index.rst +++ b/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 `_ 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 `, :doc:`developmental potential `, :doc:`RNA velocity `, - :doc:`experimental time points `, and :class:`more `. + :doc:`experimental time points `, and :mod:`more `. - compute initial, terminal and intermediate :doc:`macrostates ` :cite:`reuter:19,reuter:22`. - infer :doc:`fate probabilities and driver genes `. - visualize and cluster :doc:`gene expression trends `. - ... and much more, check out our :doc:`API `. -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 `. +manuscript :cite:`lange:22` in Nature Methods. Contributing ------------ diff --git a/docs/installation.rst b/docs/installation.rst index 3f2298f54..69f76d0af 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,19 +1,17 @@ -.. TODO(michalk8): update the instructions - Installation ============ -CellRank requires Python version >= 3.8 to run. We recommend using Miniconda_ to manage the environments. +:mod:`cellrank` requires Python version >= 3.8 to run. We recommend using Mamba_ to manage Python environments. +If you encounter any problems, feel to open an issue_. -Anaconda --------- -CellRank can be installed via:: +Conda +----- +CellRank can also be installed via `conda-forge `_ as:: - conda install -c conda-forge -c bioconda cellrank - # or with extra libraries, useful for large datasets - conda install -c conda-forge -c bioconda cellrank-krylov + conda install -c conda-forge cellrank -If an error occurs during ``conda install -c conda-forge -c bioconda cellrank-krylov``, please consult the -Dependencies_ section below. +This installation method is preferred because it also contains PETSc_ and SLEPc_, +libraries for large scale linear algebra problems CellRank relies on (e.g., when computing the metastable states or +absorption probabilities). PyPI ---- @@ -25,56 +23,9 @@ Development Version ------------------- To stay up-to-date with the newest version, run:: - pip install git+https://github.com/theislab/cellrank@main - -Dependencies ------------- -Some of the inference tasks that CellRank performs can be broken down to linear algebra problems. -For example, we solve linear systems to compute fate probabilities and we compute partial Schur decompositions and -find metastable states. For these computations to be scalable, we rely on highly optimized libraries which make use -of sparsity structure, parallel implementations and efficient message passing implemented via -`PETSc`_ and `SLEPc`_. -CellRank works without these as well, however, if you would like to apply it to large (>15k cells) datasets, -we recommend you install them. - -Below, we give details for installing both `PETSc`_ and `SLEPc`_, in case you've had any issues when installing them -through `PyPI`_ or `Anaconda`_:: - - # note: conda alternatives are denoted by alt. - - # update - sudo apt-get update - sudo apt-get upgrade - - # install a message passing interface and mpi4py - sudo apt-get install libopenmpi-dev # alt.: conda install -c conda-forge openmpi - pip install --user mpi4py # alt.: conda install -c anaconda mpi4py - - # install petsc and and petsc4py - pip install --user petsc # alt.: conda install -c conda-forge petsc - pip install --user petsc4py # alt.: conda install -c conda-forge petsc4py - - # install slepsc and slepsc4py - pip install --user slepc # alt.: conda install -c conda-forge slepc - pip install --user slepc4py # alt.: conda install -c conda-forge slepc4py - -During installation of *petsc*, *petsc4py*, *slepc*, and *slepc4py* the following -error might appear several times:: - - ERROR: Failed building wheel for [insert package name here] - -but this doesn't matter if the installer finally tells you:: - - Successfully installed [insert package name here] - -On Mac OS, install `MPICH`_ as a message passing interface and then proceed as above, using either pip or the -installation instructions given on the `PETSc`_ and `SLEPc`_ websites. The `SLEPc`_ homepage even offers a video -tutorial explaining the installation. - -If after reading this, you still can't proceed with the installation, feel free to open a `GitHub issue`_. + pip install git+https://github.com/theislab/cellrank.git@main -.. _`Miniconda`: https://conda.pydata.org/miniconda.html -.. _`GitHub issue`: https://github.com/theislab/cellrank/issues/new +.. _`Mamba`: https://mamba.readthedocs.io/en/latest/installation.html +.. _`issue`: https://github.com/theislab/cellrank/issues/new .. _`SLEPc`: https://slepc.upv.es/ -.. _`PETSc`: https://www.mcs.anl.gov/petsc/ -.. _`MPICH`: https://www.mpich.org/ +.. _`PETSc`: https://petsc.org/ diff --git a/pyproject.toml b/pyproject.toml index b84e6d00c..92900936c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -80,9 +80,10 @@ test = [ "jax", ] docs = [ + "sphinx>=5.1.1", "furo>=2022.09.29", "myst-nb>=0.17.1", - "sphinx>=5.1.1", + "sphinx-tippy>=0.4.1", "sphinx-autodoc-typehints>=1.10.3", "sphinx_copybutton>=0.5.0", "sphinx_design>=0.3.0", diff --git a/src/cellrank/_utils/_docs.py b/src/cellrank/_utils/_docs.py index c3f37b155..95cb49d7b 100644 --- a/src/cellrank/_utils/_docs.py +++ b/src/cellrank/_utils/_docs.py @@ -111,8 +111,8 @@ _write_to_adata = """\ Updates the :attr:`adata` with the following fields: - - :attr:`obsp['{{key}}'] ` - the transition matrix. - - :attr:`uns['{{key}}_params'] ` - parameters used for the calculation.""" +- :attr:`obsp['{{key}}'] ` - the transition matrix. +- :attr:`uns['{{key}}_params'] ` - parameters used for the calculation.""" _en_cutoff_p_thresh = """\ en_cutoff If ``cluster_key`` is given, this parameter determines when an approximate recurrent class will @@ -127,7 +127,7 @@ basis Basis to use when ``mode = 'embedding'``. If :obj:`None`, use ``'umap'``.""" _velocity_scheme = """\ -scheme +similarity Similarity measure between cells as described in :cite:`li:20`. Valid options are: - ``{s.CORRELATION!r}`` - :class:`~cellrank.kernels.utils.Correlation`. @@ -159,10 +159,10 @@ _absorption_utils = """\ solver Solver to use for the linear problem. Options are ``'direct'``, ``'gmres'``, ``'lgmres'``, ``'bicgstab'`` or - ``'gcrotmk'`` when ``use_petsc = False`` or one of :class:`petsc4py.PETSc.KPS.Type` otherwise. + ``'gcrotmk'`` when ``use_petsc = False``. - Information on the :mod:`scipy` iterative solvers can be found in :func:`scipy.sparse.linalg` or for - :mod:`petsc4py` solver `here `__. + Information on the :mod:`scipy` iterative solvers can be found in :mod:`scipy.sparse.linalg` or for + the ``petsc`` solvers `here `__. use_petsc Whether to use solvers from :mod:`petsc4py` or :mod:`scipy`. Recommended for large problems. If no installation is found, defaults to :func:`~scipy.sparse.linalg.gmres`. diff --git a/src/cellrank/_utils/_lineage.py b/src/cellrank/_utils/_lineage.py index f20f8900f..104467339 100644 --- a/src/cellrank/_utils/_lineage.py +++ b/src/cellrank/_utils/_lineage.py @@ -680,11 +680,11 @@ def reduce( - ``{nw.SCALE!r}`` - divide by the sum. - ``{nw.SOFTMAX!r}``- use a softmax. - Only use when ``mode = {m.DIST!r}``. + Only used when ``mode = {m.DIST!r}``. softmax_scale Scaling factor in the softmax, used for normalizing the weights to sum to :math:`1`. return_weights - If `True`, a :class:`pandas.DataFrame` of the weights used for the projection is also returned. + If `True`, a :class:`~pandas.DataFrame` of the weights used for the projection is also returned. If ``mode = {m.SCALE!r}``, the weights will be `None`. Returns diff --git a/src/cellrank/datasets.py b/src/cellrank/datasets.py index 8cc1536e0..3076c12ed 100644 --- a/src/cellrank/datasets.py +++ b/src/cellrank/datasets.py @@ -74,8 +74,6 @@ def _load_dataset_from_url( return adata -@d.get_sections(base="dataset", sections=["Parameters"]) -@d.dedent def pancreas( path: Union[str, pathlib.Path] = "datasets/endocrinogenesis_day15.5.h5ad", kind: Literal["raw", "preprocessed", "preprocessed-kernel"] = "raw", @@ -119,7 +117,6 @@ def pancreas( raise ValueError(f"Unknown dataset kind `{kind!r}`.") -@d.dedent def lung( path: Union[str, pathlib.Path] = "datasets/lung_regeneration.h5ad", **kwargs: Any, @@ -136,7 +133,10 @@ def lung( Parameters ---------- - %(dataset.parameters)s + path + Path where to save the dataset. + kwargs + Keyword arguments for :func:`~scanpy.read`. Returns ------- @@ -148,8 +148,8 @@ def lung( @inject_docs(s=ReprogrammingSubset) @d.dedent def reprogramming_morris( - subset: Literal["full", "48k", "85k"] = ReprogrammingSubset.FULL, path: Union[str, pathlib.Path] = "datasets/reprogramming_morris.h5ad", + subset: Literal["full", "48k", "85k"] = ReprogrammingSubset.FULL, **kwargs: Any, ) -> AnnData: # pragma: no cover """Reprogramming of mouse embryonic fibroblasts to induced endoderm progenitors from :cite:`morris:18`. @@ -166,14 +166,16 @@ def reprogramming_morris( Parameters ---------- + path + Path where to save the dataset. subset Whether to return the full object or just a subset. Can be one of: - ``{s.FULL!r}`` - return the complete dataset containing `104 887` cells. - ``{s.K85!r}`` - return the subset as described in :cite:`morris:18` Fig. 1, containing `85 010` cells. - ``{s.K48!r}`` - return the subset as described in :cite:`morris:18` Fig. 3, containing `48 515` cells. - - %(dataset.parameters)s + kwargs + Keyword arguments for :func:`~scanpy.read`. Returns ------- @@ -216,10 +218,13 @@ def reprogramming_schiebinger( Parameters ---------- - %(dataset.parameters)s + path + Path where to save the dataset. subset_to_serum Whether to return the full object or subsetted to the serum condition. This subset also contains the pre-computed transition matrix. + kwargs + Keyword arguments for :func:`~scanpy.read`. Returns ------- @@ -251,7 +256,10 @@ def zebrafish( Parameters ---------- - %(dataset.parameters)s + path + Path where to save the dataset. + kwargs + Keyword arguments for :func:`~scanpy.read`. Returns ------- @@ -272,7 +280,10 @@ def bone_marrow( Parameters ---------- - %(dataset.parameters)s + path + Path where to save the dataset. + kwargs + Keyword arguments for :func:`~scanpy.read`. Returns ------- diff --git a/src/cellrank/estimators/__init__.py b/src/cellrank/estimators/__init__.py index cd33c6006..e9f8d32ac 100644 --- a/src/cellrank/estimators/__init__.py +++ b/src/cellrank/estimators/__init__.py @@ -1,5 +1,5 @@ from cellrank.estimators import mixins from cellrank.estimators._base_estimator import BaseEstimator -from cellrank.estimators.terminal_states import CFLARE, GPCCA +from cellrank.estimators.terminal_states import CFLARE, GPCCA, TermStatesEstimator -__all__ = ["mixins", "BaseEstimator", "CFLARE", "GPCCA"] +__all__ = ["mixins", "BaseEstimator", "TermStatesEstimator", "CFLARE", "GPCCA"] diff --git a/src/cellrank/estimators/_base_estimator.py b/src/cellrank/estimators/_base_estimator.py index 430aa2efb..76001de8c 100644 --- a/src/cellrank/estimators/_base_estimator.py +++ b/src/cellrank/estimators/_base_estimator.py @@ -52,7 +52,7 @@ class BaseEstimator(IOMixin, KernelMixin, AnnDataMixin, abc.ABC): If :obj:`None`, the directionality will be determined automatically and ``adata`` must be provided in this case. kwargs - Keyword arguments for :class:`cellrank.kernels.PrecomputedKernel`. + Keyword arguments for the :class:`~cellrank.kernels.PrecomputedKernel`. """ def __init__( diff --git a/src/cellrank/estimators/mixins/_lineage_drivers.py b/src/cellrank/estimators/mixins/_lineage_drivers.py index 134f2af0a..718d06024 100644 --- a/src/cellrank/estimators/mixins/_lineage_drivers.py +++ b/src/cellrank/estimators/mixins/_lineage_drivers.py @@ -89,7 +89,7 @@ def compute_lineage_drivers( - ``{tm.FISHER!r}`` - Fisher transformation :cite:`fisher:21`. - ``{tm.PERM_TEST!r}`` - permutation test. cluster_key - Key from :attr:`anndata.AnnData.obs` to obtain cluster annotations. These are considered for ``clusters``. + Key in :attr:`~anndata.AnnData.obs` to obtain cluster annotations. These are considered for ``clusters``. clusters Restrict the correlations to these clusters. layer @@ -104,6 +104,8 @@ def compute_lineage_drivers( seed Random seed when ``method = {tm.PERM_TEST!r}``. %(parallel)s + kwargs + Keyword for the correlation test. Returns ------- @@ -343,7 +345,7 @@ def plot_lineage_drivers_correlation( color Key in :attr:`~anndata.AnnData.var` or :attr:`~anndata.AnnData.varm`, preferring for the former. gene_sets - Gene sets annotations of the form `{'gene_set_name': ['gene_1', 'gene_2'], ...}`. + Gene sets annotations of the form ``{'gene_set_name': ['gene_1', 'gene_2'], ...}``. gene_sets_colors List of colors where each entry corresponds to a gene set from ``genes_sets``. If `None` and keys in ``gene_sets`` correspond to lineage names, use the lineage colors. diff --git a/src/cellrank/estimators/mixins/decomposition/_eigen.py b/src/cellrank/estimators/mixins/decomposition/_eigen.py index 12ea08dde..66f0dcee7 100644 --- a/src/cellrank/estimators/mixins/decomposition/_eigen.py +++ b/src/cellrank/estimators/mixins/decomposition/_eigen.py @@ -52,7 +52,7 @@ def eigendecomposition(self) -> Optional[Dict[str, Any]]: A dictionary with the following keys: - ``'D'`` - the eigenvalues. - - ``'eigengap'`` - the eigengap. + - ``'eigengap'`` - the `eigengap `__. - ``'params'`` - parameters used for the computation. - ``'V_l'`` - left eigenvectors (optional). - ``'V_r'`` - right eigenvectors (optional). @@ -183,7 +183,7 @@ def plot_spectrum( Marker symbol used, valid options can be found in :mod:`~matplotlib.markers`. %(plotting)s kwargs - Keyword arguments for :func:`~matplotlib.axes.Axes.scatter`. + Keyword arguments for :meth:`~matplotlib.axes.Axes.scatter`. Returns ------- diff --git a/src/cellrank/estimators/mixins/decomposition/_schur.py b/src/cellrank/estimators/mixins/decomposition/_schur.py index 78e93fbdf..793d0afb7 100644 --- a/src/cellrank/estimators/mixins/decomposition/_schur.py +++ b/src/cellrank/estimators/mixins/decomposition/_schur.py @@ -98,7 +98,7 @@ def eigendecomposition(self) -> Optional[Dict[str, Any]]: A dictionary with the following keys: - ``'D'`` - the eigenvalues. - - ``'eigengap'`` - the eigengap. + - ``'eigengap'`` - the `eigengap `__. - ``'params'`` - parameters used for the computation. - ``'V_l'`` - left eigenvectors (optional). - ``'V_r'`` - right eigenvectors (optional). @@ -135,7 +135,7 @@ def compute_schur( %(eigen)s verbose Whether to print extra information when computing the Schur decomposition. - If `None`, it's disabled when ``method = 'krylov'``. + If :obj:`None`, it's disabled when ``method = 'krylov'``. Returns ------- diff --git a/src/cellrank/estimators/terminal_states/_gpcca.py b/src/cellrank/estimators/terminal_states/_gpcca.py index fc2368266..007313fcc 100644 --- a/src/cellrank/estimators/terminal_states/_gpcca.py +++ b/src/cellrank/estimators/terminal_states/_gpcca.py @@ -57,6 +57,12 @@ class CoarseTOrder(ModeEnum): class GPCCA(TermStatesEstimator, LinDriversMixin, SchurMixin, EigenMixin): """Generalized Perron Cluster Cluster Analysis (GPCCA) :cite:`reuter:18,reuter:19`. + .. seealso:: + - See :doc:`../../../notebooks/tutorials/estimators/600_initial_terminal` on how to compute the + :attr:`initial ` and :attr:`terminal ` states. + - See :doc:`../../../notebooks/tutorials/estimators/700_fate_probabilities` on how to compute the + :attr:`fate_probabilities` and :attr:`lineage_drivers`. + This is our main and recommended estimator implemented in `pyGPCCA `_ . Use it to compute macrostates, automatically and semi-automatically classify these as initial, intermediate and terminal states, compute fate probabilities towards macrostates, uncover driver genes, and much more. To compute and @@ -147,7 +153,8 @@ def compute_macrostates( ---------- n_states Number of macrostates to compute. If a :class:`~typing.Sequence`, use the *minChi* - criterion :cite:`reuter:18`. If :obj:`None`, use the *eigengap* heuristic. + criterion :cite:`reuter:18`. If :obj:`None`, use the `eigengap `__ + heuristic. %(n_cells)s cluster_key If a key to cluster labels is given, names and colors of the states will be associated with the clusters. @@ -243,7 +250,8 @@ def predict_terminal_states( method How to select the terminal states. Valid option are: - - ``'eigengap'`` - select the number of states based on the *eigengap* of :attr:`transition_matrix`. + - ``'eigengap'`` - select the number of states based on the + `eigengap `__ of :attr:`transition_matrix`. - ``'eigengap_coarse'`` - select the number of states based on the *eigengap* of the diagonal of :attr:`coarse_T`. - ``'top_n'`` - select top ``n_states`` based on the probability of the diagonal of :attr:`coarse_T`. @@ -578,9 +586,9 @@ def plot_coarse_T( Parameters ---------- show_stationary_dist - Whether to show :attr:`coarse_stationary_distribution`, if present. + Whether to show the :attr:`coarse_stationary_distribution`, if present. show_initial_dist - Whether to show :attr:`coarse_initial_distribution`. + Whether to show the :attr:`coarse_initial_distribution`. order How to order the coarse-grained transition matrix. Valid options are: diff --git a/src/cellrank/kernels/__init__.py b/src/cellrank/kernels/__init__.py index 6994eca26..dfe3245f3 100644 --- a/src/cellrank/kernels/__init__.py +++ b/src/cellrank/kernels/__init__.py @@ -1,5 +1,9 @@ from cellrank.kernels import utils -from cellrank.kernels._base_kernel import Kernel +from cellrank.kernels._base_kernel import ( + BidirectionalKernel, + Kernel, + UnidirectionalKernel, +) from cellrank.kernels._connectivity_kernel import ConnectivityKernel from cellrank.kernels._cytotrace_kernel import CytoTRACEKernel from cellrank.kernels._experimental_time_kernel import ExperimentalTimeKernel @@ -11,6 +15,8 @@ __all__ = [ "utils", "Kernel", + "UnidirectionalKernel", + "BidirectionalKernel", "ConnectivityKernel", "CytoTRACEKernel", "ExperimentalTimeKernel", diff --git a/src/cellrank/kernels/_base_kernel.py b/src/cellrank/kernels/_base_kernel.py index c95cf9437..a521f14ae 100644 --- a/src/cellrank/kernels/_base_kernel.py +++ b/src/cellrank/kernels/_base_kernel.py @@ -271,7 +271,7 @@ def plot_projection( Parameters ---------- basis - Key in :attr:`anndata.AnnData.obsm` containing the basis. + Key in :attr:`~anndata.AnnData.obsm` containing the basis. key_added If not :obj:`None`, save the result to :attr:`adata.obsm['{key_added}'] `. Otherwise, save the result to ``'T_fwd_{basis}'`` or ``'T_bwd_{basis}'``, depending on the direction. @@ -369,6 +369,8 @@ def write_to_adata(self, key: Optional[str] = None, copy: bool = False) -> None: key Key used when writing transition matrix to :attr:`adata`. If :obj:`None`, the key will be determined automatically. + copy + Whether to copy the :attr:`transition_matrix`. Returns ------- @@ -462,8 +464,18 @@ def _reuse_cache(self, expected_params: Dict[str, Any], *, time: Optional[Any] = # fmt: on +@d.dedent class Kernel(KernelExpression, abc.ABC): - """Base kernel class.""" + """Base kernel class. + + Parameters + ---------- + %(adata)s + parent + Parent kernel expression. + kwargs + Keyword arguments for the parent. + """ def __init__(self, adata: AnnData, parent: Optional[KernelExpression] = None, **kwargs: Any): super().__init__(parent=parent, **kwargs) @@ -541,7 +553,7 @@ def copy(self, *, deep: bool = False) -> "Kernel": Parameters ---------- deep - Whether to use :meth:`~copy.deepcopy`. + Whether to use :func:`~copy.deepcopy`. Returns ------- @@ -611,11 +623,11 @@ def __str__(self) -> str: class UnidirectionalKernel(UnidirectionalMixin, Kernel, abc.ABC): - """Kernel with no directionality.""" + pass class BidirectionalKernel(BidirectionalMixin, Kernel, abc.ABC): - """Kernel with either forward or backward direction that can be inverted using :meth:`__invert__`.""" + pass class Constant(UnidirectionalKernel): diff --git a/src/cellrank/kernels/_cytotrace_kernel.py b/src/cellrank/kernels/_cytotrace_kernel.py index 401952a27..84d6ff268 100644 --- a/src/cellrank/kernels/_cytotrace_kernel.py +++ b/src/cellrank/kernels/_cytotrace_kernel.py @@ -29,10 +29,14 @@ class CytoTRACEAggregation(ModeEnum): class CytoTRACEKernel(PseudotimeKernel): """Kernel which computes directed transition probabilities using the CytoTRACE score :cite:`gulati:20`. + .. seealso:: + - See :doc:`../../../notebooks/tutorials/kernels/400_cytotrace` on how to + compute the :attr:`~cellrank.kernels.CytoTRACEKernel.transition_matrix` based on the CytoTRACE score. + The k-NN graph contains information about the (undirected) connectivities among cells, reflecting their similarity. CytoTRACE can be used to estimate cellular plasticity and in turn, a pseudotemporal ordering of cells from more plastic to less plastic states. It relies on the assumption that differentiated cells express, on average, - less genes than naive cells. + fewer genes than naive cells. This kernel internally uses the :class:`~cellrank.kernels.PseudotimeKernel` to direct the k-NN graph on the basis of the CytoTRACE pseudotime. @@ -44,7 +48,6 @@ class CytoTRACEKernel(PseudotimeKernel): %(adata)s %(backward)s kwargs - Keyword arguments for the parent class. Keyword arguments for the :class:`~cellrank.kernels.PseudotimeKernel`. Examples @@ -61,15 +64,17 @@ class CytoTRACEKernel(PseudotimeKernel): sc.pp.log1p(adata) sc.pp.highly_variable_genes(adata) - # CytoTRACE by default uses imputed data - a simple way to compute k-NN imputed data is to use scVelo's moments - # function. However, note that this function expects `spliced` counts because it's designed for RNA velocity, - # so we're using a simple hack here: + # CytoTRACE by default uses imputed data - a simple way to compute + # k-NN imputed data is to use scVelo's moments function. + # However, note that this function expects `spliced` counts because + # it's designed for RNA velocity, so we're using a simple hack here: if 'spliced' not in adata.layers or 'unspliced' not in adata.layers: adata.layers['spliced'] = adata.X adata.layers['unspliced'] = adata.X scv.pp.moments(adata) - ctk = cr.kernels.CytoTRACEKernel(adata).compute_cytotrace().compute_transition_matrix() + ctk = cr.kernels.CytoTRACEKernel(adata) + ckt = ctk.compute_cytotrace().compute_transition_matrix() """ def __init__( diff --git a/src/cellrank/kernels/_pseudotime_kernel.py b/src/cellrank/kernels/_pseudotime_kernel.py index 749dd352f..83cc59d9f 100644 --- a/src/cellrank/kernels/_pseudotime_kernel.py +++ b/src/cellrank/kernels/_pseudotime_kernel.py @@ -30,6 +30,10 @@ class ThresholdScheme(ModeEnum): class PseudotimeKernel(ConnectivityMixin, BidirectionalKernel): """Kernel which computes directed transition probabilities based on a k-NN graph and pseudotime. + .. seealso:: + - See :doc:`../../../notebooks/tutorials/kernels/300_pseudotime` on how to + compute the :attr:`~cellrank.kernels.PseudotimeKernel.transition_matrix` based on the pseudotime. + The k-NN graph contains information about the (undirected) connectivities among cells, reflecting their similarity. Pseudotime can be used to either remove edges that point against the direction of increasing pseudotime :cite:`setty:19` or to down-weight them :cite:`stassen:21`. diff --git a/src/cellrank/kernels/_real_time_kernel.py b/src/cellrank/kernels/_real_time_kernel.py index 63b48a7f6..494ef3a7a 100644 --- a/src/cellrank/kernels/_real_time_kernel.py +++ b/src/cellrank/kernels/_real_time_kernel.py @@ -56,6 +56,11 @@ class SelfTransitions(ModeEnum): class RealTimeKernel(UnidirectionalKernel): """Kernel which computes transition matrix using optimal transport couplings. + .. seealso:: + - See :doc:`../../../notebooks/tutorials/kernels/500_real_time` on how to + compute the :attr:`~cellrank.kernels.RealTimeKernel.transition_matrix` between experimental time points + using `optimal transport `_. + This class should be constructed using either: 1. the :meth:`from_moscot` or :meth:`from_wot` method, diff --git a/src/cellrank/kernels/_velocity_kernel.py b/src/cellrank/kernels/_velocity_kernel.py index 48539fdd2..50ec4ecd1 100644 --- a/src/cellrank/kernels/_velocity_kernel.py +++ b/src/cellrank/kernels/_velocity_kernel.py @@ -23,6 +23,10 @@ class VelocityKernel(ConnectivityMixin, BidirectionalKernel): """Kernel which computes a transition matrix based on RNA velocity. + .. seealso:: + - See :doc:`../../../notebooks/tutorials/kernels/200_rna_velocity` on how to + compute the :attr:`~cellrank.kernels.VelocityKernel.transition_matrix` based on RNA velocity. + This borrows ideas from both :cite:`manno:18` and :cite:`bergen:20`. In short, for each cell :math:`i`, we compute transition probabilities :math:`T_{i, j}` to each cell :math:`j` in the neighborhood of :math:`i`. We quantify how much the velocity vector :math:`v_i` of cell :math:`i` points towards each of its nearst neighbors. For diff --git a/src/cellrank/kernels/utils/__init__.py b/src/cellrank/kernels/utils/__init__.py index 5cb1ec41c..1e0e76db6 100644 --- a/src/cellrank/kernels/utils/__init__.py +++ b/src/cellrank/kernels/utils/__init__.py @@ -3,6 +3,7 @@ CustomThresholdScheme, HardThresholdScheme, SoftThresholdScheme, + ThresholdSchemeABC, ) from cellrank.kernels.utils._random_walk import RandomWalk from cellrank.kernels.utils._similarity import ( diff --git a/src/cellrank/models/_base_model.py b/src/cellrank/models/_base_model.py index 985440fac..c2c4ce45c 100644 --- a/src/cellrank/models/_base_model.py +++ b/src/cellrank/models/_base_model.py @@ -710,7 +710,7 @@ def plot( fate_prob_cmap Colormap to use when coloring in the fate probabilities. cell_color - Key in :attr:`anndata.AnnData.obs` or :attr:`~anndata.AnnData.var_names` used for coloring the cells. + Key in :attr:`~anndata.AnnData.obs` or :attr:`~anndata.AnnData.var_names` used for coloring the cells. lineage_color Color for the lineage. alpha @@ -740,7 +740,7 @@ def plot( Whether to compute and show smoothed lineage probability confidence interval. lineage_probability_color Color to use when plotting the smoothed ``lineage_probability``. - If :obj:`None`, it's the same as ``lineage_color``. Only used when ``show_lineage_probability=True``. + If :obj:`None`, it's the same as ``lineage_color``. Only used when ``show_lineage_probability = True``. obs_legend_loc Location of the legend when ``cell_color`` corresponds to a categorical variable. dpi diff --git a/src/cellrank/models/_gamr_model.py b/src/cellrank/models/_gamr_model.py index 88443d03b..fb072864f 100644 --- a/src/cellrank/models/_gamr_model.py +++ b/src/cellrank/models/_gamr_model.py @@ -37,7 +37,7 @@ class GAMR(BaseModel): Number of knots. distribution Distribution family in `rpy2.robjects.r`, such as ``'gaussian'`` or ``'nb'`` for negative binomial. - If ``'nb'``, raw count data in :attr:`adata` ``.raw`` is always used. + If ``'nb'``, raw count data in :attr:`~anndata.AnnData.raw` is always used. basis Basis for the smoothing term. See `here `__ for valid options. @@ -53,8 +53,8 @@ class GAMR(BaseModel): smoothing_penalty Penalty for the smoothing term. The larger the value, the smoother the fitted curve. kwargs - Keyword arguments for ``gam.control``. - See `here `__ for reference. + Keyword arguments for `gam control + `__. """ def __init__( diff --git a/src/cellrank/models/_pygam_model.py b/src/cellrank/models/_pygam_model.py index 5c234d671..75429827e 100644 --- a/src/cellrank/models/_pygam_model.py +++ b/src/cellrank/models/_pygam_model.py @@ -84,9 +84,9 @@ class GAM(BaseModel): Whether to perform a grid search. Keys correspond to a parameter names and values to range to be searched. If ``'default'``, use the default grid. If :obj:`None`, don't perform a grid search. spline_kwargs - Keyword arguments for :class:`~pygam.s`. + Keyword arguments for :func:`~pygam.terms.s`. kwargs - Keyword arguments for :class:`~pygam.pygam.GAM`. + Keyword arguments for the :class:`~pygam.pygam.GAM`. """ def __init__( diff --git a/src/cellrank/pl/_circular_projection.py b/src/cellrank/pl/_circular_projection.py index ab0c3f862..307c79391 100644 --- a/src/cellrank/pl/_circular_projection.py +++ b/src/cellrank/pl/_circular_projection.py @@ -103,7 +103,7 @@ def circular_projection( ---------- %(adata)s keys - Keys in :attr:`~anndata.AnnData.obs` or :attr:`anndata.AnnData.var_names`. Additional keys are: + Keys in :attr:`~anndata.AnnData.obs` or :attr:`~anndata.AnnData.var_names`. Additional keys are: - ``'kl_divergence'`` - as in :cite:`velten:17`, computes KL-divergence between the fate probabilities of a cell and the average fate probabilities. See ``early_cells`` for more information. @@ -143,13 +143,12 @@ def circular_projection( - ``'best'`` - rotate labels so that they are easily readable. - ``'default'`` - use :mod:`matplotlib`'s default. - :obj:`None` - same as ``'default'``. - - If a :class:`float`, all labels will be rotated by this many degrees. + - :class:`float`, all labels will be rotated by this many degrees. show_edges Whether to show the edges surrounding the simplex. key_added Key in :attr:`~anndata.AnnData.obsm` where to add the circular embedding. If :obj:`None`, it will be set to - `'X_fate_simplex_{fwd,bwd}'`, based on the ``backward``. + ``'X_fate_simplex_{fwd,bwd}'``, based on the ``backward``. %(plotting)s kwargs Keyword arguments for :func:`~scvelo.pl.scatter`. diff --git a/src/cellrank/pl/_cluster_trends.py b/src/cellrank/pl/_cluster_trends.py index e4e27f84f..a6b2cc764 100644 --- a/src/cellrank/pl/_cluster_trends.py +++ b/src/cellrank/pl/_cluster_trends.py @@ -74,6 +74,10 @@ def cluster_trends( ) -> Optional[_return_model_type]: """Cluster and plot gene expression trends within a lineage. + .. seealso:: + - See :doc:`../../../notebooks/tutorials/estimators/800_gene_trends` on how to + visualize the gene trends. + This function is based on *Palantir* :cite:`setty:19`. It can be used to discover modules of genes that drive development along a given lineage. Consider running this function on a subset of genes which are potential lineage drivers. diff --git a/src/cellrank/pl/_gene_trend.py b/src/cellrank/pl/_gene_trend.py index 6629866e9..3c41107df 100644 --- a/src/cellrank/pl/_gene_trend.py +++ b/src/cellrank/pl/_gene_trend.py @@ -83,6 +83,10 @@ def gene_trends( ) -> Optional[_return_model_type]: """Plot gene expression trends along lineages. + .. seealso:: + - See :doc:`../../../notebooks/tutorials/estimators/800_gene_trends` on how to + visualize the gene trends. + Each lineage is defined via its lineage weights. This function accepts any model based off :class:`~cellrank.models.BaseModel` to fit gene expression, where we take the lineage weights into account in the loss function. @@ -158,7 +162,7 @@ def gene_trends( %(parallel)s %(plotting)s plot_kwargs - Keyword arguments for :meth:`~cellrank.models.BaseModel.plot`. + Keyword arguments for the :meth:`~cellrank.models.BaseModel.plot`. kwargs Keyword arguments for :meth:`~cellrank.models.BaseModel.prepare`. diff --git a/src/cellrank/pl/_heatmap.py b/src/cellrank/pl/_heatmap.py index bbceb2506..a11f2b89e 100644 --- a/src/cellrank/pl/_heatmap.py +++ b/src/cellrank/pl/_heatmap.py @@ -92,6 +92,10 @@ def heatmap( ) -> Optional[Union[Dict[str, pd.DataFrame], Tuple[_return_model_type, Dict[str, pd.DataFrame]]]]: """Plot a heatmap of smoothed gene expression along specified lineages. + .. seealso:: + - See :doc:`../../../notebooks/tutorials/estimators/800_gene_trends` on how to + visualize the gene trends. + This requires a pseudotemporal ordering of cellular dynamics, computed using a method like DPT :cite:`haghverdi:16` or Palantir :cite:`setty:19`. The function combines the pseudotemporal ordering with CellRank's fate probabilities to visualize each gene's expression along specific diff --git a/src/cellrank/pl/_log_odds.py b/src/cellrank/pl/_log_odds.py index 99f45b0ad..2f778dec8 100644 --- a/src/cellrank/pl/_log_odds.py +++ b/src/cellrank/pl/_log_odds.py @@ -52,7 +52,7 @@ def log_odds( """Plot log-odds ratio between trajectories. This plotting function is geared towards time-series datasets that have been analyzed - using the :class:`cellrank.external.kernels.WOTKernel`. It visualizes log-odd ratios + using the :class:`~cellrank.kernels.RealTimeKernel`. It visualizes log-odd ratios between different trajectories per cell, with the option to color in certain molecular features, like genes. This can be useful to detect and visualize fate-decisive genes.