SingleCellFusion is a computational tool to integrate single-cell transcriptome and epigenome datasets. Code in this repository is used in Luo et al., (2019) BioRxiv and in Yao et al., (2020) BioRxiv. Here is a brief description of how SingleCellFusion works.
Related publications:
- Luo, C. et al. Single nucleus multi-omics links human cortical cell regulatory genome diversity to disease risk variants. bioRxiv 2019.12.11.873398 (2019) doi:10.1101/2019.12.11.873398
- Yao, Z. et al. An integrated transcriptomic and epigenomic atlas of mouse primary motor cortex cell types. bioRxiv 2020.02.29.970558 (2020) doi:10.1101/2020.02.29.970558
- BRAIN Initiative Cell Census Network (BICCN) et al. A multimodal cell census and atlas of the mammalian primary motor cortex. bioRxiv 2020.10.19.343129 (2020) doi:10.1101/2020.10.19.343129
Code contributors: Fangming Xie, Aditya Chandrasekar, Wayne I. Doyle, Ethan Armand
Contact: Eran Mukamel
Step 1: Clone this repo.
git clone https://github.com/mukamel-lab/SingleCellFusion.git
cd SingleCellFusionTBD Step 2: Set up a conda environment and install dependent packages. The environment should be installed on the UNIX terminal(Skip this step if not needed.)
conda env create -f environment.yml # create an env named scf_terra
source activate scf_terrausage: SingleCellFusion [-h] -i xx.h5ad [xx.h5ad ...] -im rna/atac/mc [rna/atac/mc ...]
-f xx.h5ad [xx.h5ad ...] [-o DIR] [-op OUTPUT_PREFIX]
[--nearest_neighbors NEAREST_NEIGHBORS] [--relaxation RELAXATION]
[--num_pcs NUM_PCS] [--smoothing_fractions SMOOTHING_FRACTIONS]
[--leiden_n_neighbors LEIDEN_N_NEIGHBORS] [--leiden_resolutions LEIDEN_RESOLUTIONS]
[--umap_n_neighbors UMAP_N_NEIGHBORS] [--umap_min_dist UMAP_MIN_DIST]
SingleCellFusion is a computational tool to integrate single-cell transcriptome and epigenome datasets.
optional arguments:
-h, --help show this help message and exit
required:
-i xx.h5ad [xx.h5ad ...], --input_datasets xx.h5ad [xx.h5ad ...]
(list of str) Paths to .h5ad files, each containing a cell-by-gene feature matrix,
cell IDs and gene IDs. Cell IDs should be unique within each .h5ad file, Gene IDs
should be shared or partially shared across files. Multiple inputs should be listed
as a space seperated list of filenames. (default: None)
-im rna/atac/mc [rna/atac/mc ...], --input_modalities rna/atac/mc [rna/atac/mc ...]
(list of str) Data modalities chosen from 'rna', 'atac', or 'mc'. This should be
listed in the same order as input_datasets. (default: None)
-f xx.h5ad [xx.h5ad ...], --feature_datasets xx.h5ad [xx.h5ad ...]
(list of str) Dataset(s) whose features all other datasets will impute into. This
should be a subset of --input_datasets. Enter multiple datasets as a space-separated
list of filenames. The features of these datasets will be the features kept in the
output imputed data table." (default: None)
optional:
-o DIR, --output_dir DIR
(str) Directory to store output files (default: ./results)
-op OUTPUT_PREFIX, --output_prefix OUTPUT_PREFIX
(str) The output files will contain this prefix. (default: SingleCellFusion)
--nearest_neighbors NEAREST_NEIGHBORS
(integer) Number of nearest neighbors used to impute data (default: 20)
--relaxation RELAXATION
(float) A value between 1 to infinity. This is a parameter that constraints the
number of neighbors a cell is allowed to receive. Assume dataset 1 has N1 cells,
dataset 2 has N2 cells. To find k neighbors in dataset 2 for every cell in dataset 1
means on average each cell in dataset 2 receives (kN1/N2) connections. However, not
all cells in dataset 2 gets the same number of connections. We therefore set an upper
bound for the number of connections a cell in dataset 2 can receive to be:
(kN1/N2)*relaxation where relaxation >= 1. Relaxation=1 enforces a hard limit that
every cell receives the same number of nearest neighbors, while relaxation=infinity
approaches traditional kNN. (default: 3)
advanced:
--num_pcs NUM_PCS (integer) Number of Principal Components to keep for each dataset for smoothing
and for clustering/embedding after imputation. (default: 50)
--smoothing_fractions SMOOTHING_FRACTIONS
(list of floats) A list of three values between 0 to 1 that controls the relative
contribution from the cell itself vs. its neighbors in within-dataset smoothing,
specified for 'rna', 'atac', 'mc' data, respectively. (default: [0.7, 0.1, 0.9])
--leiden_n_neighbors LEIDEN_N_NEIGHBORS
(integer) Number of nearest neighbors to form in the integrated space, the resulting
nearest neighbor graph is used for Leiden clustering. It is passed into the python
package leidenalg.
(default: 30)
--leiden_resolutions LEIDEN_RESOLUTIONS
(list of floats) A list of resolutions to be used for Leiden Clustering. It is
passed into the python package leidenalg. (default: [0.1, 0.2, 0.4, 0.8])
--umap_n_neighbors UMAP_N_NEIGHBORS
(integer) Number of neighbors for UMAP. It is passed into the python package
umap.UMAP(n_neighbors). (default: 60)
--umap_min_dist UMAP_MIN_DIST
(float) Minimum distance for UMAP. It is passed into the python package
umap.UMAP(min_dist). (default: 0.5)
Contributors: Fangming Xie, Aditya Chandrasekar, Wayne I. Doyle, Ethan J. Armand, Eran Mukamel.
Contact: Eran Mukamel (emukamel@ucsd.edu).
./example-MOp-L5ET contains an example of integrating the layer 5 Extratelencephalically Projecting neurons (L5 ET) from 4 different datasets from the mouse primary motor cortex. The example directory includes the organized datasets, code, and results, which could be used as a template for other similar tasks.
After SingleCellFusion on the example data with run_scf.sh in example-MOp_L5ET (which is a call to SingleCellFusion with default parameters), the notebook ./example-MOp_L5ET/visualize_results.ipynb provides a step-by-step walkthrough of manipulating and plotting the integrated data. The plots created are shown below, and all the required code to generate them is included in the notebook.
cd ./example-MOp_L5ET
# shell script to run SingleCellFusion using example parameters
./run_scf.sh
# visualize results
jupyter notebook visualize_results.ipynb
More example datasets, and prepared ./run_scf.sh files are included in the repository to play around with.
SingleCellFusion integrates our modalities and embeds the integrated space into common UMAP coordinates. We want to plot these UMAP coordinates, coloring each data point to get a rough view of how integrated the modalities are.
For our Top Panel, we plot the integrated UMAP space, coloring each point with the colors of each integrated modality.
For the Bottom Panels, we plot the integrated UMAP space by each of the joint clusters found. Each plot corresponds to a separate clustering resolution, set when calling SingleCellFusion.
In order to ensure that each cluster has a similar composition of all of the datasets, we plot the dataset compositions of each Joint Cluster in a bar chart.
Each bar corresponds to a different cluster found in our Joint Clustering, colored by the original datasets. To check that each cluster has a relatively even composition of each dataset, we plot the overall composition of datasets next to our bar charts for comparison.
To ensure that SingleCellFusion does not cluster cells by their source dataset, we want the composition of each cluster to be as close to the overall composition of the data as possible (defined by the sizes of the original modalities).
SingleCellFusion integrates our modalities and embeds the integrated space into common UMAP coordinates. We want to show that our integration does not segregate our cells by modality, and rather integrates them by other expression-level features.
To do this, we plot each modality separately on the same UMAP space and check that each modality is evenly distributed across the space.
To see how the original clusters from individual modalities are preserved in the integrated clustering, we display the original cell-type annotations of individual datasets in our integrated space.
For the given example, we will focus on displaying L5 PT (L5 ET or its equivalent annotation) cells. The majority of the cells in our example are labeled as L5 PT/ET in each individual dataset's clusters, with a few exceptions.
To continue investigating how the original clusters from individual modalities are maintained in the integrated clusters, we can plot a confusion matrix showing how the clusters of individual datasets are re-organized into new integrated clusters.
The rows of each confusion matrix shows the cluster labels for the individual dataset. If no such cluster labels exist, a single column is shown, so we can still examine the distribution of cells in the Joint Clusters.
The y-axis shows the three clusters identified in the integrated dataset.
The Confusion Matrices on the first row are all Normalized by Joint Clusters (the Sum of each Row is 1).
The Confusion Matrices on the second row are all Normalized by Original Clusters (the Sum of each Row is 1).
