Package: scmomat
scMoMaT: a unified framework for single cell mosaic integration and multi-modal bio-marker detectionscMoMaT v0.2.0DescriptionscMoMaT is a single-cell data integration method that is able to:integrate single cell multi-omics data under the mosaic scenario using matrix tri-factorizationuncover the cell type specific bio-markers at the same time when learning a unified cell representationintegrate cell batches with unequal cell type compositionDependencyPython >= 3.8.10
numpy >= 1.19.5
torch >= 1.11.0
scipy >= 1.7.3
sklearn >= 0.22.1
matplotlib >= 3.5.2
umap >= 0.5.2
leidenalg >= 0.9.1
pandas >= 1.4.0
adjustText >= 0.7.3 (optional)Directorysrccontains the main script of scMoMaTtestcontains the testing script of scMoMaT on the datasets in the manuscript and running script of baseline methods. Please refer to this folder for the reproduction of test results. The testing dataset is available upon request.datastores the datasetsDataNecessary data for PBMC (the first real dataset in the manuscript,ASAP-PBMC) and MOp (the second real dataset in the manuscript,MOp_5batches) are provided, which should be suffice for the running of scMoMaT indemo_pbmc.pyanddemo_mop_5batches.pyas examples. The dataset for the other demo scrips are available upon requests.InstallationInstall the package withpip install scmomatOr install the latest version by cloning the repository withgit clone https://github.com/PeterZZQ/scMoMaT.gitEnter the root directory of the packagecd scMoMaTAnd runpip install .Uninstall usingpip uninstall scmomatUsageTraining pipeline of scMoMaTData objectcountMake sure that the dataset get stored in the dictionary, and save the value to each key:
*nbatches: total number of batches
*feats_name: a dictionary storing the feature names for different modalities, e.g.{"rna": np.array([aaaa, bbbb,...]), "atac": np.array([ccc, ddd, ...]), "protein": np.array([eee, fff, ...])}*modality 1(e.g.rnain the example below): aliststore all data matrices correspond to modality 1, a element correspond to one batch, elements are ordered in the list following the ordering of batches.The batches that does not have count matrix in corresponding modality is insertedNoneas placeholder*modality 2(e.g.atacin the example below): requirement the same as above.
*modality 3(e.g.protein): requirement the same as above.
* ...Checkdemo_scmomat.ipynbfor an example. Note:
* The number of item in thefeats_nameshould match the number of modalities incounts.
* The length of lists inmodality 1,modality 2,modality 3, etc should have the same length, which is equal tonbatches. (missing matrices are denoted asNoneas explained above).The matrices must be ordered according to the batch ID in each list,so that scMoMaT can detact parallel sequenced batches.
* The data matrix in each modality (each list) should have the same set of features. You can do thie by 1. using the intersection of all genes/proteins in different batches; 2. Remap the chromatin regions according to the peaks of one batch.
* The data matrix is of the shape(ncells, nfeatures), and preprocessed withutils.preprocess()function.One example template is shown as below, note that the features of data matrices are matched in advance. The connection matrix (GxR.npz) that is used to generate pseudo-count is also provided in advance (used the code in foldercalc_pseudo_count/calc_pseudo_count.R). Feel free to modify on the template to use your dataset.First training stageimportscmomat# training device: CPU or GPUdevice=torch.device("cuda:1"iftorch.cuda.is_available()else"cpu")# number of latent dimensions (20~30)K=30# number of iterationsT=4000# [Optional] parameter lambda is set to be the default value 0.001# 1st stage training, learning cell factorsmodel=scmomat.scmomat_model(counts=counts,K=K,device=device)losses=model.train_func(T=T)# extract cell factorszs=model.extract_cell_factors()Cell factor post-processing# post-processing# neighborhood size (30~50)n_neighbors=30# [Optional] neighborhood radius (between 0 and 1)r=None# number of parallel CPU for calculation, default 1njobs=8# obtain post-processed graphs_pair_dist,knn_indices,knn_dists=scmomat.post_process(zs,n_neighbors,njobs=8,r=r)Cluster and retraining# cluster with post-processed graph# cluster resolutionresolution=0.9labels_leiden=scmomat.leiden_cluster(X=None,knn_indices=knn_indices,knn_dists=knn_dists,resolution=resolution)# visualize graph with umapumap_op=scmomat.UMAP(n_components=2,n_neighbors=n_neighbors,min_dist=0.20,random_state=0,metric='precomputed',knn_dists=knn_dists,knn_indices=knn_indices)x_umap=umap_op.fit_transform(s_pair_dist)scmomat.plot_latent(x_umap,annos=labels_leiden,mode="joint",save=None,figsize=(10,7),axis_label="UMAP",markerscale=6,s=5,label_inplace=True,alpha=0.7)# 2nd stage training with cluster result, obtained feature factors# [Optional] parameter lambda is set to be the default value 0.001# [Optional] Update counts to include more training modalities (motif)model2=scmomat.scmomat_retrain(model=model,counts=counts,labels=labels_leiden,device=device)# number of iteractions is 2000losses=model2.train(T=2000)# extract marker scoresscore_feats=model2.extract_feature_factors()ExamplesThe above example shows the key steps in scmomat, which does not include the ploting function.demo_scmomat.ipynbprovides a detailed example run onMOp_5batchesdataset (running time: training procedure takes ~5mins on NVIDIA A40 GPU, total file takes ~30mins).For more example, please see the test scripts intestfolder, necessary comments are included:test_pbmc.py: The first real dataset in the manuscript (data provided).test_bmmc_healthy.py: The third real dataset in the maunscript.test_spleen.py: The fourth real dataset in the manuscript.test_spleen_subsample.py: The fourth real dataset in the manuscript.test_mop_5batches.py: The second real dataset in the manuscript.ContactZiqi Zhang:ziqi.zhang@gatech.eduXiuwei Zhang:xiuwei.zhang@gatech.eduCite@article{zhang2022scmomat,
  title={scMoMaT: Mosaic integration of single cell multi-omics matrices using matrix trifactorization},
  author={Zhang, Ziqi and Sun, Haoran and Chen, Xinyu and Mariappan, Ragunathan and Chen, Xi and Jain, Mika and Efremova, Mirjana and Rajan, Vaibhav and Teichmann, Sarah and Zhang, Xiuwei},
  journal={bioRxiv},
  year={2022},
  publisher={Cold Spring Harbor Laboratory},
}