Inferring Trajectories using Python (Jupyter Notebook) in Galaxy

Author(s) orcid logoAvatarWendi BaconAvatarMehmet Tekman
Editor(s) orcid logoAvatarHelena Rasche
Tester(s) AvatarJulia Jakiela
Overview
Questions:
  • How can I infer lineage relationships between single cells based on their RNA, without a time series?

Objectives:
  • Execute multiple plotting methods designed to maintain lineage relationships between cells

  • Interpret these plots

Requirements:
Time estimation: 2 hours
Supporting Materials:
Last modification: Nov 17, 2022
License: Tutorial Content is licensed under Creative Commons Attribution 4.0 International License The GTN Framework is licensed under MIT

Introduction

You’ve done all the hard work of preparing a single cell matrix, processing it, plotting it, interpreting it, finding lots of lovely genes, all within the glorious Galaxy interface. Now you want to infer trajectories, or relationships between cells… and you’ve been threatened with learning Python to do so! Well, fear not. If you can have a run-through of a basic python coding introduction such as this one, then that will help you make more sense of this tutorial, however you’ll be able to make and interpret glorious plots even without understanding the Python coding language. This is the beauty of Galaxy - all the ‘set-up’ is identical across computers, because it’s browser based. So fear not!

Traditionally, we thought that differentiating or changing cells jumped between discrete states, so ‘Cell A’ became ‘Cell B’ as part of its maturation. However, most data shows otherwise, that generally there is a spectrum (a ‘trajectory’, if you will…) of small, subtle changes along a pathway of that differentiation. Trying to analyse cells every 10 seconds can be pretty tricky, so ‘pseudotime’ analysis takes a single sample and assumes that those cells are all on slightly different points along a path of differentiation. Some cells might be slightly more mature and others slightly less, all captured at the same ‘time’. We ‘assume’ or ‘infer’ relationships between cells.

We will use the same sample from the previous three tutorials, which contains largely T-cells in the thymus. We know T-cells differentiate in the thymus, so we would assume that we would capture cells at slightly different time points within the same sample. Furthermore, our cluster analysis alone showed different states of T-cell. Now it’s time to look further!

Agenda

In this tutorial, we will cover:

  1. Introduction
    1. Get data
    2. Filtering for T-cells
    3. Launching Jupyter
  2. Run the tutorial!
  3. Tutorial Plot Answers
  4. After Jupyter
  5. Conclusion

Get data

We’ve provided you with experimental data to analyse from a mouse dataset of fetal growth restriction Bacon et al. 2018. This is the full dataset generated from this tutorial (see the study in Single Cell Expression Atlas and the project submission). You can find the final dataset in this input history or download from Zenodo below.

Hands-on: Data upload
  1. Create a new history for this tutorial
  2. Import the AnnData object from Zenodo

    https://zenodo.org/record/7075718/files/Trajectories_Instructions.ipynb
    https://zenodo.org/record/7075718/files/Final_cell_annotated_object.h5ad
    
    • Copy the link location
    • Open the Galaxy Upload Manager (galaxy-upload on the top-right of the tool panel)

    • Select Paste/Fetch Data
    • Paste the link into the text field

    • Press Start

    • Close the window
  3. Rename galaxy-pencil the .h5ad object as Final cell annotated object

    • Click on the galaxy-pencil pencil icon for the dataset to edit its attributes
    • In the central panel, change the Name field to Final cell annotated object
    • Click the Save button
  4. Check that the datatype is h5ad

    • Click on the galaxy-pencil pencil icon for the dataset to edit its attributes
    • In the central panel, click on the galaxy-chart-select-data Datatypes tab on the top
    • Select h5ad
      • tip: you can start typing the datatype into the field to filter the dropdown menu
    • Click the Save button
  5. Rename galaxy-pencil the .ipynb object as Trajectories_Instructions.ipynb

  6. Check that the datatype is .ipynb

Filtering for T-cells

One problem with our current dataset is that it’s not just T-cells: we found in the previous tutorial that it also contains macrophages. This is a problem, because trajectory analysis will generally try to find relationships between all the cells in the sample. We need to remove those cell types to analyse the trajectory.

Tools are frequently updated to new versions. Your Galaxy may have multiple versions of the same tool available. By default, you will be shown the latest version of the tool. This may NOT be the same tool used in the tutorial you are accessing. Furthermore, if you use a newer tool in one step, and try using an older tool in the next step… this may fail! To ensure you use the same tool versions of a given tutorial, use the Tutorial mode feature.

  • Open your Galaxy server
  • Click on the curriculum icon on the top menu, this will open the GTN inside Galaxy.
  • Navigate to your tutorial
  • Tool names in tutorials will be blue buttons that open the correct tool for you
  • Note: this does not work for all tutorials (yet) gif showing how GTN-in-Galaxy works
  • You can click anywhere in the grey-ed out area outside of the tutorial box to return back to the Galaxy analytical interface
Hands-on: Removing macrophages
  1. Manipulate AnnData Tool: toolshed.g2.bx.psu.edu/repos/iuc/anndata_manipulate/anndata_manipulate/0.7.5+galaxy1 with the following parameters:
    • param-file “Annotated data matrix”: Final cell annotated object
    • “Function to manipulate the object”: Filter observations or variables
    • “What to filter?”: Observations (obs)
    • “Type of filtering?”: By key (column) values
    • “Key to filter”: cell_type
    • “Type of value to filter”: Text
    • “Filter”: not equal to
    • “Value”: Macrophages
  2. Rename galaxy-pencil output h5ad T-cell_object.h5ad

You should now have 8569 cells, as opposed to the 8605 you started with. You’ve only removed a few cells (the contaminants!), but it makes a big difference in the next steps.

Take note of what # this dataset is in your history, as you will need that shortly!

Launching Jupyter

Warning: Data uploads and Jupyter

There are a few ways of importing and uploading data in Jupyter. You might find yourself accidentally doing this differently than the tutorial, and that’s ok. There are a few key steps where you will call files from a location - if these don’t work from you, check that the file location is correct and change accordingly!

JupyterLab is a bit like RStudio but for other coding languages. What, you’ve never heard of RStudio? Then don’t worry, just follow the instructions!

warning Please note: this is only currently available on the usegalaxy.eu and usegalaxy.org sites.

Hands-on: Downloading the tutorial notebook
  1. You will need to download the tutorial notebook locally to your own computer. Do this by going here: Download the notebook
Hands-on: Launching JupyterLab
  1. Interactive JupyTool and Notebook Tool: interactive_tool_jupyter_notebook with the following parameters:
    • “Do you already have a notebook?”: Start with a fresh notebook

    This may take a moment, but once the Executed notebook in your dataset is orange, you are up and running!

  2. Either click on the blue User menu, or go to the top of the screen and choose User and then Active InteractiveTools

  3. Click on the newest JupyTool interactive tool.

Welcome!

Warning: Danger: You can lose data!

Do NOT delete or close this notebook dataset in your history. YOU WILL LOSE IT!

Hands-on: Creating a notebook
  1. Click the Python 3 icon under Notebook
Python 3 icon.
Figure 1: Python 3 Button
  1. Save your file (File: Save, or click the galaxy-save Save icon at the top left)

  2. If you right click on the file in the folder window at the left, you can rename your file whateveryoulike.ipynb

Cool! Now you know how to create a file! Helpfully, however, we have created one for you, and you’ve downloaded it onto your computer already!

Hands-on: Uploading the tutorial notebook
  1. In the folder window, galaxy-upload Upload the Trajectories_Instructions.ipynb from your computer. It should appear in the file window.

  2. Open it by double clicking it in the file window.

Warning: You should Save frequently!

This is both for good practice and to protect you in case you accidentally close the browser. Your environment will still run, so it will contain the last saved notebook you have. You might eventually stop your environment after this tutorial, but ONLY once you have saved and exported your notebook (more on that at the end!) Note that you can have multiple notebooks going at the same time within this JupyterLab, so if you do, you will need to save and export each individual notebook. You can also download them at any time.

Run the tutorial!

At this point, to prevent you having to switch back and forth between browsers, the directions for the rest of tutorial are all in the notebook you input! You may have to change certain numbers in the code blocks, so do read carefully. You will be able to run each step be clicking on the code block and pressing the workflow-run Run the selected cells and advance step. You will want to keep a tab open with your Galaxy history showing (so just launch another browser of your usegalaxy.eu instance), so that you can see when your files appear there. The tutorial is adapted from the Scanpy Trajectory inference tutorial.

Tutorial Plot Answers

Just in case, we’ve put the plots you should generate in the tutorial here. If things have gone wrong, you can also download this answer key tutorial.

Plot1-Force-Directed Graph.
Figure 2: Plot1-Force-Directed Graph
Diffusion Map.
Figure 3: Diffusion Map
PAGA.
Figure 4: PAGA
Force-Directed + PAGA - Cell type.
Figure 5: Force-Directed + PAGA - Cell type
Force-Directed + PAGA - Genotype.
Figure 6: Force-Directed + PAGA - Genotype
Force-Directed + PAGA - Markers.
Figure 7: Force-Directed + PAGA - Markers
Force-Directed + Pseudotime.
Figure 8: Force-Directed + Pseudotime

After Jupyter

congratulations Congratulations! You’ve made it through Jupyter!

Hands-on: Closing JupyterLab
  1. Click User: Active Interactive Tools

  2. Tick galaxy-selector the box of your Jupyter Interactive Tool, and click Stop

If you want to run this notebook again, or share it with others, it now exists in your history. You can use this ‘finished’ version just the same way as you downloaded the directions file and uploaded into the Jupyter environment.

Conclusion

congratulations Congratulations! You’ve made it to the end! You might be interested in the Answer Key History or the Answer Key Jupyter Notebook.

In this tutorial, you moved from called clusters to inferred relationships and trajectories using pseudotime analysis. You found an alternative to PCA (diffusion map), an alternative to tSNE (force-directed graph), a means of identifying cluster relationships (PAGA), and a metric for pseudotime (diffusion pseudotime) to identify early and late cells. If you were working in a group, you found that such analysis is slightly more sensitive to your decisions than the simpler filtering/plotting/clustering is. We are inferring and assuming relationships and time, so that makes sense!

To discuss with like-minded scientists, join our Gitter channel for all things Galaxy-single cell! Gitter.

Key points
  • Trajectory analysis is less robust than pure plotting methods, as such ‘inferred relationships’ are a bigger mathematical leap

  • As always with single-cell analysis, you must know enough biology to deduce if your analysis is reasonable, before exploring or deducing novel insight

Frequently Asked Questions

Have questions about this tutorial? Check out the tutorial FAQ page or the FAQ page for the Single Cell topic to see if your question is listed there. If not, please ask your question on the GTN Gitter Channel or the Galaxy Help Forum

Useful literature

Further information, including links to documentation and original publications, regarding the tools, analysis techniques and the interpretation of results described in this tutorial can be found here.

References

  1. Bacon, W. A., R. S. Hamilton, Z. Yu, J. Kieckbusch, D. Hawkes et al., 2018 Single-Cell Analysis Identifies Thymic Maturation Delay in Growth-Restricted Neonatal Mice. Frontiers in Immunology 9: 10.3389/fimmu.2018.02523

Feedback

Did you use this material as an instructor? Feel free to give us feedback on how it went.
Did you use this material as a learner or student? Click the form below to leave feedback.

Click here to load Google feedback frame

Citing this Tutorial

  1. Wendi Bacon, Mehmet Tekman, Inferring Trajectories using Python (Jupyter Notebook) in Galaxy (Galaxy Training Materials). https://training.galaxyproject.org/training-material/topics/single-cell/tutorials/scrna-case_JUPYTER-trajectories/tutorial.html Online; accessed TODAY
  2. Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012



@misc{single-cell-scrna-case_JUPYTER-trajectories,
author = "Wendi Bacon and Mehmet Tekman",
title = "Inferring Trajectories using Python (Jupyter Notebook) in Galaxy (Galaxy Training Materials)",
year = "",
month = "",
day = ""
url = "\url{https://training.galaxyproject.org/training-material/topics/single-cell/tutorials/scrna-case_JUPYTER-trajectories/tutorial.html}",
note = "[Online; accessed TODAY]"
}
@article{Hiltemann_2023,
	doi = {10.1371/journal.pcbi.1010752},
	url = {https://doi.org/10.1371%2Fjournal.pcbi.1010752},
	year = 2023,
	month = {jan},
	publisher = {Public Library of Science ({PLoS})},
	volume = {19},
	number = {1},
	pages = {e1010752},
	author = {Saskia Hiltemann and Helena Rasche and Simon Gladman and Hans-Rudolf Hotz and Delphine Larivi{\`{e}}re and Daniel Blankenberg and Pratik D. Jagtap and Thomas Wollmann and Anthony Bretaudeau and Nadia Gou{\'{e}} and Timothy J. Griffin and Coline Royaux and Yvan Le Bras and Subina Mehta and Anna Syme and Frederik Coppens and Bert Droesbeke and Nicola Soranzo and Wendi Bacon and Fotis Psomopoulos and Crist{\'{o}}bal Gallardo-Alba and John Davis and Melanie Christine Föll and Matthias Fahrner and Maria A. Doyle and Beatriz Serrano-Solano and Anne Claire Fouilloux and Peter van Heusden and Wolfgang Maier and Dave Clements and Florian Heyl and Björn Grüning and B{\'{e}}r{\'{e}}nice Batut and},
	editor = {Francis Ouellette},
	title = {Galaxy Training: A powerful framework for teaching!},
	journal = {PLoS Comput Biol} Computational Biology}
}

                   

Congratulations on successfully completing this tutorial!