refine-docs

README.md

@@ -1,10 +1,10 @@
-stagewiseNN
+StagewiseNN
 ===========
 
 [//]: # (https://zenodo.org/badge/386473402.svg)
 [![DOI](https://zenodo.org/badge/386473402.svg)](https://zenodo.org/badge/latestdoi/386473402)
 
-**stagewiseNN** is a computational tool for constructing
+**StagewiseNN** is a computational tool for constructing
 developmental tree from Multi-staged single-cell RNA-seq data.
 
 (see [StagewiseNN Documentation ](https://xingyanliu.github.io/stagewiseNN/index.html) for detailed guides)
@@ -17,6 +17,19 @@ and adaptive cluster refinement.
 
 [//]: # (![StagewiseNN](docs/source/_figs/stagewisenn.png))
 
+The single-cell graph can be further visualized using graph embedding methods, e.g. UMAP, SPRING.
+
+We have used it to build the developmental tree from Amphioxus embryonic cells, across
+nine developmental stages ("B", "G3", "G4", "G5", "G6", "N0", "N1", "N3", "L0"),
+where seven major lineages were recognized.
+
+<img src="docs/source/_figs/umap_rna.png" height="180"/>
+
+StagewiseNN can also be applied on **scATAC-seq** data sampled at multiple timepoints,
+once the peak-by-cell matrix is transformed into the gene activities (i.e., a gene-by-cell matrix).
+
+<img src="docs/source/_figs/umap_atac.png" height="180"/>
+
 It is easy to use:
 
 ```python
@@ -29,14 +42,14 @@ import swnn
 # stage_order = [f'stage_{i}' for i in range(5)]
 
 builder = swnn.Builder(stage_order=stage_order)
-# step 1:
-# building (stage-wise) single-cell graph
+
+# step1: building a (stage-preserved) single-cell graph
 distmat, connect = builder.build_graph(
-        X=data_matrix, stage_lbs=stage_labels,
-    )
-# step 2:
-# build developmental tree from single-cell graph
-builder.build_tree(group_labels, stage_labels,)
+       X=data_matrix, stage_lbs=stage_labels,
+   )
+# step2: build a developmental tree from the single-cell graph
+edgedf, refined_group_lbs = builder.build_tree(group_labels, stage_labels,)
+
 ```
 
 

docs/_sources/index.rst.txt

@@ -1,33 +1,39 @@
-.. stagewiseNN documentation master file, created by
+.. StagewiseNN documentation master file, created by
    sphinx-quickstart on Mon Jul 19 12:54:30 2021.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-stagewiseNN - Building developmental tree from scRNA-seq
-========================================================
+StagewiseNN - Building developmental tree from single-cell data
+===============================================================
 
-**stagewiseNN** is a computational tool for constructing
+**StagewiseNN** is a computational tool for constructing
 developmental (lineage) tree from Multi-staged single-cell RNA-seq data.
 
 It starts from building a single-cell graph by connecting each cell to its
 k-nearest neighbors in the parent stage, followed by voting-based tree-construction
 and adaptive cluster refinement.
 
-.. image:: _figs/stagewisenn.png
+.. image:: _figs/swnn_overview.png
    :height: 250px
 
 The single-cell graph can be further visualized using graph embedding methods, e.g. UMAP, SPRING.
 
 We have used it to build the developmental tree from Amphioxus embryonic cells, across
-nine developmental stages ("B", "G3", "G4", "G5", "G6", "N0", "N1", "N3", "L0").
-And seven major lineages were recognized.
+nine developmental stages ("B", "G3", "G4", "G5", "G6", "N0", "N1", "N3", "L0"),
+where seven major lineages were recognized.
 
 .. image:: _figs/umap_stage.png
    :height: 200px
 
 .. image:: _figs/umap_lineage.png
    :height: 200px
 
+StagewiseNN can also be applied on **scATAC-seq** data sampled at multiple timepoints,
+once the peak-by-cell matrix is transformed into the gene activities (i.e., a gene-by-cell matrix).
+
+.. image:: _figs/umap_atac.png
+   :height: 200px
+
 Installation
 ------------
 
@@ -69,13 +75,12 @@ See :doc:`tutorial/tutorial_builder_based` for detailed guide.
    # stage_order = [f'stage_{i}' for i in range(5)]
 
    builder = swnn.Builder(stage_order=stage_order)
-   # step1:
-   # building (stage-wise) single-cell graph
+
+   # step1: building a (stage-preserved) single-cell graph
    distmat, connect = builder.build_graph(
            X=data_matrix, stage_lbs=stage_labels,
        )
-   # step2:
-   # build developmental tree from single-cell graph
+   # step2: build a developmental tree from the single-cell graph
    edgedf, refined_group_lbs = builder.build_tree(group_labels, stage_labels,)
 
 
@@ -97,14 +102,6 @@ We have a mailing list located at:
 * [email protected]
 * [email protected]
 
-Citation
---------
-
-If you find StagewiseNN helps, Please cite:
-
-   Pengcheng Ma, Xingyan Liu, Zaoxu Xu et al. **Joint profiling of gene expression and chromatin accessibility of amphioxus development at single cell resolution**, 18 May 2021, PREPRINT (Version 1) available at Research Square [https://doi.org/10.21203/rs.3.rs-504113/v1]
-
-
 
 .. toctree::
    :caption: Contents
@@ -116,8 +113,8 @@ If you find StagewiseNN helps, Please cite:
    citation
 
 
-Indices and tables
-==================
+Indices
+=======
 
 * :ref:`genindex`
-* :ref:`search`
+

docs/_sources/tutorial/tutorial_builder_based.ipynb.txt

@@ -50,6 +50,7 @@
    "source": [
     "ROOT = Path('../')  \n",
     "sys.path.append(str(ROOT))\n",
+    "\n",
     "import swnn\n",
     "from swnn import describe_dataframe, set_adata_hvgs, change_names"
    ]
@@ -78,19 +79,16 @@
     }
    ],
    "source": [
-    "DATADIR = ROOT / 'sample_data'\n",
-    "resdir = ROOT / '_temp'\n",
-    "swnn.check_dirs(resdir)\n",
-    "\n",
-    "path_adata = DATADIR / 'subsampled_B-L0-0.2.h5ad'"
+    "resdir = ROOT / '_temp'  # The result directory, reset by user!\n",
+    "swnn.check_dirs(resdir)"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "701b9472",
    "metadata": {},
    "source": [
-    "Load sample data (an ``AnnData`` object)"
+    "Load the sample data (as an ``AnnData`` object)"
    ]
   },
   {
@@ -113,6 +111,9 @@
     }
    ],
    "source": [
+    "DATADIR = ROOT / 'sample_data'                     # reset by user!\n",
+    "path_adata = DATADIR / 'subsampled_B-L0-0.2.h5ad'  # reset by user!\n",
+    "\n",
     "adata_raw = sc.read_h5ad(path_adata)\n",
     "adata_raw"
    ]
@@ -146,7 +147,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# way 1, most commonly adopted\n",
+    "# way 1, the most commonly adopted\n",
     "adata_norm = swnn.normalize_default(adata_raw, target_sum=None, copy=True, )"
    ]
   },
@@ -181,6 +182,14 @@
     "hvg_freq, hvg_dict = swnn.groupwise_hvgs_freq(adata, groupby='stage_name')"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "13ed9844",
+   "metadata": {},
+   "source": [
+    "Take the HVGs that are detected on more that 3 stages:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 9,
@@ -196,7 +205,7 @@
     }
    ],
    "source": [
-    "hvgs = swnn.take_high_freq_elements(hvg_freq, 3)\n",
+    "hvgs = swnn.take_high_freq_elements(hvg_freq, min_freq=3)\n",
     "print('Total of %d HVGs are used.' % len(hvgs))"
    ]
   },
@@ -207,13 +216,15 @@
    "source": [
     "**NOTE** \n",
     "\n",
-    "If you have already computed the HVG frequencies, you can directly load them, and take ones with high-frequencies.\n",
+    "* If you have already computed the HVG frequencies, you can directly load them, and take ones with high-frequencies.\n",
     "\n",
     "```python\n",
     "hvg_freq = pd.read_csv(path_hvg_freq, index_col=0, header=None).iloc[:, 0].to_dict()\n",
     "hvgs = swnn.take_high_freq_elements(hvg_freq, min_freq=3)\n",
     "```\n",
     "\n",
+    "\n",
+    "\n",
     "Next, set HVGs to ``adata``"
    ]
   },
@@ -275,7 +286,7 @@
    "source": [
     "## 2 The main process\n",
     "\n",
-    "### 2.0 Setting inputs and parameters"
+    "### 2.0 Setting inputs and the parameters"
    ]
   },
   {
@@ -323,7 +334,7 @@
    "id": "1495bc24",
    "metadata": {},
    "source": [
-    "### 2.1 Building (stage-wise) single-cell graph"
+    "### 2.1 Building a (stage-wise) single-cell graph"
    ]
   },
   {
@@ -440,7 +451,9 @@
    "id": "8cb78078",
    "metadata": {},
    "source": [
-    "### 2.2 Build developmental tree from single-cell graph"
+    "We can see that the UMAP-plot computed from the 20%-subsample is similar to that built from the full data.\n",
+    "\n",
+    "### 2.2 Build a developmental tree from the single-cell graph"
    ]
   },
   {
@@ -673,13 +686,27 @@
     "edgedf.head()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "64b5c80b",
+   "metadata": {},
+   "source": [
+    "The values in 'prop' column of `edgedf` is the voting proportions from 'node' to the most likely 'parent'."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "0be48081",
+   "id": "373f73f0",
    "metadata": {},
    "outputs": [],
-   "source": []
+   "source": [
+    "# save the results\n",
+    "edgedf.to_csv(resdir / 'edgedf.csv')\n",
+    "\n",
+    "# set the refined labels \n",
+    "adata.obs['refined_group'] = refined_group_lbs"
+   ]
   }
  ],
  "metadata": {

docs/api.html

@@ -228,8 +228,8 @@ <h2>Object for Management<a class="headerlink" href="#object-for-management" tit
 <col style="width: 90%" />
 </colgroup>
 <tbody>
-<tr class="row-odd"><td><p><a class="reference internal" href="generated/swnn.Builder.html#swnn.Builder" title="swnn.Builder"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Builder</span></code></a>(stage_order, **build_params)</p></td>
-<td><p></p></td>
+<tr class="row-odd"><td><p><a class="reference internal" href="generated/swnn.Builder.html#swnn.Builder" title="swnn.Builder"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Builder</span></code></a>(stage_order)</p></td>
+<td><p>The wrapper object for conveniently building both the single-cell graph and the coarse-grained tree.</p></td>
 </tr>
 </tbody>
 </table>