v0.2.0 update

Teichlab · Apr 18, 2024 · 044acbf · 044acbf
1 parent 2973e83
commit 044acbf
Show file tree

Hide file tree

Showing 97 changed files with 13,461 additions and 152 deletions.
diff --git a/doc/build/doctrees/G2Gtutorial.doctree b/doc/build/doctrees/G2Gtutorial.doctree
diff --git a/doc/build/doctrees/environment.pickle b/doc/build/doctrees/environment.pickle
diff --git a/doc/build/doctrees/index.doctree b/doc/build/doctrees/index.doctree
diff --git a/doc/build/doctrees/notebooks/G2G_Tutorial.doctree b/doc/build/doctrees/notebooks/G2G_Tutorial.doctree
diff --git a/doc/build/html/.buildinfo b/doc/build/html/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 6e59a27ad7a662760f493dfdc52ce191
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/doc/build/html/G2Gtutorial.html b/doc/build/html/G2Gtutorial.html
@@ -0,0 +1,107 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en">
+<head>
+  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
+
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Tutorial &mdash; Genes2Genes v1.0 documentation</title>
+      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=80d5e7a1" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=19f00094" />
+      <link rel="stylesheet" type="text/css" href="_static/mystnb.4510f1fc1dee50b3e5859aac5469c37c29e427902b24a333a5f9fcb2f0b3ac41.css" />
+
+
+  <!--[if lt IE 9]>
+    <script src="_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+
+        <script src="_static/jquery.js?v=5d32c60e"></script>
+        <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=99a04888"></script>
+        <script src="_static/doctools.js?v=888ff710"></script>
+        <script src="_static/sphinx_highlight.js?v=4825356b"></script>
+    <script src="_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+
+
+
+          <a href="index.html" class="icon icon-home">
+            Genes2Genes
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <ul>
+<li class="toctree-l1"><a class="reference internal" href="index.html">Genes2Genes</a></li>
+</ul>
+
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="index.html">Genes2Genes</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
+      <li class="breadcrumb-item active">Tutorial</li>
+      <li class="wy-breadcrumbs-aside">
+            <a href="_sources/G2Gtutorial.rst.txt" rel="nofollow"> View page source</a>
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+
+  <section id="tutorial">
+<span id="g2gtutorial"></span><h1>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this heading"></a></h1>
+<p>Load the reference and query datasets:</p>
+</section>
+
+
+           </div>
+          </div>
+          <footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2023, Dinithi Sumanaweera, Teichmann Lab.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>
diff --git a/...ml/_images/0f49cc6ea04e7560f7e38ef277c43c473fb2c114edb9c923ec54746560932631.png b/...ml/_images/0f49cc6ea04e7560f7e38ef277c43c473fb2c114edb9c923ec54746560932631.png
diff --git a/...ml/_images/1249cf2744ee0e02646e34175d71b6a67f9c42accae56a668d19e0b7878125e1.png b/...ml/_images/1249cf2744ee0e02646e34175d71b6a67f9c42accae56a668d19e0b7878125e1.png
diff --git a/...ml/_images/21bde91f0cf441f6e0b83164dc91ae20106399b58b59ea446fe1360130b89d59.png b/...ml/_images/21bde91f0cf441f6e0b83164dc91ae20106399b58b59ea446fe1360130b89d59.png
diff --git a/...ml/_images/4df0fb434f256a77fbd87625bbb67dcf1d4eefaffc075b69e6d86b2c48c7c0ae.png b/...ml/_images/4df0fb434f256a77fbd87625bbb67dcf1d4eefaffc075b69e6d86b2c48c7c0ae.png
diff --git a/...ml/_images/561939030134240ae731fdaf091e92c989c5dc668ccb71cab3fb1008ddadfc4c.png b/...ml/_images/561939030134240ae731fdaf091e92c989c5dc668ccb71cab3fb1008ddadfc4c.png
diff --git a/...ml/_images/58f3c09a4c27a161a12922d47eafa60f7e08d0879ce897dc6366bc05fe4d6ce3.png b/...ml/_images/58f3c09a4c27a161a12922d47eafa60f7e08d0879ce897dc6366bc05fe4d6ce3.png
diff --git a/...ml/_images/5fdca400912538b8363649e2dba555b9f552160bed25ad93b6dfa30ca6062120.png b/...ml/_images/5fdca400912538b8363649e2dba555b9f552160bed25ad93b6dfa30ca6062120.png
diff --git a/...ml/_images/72ff20b01b33de3342d3d0b25986dba1f16ca456780e54094b50ff646bcfe058.png b/...ml/_images/72ff20b01b33de3342d3d0b25986dba1f16ca456780e54094b50ff646bcfe058.png
diff --git a/...ml/_images/9f89830ecc564797d3b60b6b15f2bb6f522db808f9a2c22df9b53f0a2a67673c.png b/...ml/_images/9f89830ecc564797d3b60b6b15f2bb6f522db808f9a2c22df9b53f0a2a67673c.png
diff --git a/doc/build/html/_images/DocFigs1-1.png b/doc/build/html/_images/DocFigs1-1.png
diff --git a/doc/build/html/_images/DocFigs1-3.png b/doc/build/html/_images/DocFigs1-3.png
diff --git a/doc/build/html/_images/DocFigs1.png b/doc/build/html/_images/DocFigs1.png
diff --git a/doc/build/html/_images/DocFigs2.png b/doc/build/html/_images/DocFigs2.png
diff --git a/...ml/_images/a26fdcf8a6a8dac35b6be3103d34a63301abebd8099ef415b6fb37c05291d90e.png b/...ml/_images/a26fdcf8a6a8dac35b6be3103d34a63301abebd8099ef415b6fb37c05291d90e.png
diff --git a/...ml/_images/a918c2cd67d97aede6980dfc0dfea90a00647fd39f6428459a820fd078809147.png b/...ml/_images/a918c2cd67d97aede6980dfc0dfea90a00647fd39f6428459a820fd078809147.png
diff --git a/...ml/_images/ac99bfa573fced861e8c64a8641ff4621e879cafff89c1082a13d55a64e506d6.png b/...ml/_images/ac99bfa573fced861e8c64a8641ff4621e879cafff89c1082a13d55a64e506d6.png
diff --git a/...ml/_images/c33d27ce8286995c53cd6a7a98836cadf5656d37f278b032aebe6842729ea3f7.png b/...ml/_images/c33d27ce8286995c53cd6a7a98836cadf5656d37f278b032aebe6842729ea3f7.png
diff --git a/...ml/_images/c95cfd82d0a7db3db68f4105f9a6b9452a5d98606745711b11a9f9a91cc1ebfe.png b/...ml/_images/c95cfd82d0a7db3db68f4105f9a6b9452a5d98606745711b11a9f9a91cc1ebfe.png
diff --git a/...ml/_images/cb9d014d5019323a6c8df2f4490e4989b92f057d56da3fa55630e9f4c66c6e19.png b/...ml/_images/cb9d014d5019323a6c8df2f4490e4989b92f057d56da3fa55630e9f4c66c6e19.png
diff --git a/...ml/_images/d11b5c10fdf30ee12f0ac9bf62662279b20b939402bac51e4535d3c62221aa56.png b/...ml/_images/d11b5c10fdf30ee12f0ac9bf62662279b20b939402bac51e4535d3c62221aa56.png
diff --git a/...ml/_images/e57f23067cf79892be4203eaa502885c230fbc5fa7ceab708c80dfa868fec69f.png b/...ml/_images/e57f23067cf79892be4203eaa502885c230fbc5fa7ceab708c80dfa868fec69f.png
diff --git a/...ml/_images/e61f45f76bc238b5b30c279753d0ef2a9569dc5963df7686d832ee4c9f24eb31.png b/...ml/_images/e61f45f76bc238b5b30c279753d0ef2a9569dc5963df7686d832ee4c9f24eb31.png
diff --git a/doc/build/html/_sources/G2Gtutorial.rst.txt b/doc/build/html/_sources/G2Gtutorial.rst.txt
@@ -0,0 +1,11 @@
+
+.. _G2Gtutorial:
+Tutorial
+=======================================
+
+
+Load the reference and query datasets:
+
+
+
+
diff --git a/doc/build/html/_sources/index.rst.txt b/doc/build/html/_sources/index.rst.txt
@@ -0,0 +1,124 @@
+.. Genes2Genes documentation master file, created by
+   sphinx-quickstart on Wed Aug 16 09:01:25 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Genes2Genes
+=======================================
+
+**A framework for single-cell pseudotime trajectory alignment** 
+
+.. contents:: Contents
+
+Genes2Genes (G2G) is a new Python framework for aligning single-cell pseudotime trajectories of gene expression between any reference and query for a pairwise comparison such as:
+
+    * Organoid vs. Reference tissue
+    * Control vs. Treatment
+    * Healthy vs. Disease
+
+Trajectory alignment: What & Why?
+###########
+
+A single-cell trajectory describes the transcriptomic state of cells along some axis of progression (such as time), due to undergoing some dynamic process (e.g. cell differentiation, treatment response, or disease infection). Given an scRNA-seq profile, there are various tools available today to infer such trajectory by estimating a pseudo ordering of the cells along an axis, commonly referred to as 'pseudotime'. The pseudotime axis of a trajectory can be descritized to represent it as a sequence of discrete time points. Given two such discrete pseudotime sequences of two trajectories, a pairwise alignment between them defines a non-linear mapping between their time points. This mapping could have 1-to-1  matches as well as 1-to-many/many-to-1 matches (a.k.a warps) between the time points, while unmapping the time points which have significantly different transcriptomic states. Below is an example visualization of two cell differentiation trajectories. 
+
+
+.. image:: images/DocFigs1.png
+  :width: 600
+  :alt: What is trajectory alignment?
+  :align: center
+
+For two trajectories representing single lineages as above, G2G generates an **optimal pairwise trajectory alignment** that captures the matches and mismatches between their time points in sequential order, allowing a user to quantify the degree of similarity between them.
+
+.. image:: images/DocFigs1-1.png
+  :width: 600
+  :alt: Example mapping
+  :align: center
+| 
+G2G defines 5 different states of alignment between any two **R** and **Q** time points, corresponding to all possible match and mismatch states. They are: 1-to-1 match (``M``), 1-to-many match (``V``), many-to-1 match (``W``), insertion (``I``) and deletion (``D``). Here, ``I`` or ``D`` refer to a mismatched time point in Q or R, respectively. These states jointly cover the alignment states defined in classical dynamic time warping and biological sequence alignment. 
+
+.. image:: images/DocFigs1-3.png
+  :width: 600
+  :alt: 5 states of alignment
+  :align: center
+|
+Accordingly, we can describe any trajectory alignment as a 5-state alignment string. For example, the 5-state alignment string of the above illustrated trajectory alignment is:
+
+.. code-block:: 
+
+   IIIMMMWWWIIIDDDMMMIIIIDDDD
+
+This G2G alignment string enables us to identify the time regions of match and mismatch along the trajectories. For instance, we can interpret the above illustrated alignment as follow -- *R and Q trajectories have mid and late mismatches, with the early stage of Q being mismatched, yet starting to match to the early stage of R at the middle of Q's trajectory. Overall, there are 9 R and Q pseudotime pairs getting matched (with 34.62% alignment similarity)*. 
+
+
+Outputs from Genes2Genes
+###########
+
+Given an scRNA-seq dataset with their pseudotime estimates and a specified set of genes (e.g. all transcription factors, highly variable genes, biological/signaling pathway genes), G2G generates fully-descriptive alignments for each gene (i.e. **gene-level alignment**), as well as an average (aggregate) alignment (i.e. **cell-level alignment**) across all genes. 
+
+Below is an example gene-level alignment of the gene *JUNB* in T cell differentiation between a pan-fetal reference and an artificial thymic organoid system:
+
+.. image:: images/DocFigs2.png
+  :width: 600
+  :alt: Example gene-level alignment?
+  :align: center
+|
+.. code-block:: 
+
+    IIIIIDMMMMMMMMIDDDDD 
+
+Each gene-level alignment carries its 5-state string, an alignment similarity percentage statistic,  and the optimal alignment cost (in *nits* -- the unit measure of information). For the above gene, the aligment similarity is 40%, and the total cost of alignment is 53.47 nits. When the degree of difference in gene expression  between the reference and query  is high, the alignment cost will also be high. 
+
+G2G uses the inferred gene-level alignments to inform:
+
+#. **The degree of similarity between the two profiles** as an average percentage of alignment similarity across all the genes tested,
+#. **An aggregate cell-level alignment across all genes** to inform the average states of match and mismatch between the two profiles (again represented by a 5-state string),  
+#. **A ranked list of genes across time (from the most distant to most similar)** based on their alignment similarity percentage statistic,
+#. **The diversity of different alignment patterns in genes**, by clustering gene-level alignments to identify different matching and mismatching patterns along time,
+
+between the two single-cell reference and query profiles in comparison. 
+
+For further downstream analysis, G2G provides a wrapper function to check gene-set overrepresentation analysis of the identified gene-clusters and the list of the top distant (differentially-expressed) genes across time, using  `GSEApy <https://github.com/zqfang/GSEApy>`_ Enrichr interface. The user is also able to compute an average alignment across any gene subset of their interest.
+
+**Note**: G2G has been developed only for single-lineage trajectory comparison. In the case of a trajectory with multiple branches, we recommend separating out the singe-lineage branches before any pairwise comparison.
+
+Our approach to trajectory alignment
+###########
+
+We employ a **dynamic programming** (DP) based algorithm that can capture both matches and mismatches in gene expression in a unified way. This combines the classical **Gotoh's algorithm** for biological sequence alignment with **dynamic time warping**. Our DP algorithm uses a **Bayesian information-theoretic scoring scheme** based on the **minimum message length** criterion to generate an optimal alignment between two gene trajectories. This scheme  evaluates the distributional similarity of gene expression between R and Q for each pair of time points, in terms of both their mean and variance of expression modelled as Gaussian distributions.
+For more details on the methods, please see our `manuscript <https://doi.org/10.1101/2023.03.08.531713>`_. 
+
+Getting started
+===========
+
+For now, G2G needs to be installed from GitHub:
+
+.. code-block:: shell
+
+   pip install git+https://github.com/Teichlab/Genes2Genes.git
+   
+The package will be made available soon on PyPi. 
+
+**Input to Gene2Genes**
+
+G2G takes reference and query input data as ``anndata`` objects, where each ``adata`` object has:
+
+* log1p normalised gene expression stored at ``adata.X`` 
+* pseudotime estimates of the cells stored as ``adata.obs['time']``
+
+The user can estimate pseudotime of the cells in their datasets  using any suitable method available (such as `Diffusion pseudotime <https://scanpy.readthedocs.io/en/stable/generated/scanpy.tl.dpt.html>`_, `Palantir <https://github.com/dpeerlab/Palantir>`_,  `GPLVM <https://pyro.ai/examples/gplvm.html>`_,  `Monocle <http://cole-trapnell-lab.github.io/monocle-release/>`_ etc.).
+For better visualisation and interpretation of the alignment results, we recommend the data to be annotated with their cell types (manually and/or using an automatic annotation tool such as `CellTypist <https://www.celltypist.org>`_). 
+
+Please refer to our :doc:`G2Gtutorial` for an example analysis between a reference and query dataset from literature.
+
+Citing Genes2Genes
+===========
+Our manuscript is currently available as a `preprint <https://doi.org/10.1101/2023.03.08.531713>`_ at bioRxiv: 
+
+*Sumanaweera, D., Suo, C., Cujba, A.M., Muraro, D., Dann, E., Polanski, K., Steemers, A.S., Lee, W., Oliver, A.J., Park, J.E. and Meyer, K.B., 2023.* **Gene-level alignment of single cell trajectories informs the progression of in vitro T cell differentiation**. *bioRxiv, pp.2023-03.*
+
+
+.. toctree::
+   :hidden:
+
+   self
+   ../notebooks/Tutorial
diff --git a/doc/build/html/_sources/notebooks/G2G_Tutorial.ipynb.txt b/doc/build/html/_sources/notebooks/G2G_Tutorial.ipynb.txt