--- a
+++ b/README.md
@@ -0,0 +1,82 @@
+# scMDC
+Single Cell Multi-omics deep clustering (**scMDC v1.0.1**)
+
+We develop a novel multimodal deep learning method, scMDC, for single-cell multi-omics data clustering analysis. scMDC is an end-to-end deep model that explicitly characterizes different data sources and jointly learns latent features of deep embedding for clustering analysis. Extensive simulation and real-data experiments reveal that scMDC outperforms existing single-cell single-modal and multimodal clustering methods on different single-cell multimodal datasets. The linear scalability of running time makes scMDC a promising method for analyzing large multimodal datasets.
+
+## Table of contents
+- [Network diagram](#diagram)
+- [Dependencies](#Dependencies)
+- [Usage](#Usage)
+- [Output](#Output)
+- [Arguments](#Arguments)
+- [Citation](#Citation)
+- [Contact](#contact)
+
+## <a name="diagram"></a>Network diagram
+![Model structure](https://github.com/xianglin226/scMDC/blob/master/src/fig1_.png?raw=true)  
+
+## <a name="Dependencies"></a>Dependencies
+Python 3.8.1
+
+Pytorch 1.6.0
+
+Scanpy 1.6.0
+
+SKlearn 0.22.1
+
+Numpy 1.18.1
+
+h5py 2.9.0  
+
+All experiments of scMDC in this study are conducted on Nvidia Tesla P100 (16G) GPU.
+We suggest to install the dependencies in a conda environment (conda create -n scMDC).  
+It takes few minutes to install the dependencies.  
+scMDC takes about 3 minutes to cluster a dataset with 5000 cells.  
+
+## <a name="Usage"></a>Usage  
+1) Prepare the input data in h5 format. (See readme in 'dataset' folder)  
+2) Run scMDC according to the running script in "script" folder (Note the parameter settings if you work on mRNA+ATAC data and use run_scMDC_batch.py for multi-batch data clustering)  
+3) Run DE analysis by run_LRP.py based on the well-trained scMDC model (refer the LRP running script in "script" folder)  
+
+## <a name="Output"></a>Output  
+1) scMDC outputs a latent representation of data which can be used for further downstream analyses and visualized by t-SNE or Umap; 
+2) Multi-batch scMDC outputs a latent representation of integrated datasets on which the batch effects are corrected.  
+3) LRP outputs a gene rank which indicates the importances of genes for a given cluster and can be used for pathway analysis.  
+
+## <a name="Arguments"></a>Arguments
+--n_clusters: number of clusters (K); scMDC will estimate K if this arguments is set to -1.  
+--cutoff: A ratio of epoch before which the model only train the low-level autoencoders.   
+--batch_size: batch size.  
+--data_file: path to the data input.  
+Data format: H5.  
+Structure: X1(RNA), X2(ADT or ATAC), Y(label, if exit), Batch (Batch indicator for multi-batch data clustering).  
+--maxiter: maximum epochs of training. Default: 10000.  
+--pretrain_epochs: number of epochs for pre-training. Default: 400.  
+--gamma: coefficient of clustering loss. Default: 0.1.  
+--phi1 and phi2: coefficient of KL loss in pretraining and clustering stage. Default: 0.001 for CITE-Seq; 0.005 for SMAGE-Seq*.  
+--update_interval: the interval to check the performance. Default: 1.  
+--tol: the criterion to stop the model, which is a percentage of changed labels. Default: 0.001.  
+--ae_weights: path of the weight file.  
+--save_dir: the directory to store the outputs.  
+--ae_weight_file: the directory to store the weights.  
+--resolution: the resolution parameter to estimate k. Default: 0.2.  
+--n_neighbors: the n_neighbors parameter to estimate K. Default: 30.  
+--embedding_file: if save embedding file. Default: No  
+--prediction_file: if save prediction file. Default: No  
+--encodeLayer: layers of the low-level encoder for RNA: Default: [256,64,32,16] for CITE-Seq; [256,128,64] for SMAGE-seq.  
+--decodeLayer1: layers of the low-level encoder for ADT: Default: [16,64,256] for CITE-Seq. [64,128,256] for SMAGE-seq.  
+--decodeLayer2: layers of the high-level encoder. Default:[16,20] for CITE-Seq. [64,128,256] for SMAGE-seq.  
+--sigma1: noise on RNA data. Default: 2.5.  
+--sigma2: noise on ADT data. Default: 1.5 for CITE-Seq; 2.5 for SMAGE-Seq  
+--filter1: if do feature selection on Genes. Default: No.  
+--filter2: if do feature selection on ATAC. Default: No.  
+--f1: Number of high variable genes (in X1) used for clustering if doing the featue selection. Default: 2000  
+--f2: Number of high variable genes from ATAC (in X2) used for clustering if doing the featue selection. Default: 2000  
+*We denote 10X Single-Cell Multiome ATAC + Gene Expression technology as SMAGE-seq for convenience.  
+
+
+## <a name="Citation"></a>Citation
+Lin, X., Tian, T., Wei, Z., & Hakonarson, H. (2022). Clustering of single-cell multi-omics data with a multimodal deep learning method. Nature Communications, 13(1), 1-18.
+
+## <a name="contact"></a>Contact
+Xiang Lin <xl456@njit.edu>