Skip to content

Commit

Permalink
Merge pull request #56 from theislab/feature/init_term_tutorial
Browse files Browse the repository at this point in the history 
Add a tutorial about initial and terminal state inference.
  • Loading branch information
@Marius1311
Marius1311 authored Jun 14, 2023
2 parents b300a92 + bed0d10 commit 120dc07
Show file tree
Hide file tree
Showing 7 changed files with 4,753 additions and 132 deletions.
Binary file added tutorials/_static/img/gpcca_example.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added tutorials/_static/img/initial_terminal.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
55 changes: 24 additions & 31 deletions tutorials/cellrank_meets_cytotrace.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# CellRank meets CytoTRACE"
"# CellRank Meets CytoTRACE"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
":::{note}\n",
"\n",
"If you encounter any bugs in the code, our if you have suggestions for new features, please open an [issue](https://github.com/theislab/cellrank/issues/new/choose). If you have a general question or something you would like to discuss with us, please post on the [scverse discourse](https://discourse.scverse.org/c/ecosytem/cellrank/40). You can also contact us using info@cellrank.org. \n",
"\n",
":::"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Preliminaries"
"## Preliminaries"
]
},
{
Expand All @@ -35,7 +24,7 @@
"- set up CellRank's {class}`~cellrank.kernels.CytoTRACEKernel` to compute a transition matrix based on the CytoTRACE score. \n",
"- visualize the transition matrix in a low-dimensional embedding. \n",
"\n",
"Here's a conceptual overview of how we compute the CytoTRACE score:"
"This tutorial notebook can be downloaded using the following [link](https://github.com/theislab/cellrank_notebooks/raw/main/tutorials/cellrank_meets_cytotrace.ipynb)."
]
},
{
Expand All @@ -47,11 +36,11 @@
}
},
"source": [
":::{fig} fig-intro\n",
":::{figure-md} fig-intro\n",
"\n",
"<img src=\"_static/img/cytotrace_score.jpg\" width=\"800px\" alt=\"CytoTRACE uses the number of genes expressed per cell to estimate a developmental potential.\">\n",
"\n",
"**CytoTRACE estimates differentiation potential***: Following the original CytoTRACE suggestion, we use the number of genes expressed per cell as a raw signal of differentiation status and apply several post-processing steps to increase robustness. The basic assumption behind this method is that naive cells on average express more genes compared to mature cells because they regulate their chromatin less tightly; we've observed this to work well for many early developmental datasets. \n",
"**CytoTRACE estimates differentiation potential**: Following the original CytoTRACE suggestion, we use the number of genes expressed per cell as a raw signal of differentiation status and apply several post-processing steps to increase robustness. The basic assumption behind this method is that naive cells on average express more genes compared to mature cells because they regulate their chromatin less tightly; we've observed this to work well for many early developmental datasets. \n",
"\n",
":::"
]
Expand All @@ -78,7 +67,7 @@
"source": [
":::{note}\n",
"\n",
"If you want to run this on your own data, you will need...\n",
"If you want to run this on your own data, you will need:\n",
"\n",
"- a scRNA-seq dataset which satisfies the CytoTRACE assumptions, i.e., naive cell states should on avarage express more genes. This is often the case for early develpmental stages. \n",
"\n",
Expand All @@ -89,7 +78,11 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"This tutorial notebook can be downloaded using the following [link](https://github.com/theislab/cellrank_notebooks/raw/master/tutorials/cellrank_meets_cytotrace.ipynb)."
":::{note}\n",
"\n",
"If you encounter any bugs in the code, our if you have suggestions for new features, please open an [issue](https://github.com/theislab/cellrank/issues/new/choose). If you have a general question or something you would like to discuss with us, please post on the [scverse discourse](https://discourse.scverse.org/c/ecosytem/cellrank/40). You can also contact us using info@cellrank.org. \n",
"\n",
":::"
]
},
{
Expand All @@ -98,7 +91,7 @@
"hidePrompt": true
},
"source": [
"## Import packages & data"
"### Import packages & data"
]
},
{
Expand Down Expand Up @@ -201,7 +194,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Explore the data"
"### Explore the data"
]
},
{
Expand Down Expand Up @@ -282,7 +275,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Preprocess"
"### Preprocess"
]
},
{
Expand Down Expand Up @@ -362,14 +355,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Use developmental potential to direct differentiation"
"## Use developmental potential to direct differentiation"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Compute the CytoTRACE score"
"### Compute the CytoTRACE score"
]
},
{
Expand Down Expand Up @@ -508,7 +501,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Compute & visualize a transition matrix"
"### Compute & visualize a transition matrix"
]
},
{
Expand Down Expand Up @@ -768,32 +761,32 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Closing matters"
"## Closing matters"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## What's next? "
"### What's next? "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In this tutorial, you learned how to use CellRank to compute a transition matrix based on the CytoTRACE pseudotime and how it can be visualized in low dimensions. The real power of CellRank comes in when you use estimators to analyze the transition matrix directly, rather than projecting it. For the next steps, we recommend...\n",
"In this tutorial, you learned how to use CellRank to compute a transition matrix based on the CytoTRACE pseudotime and how it can be visualized in low dimensions. The real power of CellRank comes in when you use estimators to analyze the transition matrix directly, rather than projecting it. For the next steps, we recommend to:\n",
"\n",
"- going through the {doc}`initial and terminal states tutorial <initial_terminal>` to learn how to use the transition matrix to automatically identify initial and terminal states. \n",
"- taking a look at the {class}`API <cellrank.kernels.CytoTRACEKernel>` to learn about parameter values you can use to adapt these computations to your data. \n",
"- reading the original CytoTRACE publication and considering limitations of this appraoch {cite}`gulati:20`. "
"- go through the {doc}`initial and terminal states tutorial <initial_terminal>` to learn how to use the transition matrix to automatically identify initial and terminal states. \n",
"- take a look at the {class}`API <cellrank.kernels.CytoTRACEKernel>` to learn about parameter values you can use to adapt these computations to your data. \n",
"- read the original CytoTRACE publication and considering limitations of this appraoch {cite}`gulati:20`. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Package versions"
"### Package versions"
]
},
{
Expand Down
66 changes: 30 additions & 36 deletions tutorials/cellrank_meets_pseudotime.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# CellRank meets pseudotime"
"# CellRank Meets Pseudotime"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
":::{note}\n",
"\n",
"If you encounter any bugs in the code, our if you have suggestions for new features, please open an [issue](https://github.com/theislab/cellrank/issues/new/choose). If you have a general question or something you would like to discuss with us, please post on the [scverse discourse](https://discourse.scverse.org/c/ecosytem/cellrank/40). You can also contact us using info@cellrank.org. \n",
"\n",
":::"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Preliminaries"
"## Preliminaries"
]
},
{
Expand All @@ -35,7 +24,9 @@
"- use CellRank's {class}`~cellrank.kernels.PseudotimeKernel` to compute a transition matrix based on *any* pseudotime of your liking. \n",
"- visualize the transition matrix in a low-dimensional embedding. \n",
"\n",
"Along the way, we'll see an example where RNA velocity does not work well {cite}`manno:18, bergen:20, bergen:21`; this motivates us to use the {class}`~cellrank.kernels.PseudotimeKernel`. "
"Along the way, we'll see an example where RNA velocity does not work well {cite}`manno:18, bergen:20, bergen:21`; this motivates us to use the {class}`~cellrank.kernels.PseudotimeKernel`. \n",
"\n",
"This tutorial notebook can be downloaded using the following [link](https://github.com/theislab/cellrank_notebooks/raw/main/tutorials/cellrank_meets_pseudotime.ipynb)."
]
},
{
Expand All @@ -61,7 +52,7 @@
"metadata": {},
"source": [
":::{note}\n",
"If you want to run this on your own data, you will need...\n",
"If you want to run this on your own data, you will need:\n",
"\n",
"- a scRNA-seq dataset for which you have computed a pseudotime using a tool like {func}`~scanpy.tl.dpt` {cite}`haghverdi:16`, Palantir {cite}`setty:19` or Slingshot {cite}`street:18`.\n",
"\n",
Expand All @@ -72,14 +63,18 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"This tutorial notebook can be downloaded using the following [link](https://github.com/theislab/cellrank_notebooks/raw/master/tutorials/cellrank_meets_pseudotime.ipynb)."
":::{note}\n",
"\n",
"If you encounter any bugs in the code, our if you have suggestions for new features, please open an [issue](https://github.com/theislab/cellrank/issues/new/choose). If you have a general question or something you would like to discuss with us, please post on the [scverse discourse](https://discourse.scverse.org/c/ecosytem/cellrank/40). You can also contact us using info@cellrank.org. \n",
"\n",
":::"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Import packages & data"
"### Import packages & data"
]
},
{
Expand Down Expand Up @@ -188,7 +183,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Check RNA velocity on this data"
"## Check RNA velocity on this data"
]
},
{
Expand Down Expand Up @@ -526,15 +521,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"::: {figure-md} fig-no-clps\n",
"\n",
"<img src=\"_static/img/bm_driver_genes.jpg\" \n",
"alt=\"Without the CLPs, the top-likelihood genes look like they require state and time-dependent rates.\">"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Even with CLPs removed, projected velocities still point oppposite to what's known. The top-likelihood genes look different now - the CLP outliers have been removed; however, many of these top-influential genes show signs of state and time-dependent kinetic parameters. For example, in *ANK1*, Erythroid cells seem to require their own parameter set and in *RPS16*, the direction is inverted, i.e., an up-regulation is detected as a down-regulation, probably due to transcriptional bursting {cite}`bergen:21, barile:21`. "
"alt=\"Without the CLPs, the top-likelihood genes look like they require state and time-dependent rates.\">\n",
"\n",
"**Removing CLPs does not resolve the problem:** Even with CLPs removed, projected velocities still point oppposite to what's known. The top-likelihood genes look different now - the CLP outliers have been removed; however, many of these top-influential genes show signs of state and time-dependent kinetic parameters. For example, in *ANK1*, Erythroid cells seem to require their own parameter set and in *RPS16*, the direction is inverted, i.e., an up-regulation is detected as a down-regulation, probably due to transcriptional bursting {cite}`bergen:21, barile:21`. \n",
"\n",
":::"
]
},
{
Expand All @@ -548,14 +542,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Use pseudotime to recover directed differentiation"
"## Use pseudotime to recover directed differentiation"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Choosing the right pseudotime"
"### Choosing the right pseudotime"
]
},
{
Expand Down Expand Up @@ -741,7 +735,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Compute a transition matrix"
"### Compute a transition matrix"
]
},
{
Expand Down Expand Up @@ -883,32 +877,32 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Closing matters"
"## Closing matters"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## What's next? "
"### What's next? "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In this tutorial, you learned how to use CellRank to compute a transition matrix using any precomputed pseudotime and how it can be visualized in low dimensions. The real power of CellRank comes in when you use estimators to analyze the transition matrix directly, rather than projecting it. For the next steps, we recommend...\n",
"In this tutorial, you learned how to use CellRank to compute a transition matrix using any precomputed pseudotime and how it can be visualized in low dimensions. The real power of CellRank comes in when you use estimators to analyze the transition matrix directly, rather than projecting it. For the next steps, we recommend to:\n",
"\n",
"- going through the {doc}`initial and terminal states tutorial <initial_terminal>` to learn how to use the transition matrix to automatically identify initial and terminal states. \n",
"- taking a look at the {class}`API <cellrank.kernels.PseudotimeKernel>` to learn about parameter values you can use to adapt these computations to your data. \n",
"- exploring the vast amount of pseudotime methods to find the one that works best for your data {cite}`saelens:19`. "
"- go through the {doc}`initial and terminal states tutorial <initial_terminal>` to learn how to use the transition matrix to automatically identify initial and terminal states. \n",
"- take a look at the {class}`API <cellrank.kernels.PseudotimeKernel>` to learn about parameter values you can use to adapt these computations to your data. \n",
"- explore the vast amount of pseudotime methods to find the one that works best for your data {cite}`saelens:19`. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Package versions"
"### Package versions"
]
},
{
Expand Down
Loading

0 comments on commit 120dc07

Please sign in to comment.