update README

.gitignore

@@ -0,0 +1 @@
+.DS_Store

README.md

@@ -24,15 +24,15 @@ We implemented MARS model in a self-contained class. To make an instance and tra
 mars = MARS(n_clusters, params, labeled_exp, unlabeled_exp, pretrain_data)
 adata, landmarks, scores = mars.train(evaluation_mode=True)
 ```
-In the evaluation_mode labeles for unlabeled experiment are provided which MARS uses to compute clustering metrics and evaluate the model. Otherwise, MARS just provides predictions for the unlabeled experiment. MARS stores all embeddings (for labeled and unlabeled data), as well as predictions in anndata object.
+MARS provides annotations for the unlabeled experimentm as well as embeddings for annotated and unannotated experiments, and stores them in anndata object. In the evaluation_mode annotations for unlabeled experiment need to be provided, and they are used to compute metrics and evaluate the performance of the model. 
 
-Performance of MARS on the Tabula Muris data:
+MARS embeddings can be visualized in the 2D space using UMAP or tSNE. Example embeddings for diaphragm and liver tissues:
 
 <p align="center">
-<img src="https://github.com/mbrbic/mars/blob/master/images/MARS_performance.png" width="400" align="center">
+<img src="https://github.com/mbrbic/mars/blob/master/images/MARS_embeddings.png" width="400" align="center">
 </p>
 
-MARS can also produce interpretable names for discovered clusters by calling:
+MARS can generate interpretable names for discovered clusters by calling:
 ```
 mars.name_cell_types(adata, landmarks, cell_type_name_map)
 ```
@@ -43,16 +43,22 @@ Example of the MARS naming approach:
 <img src="https://github.com/mbrbic/mars/blob/master/images/MARS_naming.png" width="600" align="center">
 </p>
 
-Example of running MARS on Tabula Muris dataset in leave-one-tissue-out manner is provided in the main.py.
+Example of running MARS on Tabula Muris dataset in leave-one-tissue-out manner is provided in the [main_TM.py](https://github.com/snap-stanford/mars/blob/master/main_TM.py). We also provide two example notebooks that illustrate MARS on small-scale datasets:
+- [cellbench.ipynb](https://github.com/snap-stanford/mars/blob/master/notebooks/cellbench.ipynb) demonstrates MARS on two CellBench dataset of five sorted lung cancer cell lines sequenced with 10Xand CEL-Seq2 protocols. 
+- [kolod_pollen_bench.ipynb](https://github.com/snap-stanford/mars/blob/master/notebooks/kolod_pollen_bench.ipynb) demonstrates MARS on [Pollen](https://pubmed.ncbi.nlm.nih.gov/25086649/) dataset of diverse human cell types, and [Kolodziejczyk](http://www.ncbi.nlm.nih.gov/pmc/articles/PMC4595712/ dataset of mouse pluripotent cells.
 
+## Cross-validation benchmark
+
+We provide cross-validation benchmark [cross_tissue_generator.py](https://github.com/snap-stanford/mars/blob/master/cross_tissue_generator.py) for classifying cell types of Tabula Muris data. The iterator goes over cross-organ train/test splits with an auto-download of Tabula Muris data.
 
 ## Datasets
 
-Tabula Muris Senis datasets used in our study can be downloaded from [https://figshare.com/projects/Tabula\_Muris\_Senis/64982](https://figshare.com/projects/Tabula\_Muris\_Senis/64982).
+Tabula Muris Senis datasets is from [https://figshare.com/projects/Tabula\_Muris\_Senis/64982](https://figshare.com/projects/Tabula\_Muris\_Senis/64982).
 
-Dataset in h5ad format can be downladed from [http://snap.stanford.edu/mars/data/tms-facs-mars.tar.gz](http://snap.stanford.edu/mars/data/tms-facs-mars.tar.gz).
+Tabula Muris Senis dataset in h5ad format can be downladed at [http://snap.stanford.edu/mars/data/tms-facs-mars.tar.gz](http://snap.stanford.edu/mars/data/tms-facs-mars.tar.gz).
+Small-scale example datasets CellBench and Kolodziejczyk/Pollen can be downloaded at [https://github.com/snap-stanford/mars/blob/master/benchmark_datasets/cellbench_kolod_pollen.tgz](https://github.com/snap-stanford/mars/blob/master/benchmark_datasets/cellbench_kolod_pollen.tgz).
 
-Saved models for each tissue in Tabula Muris can be downladed from [http://snap.stanford.edu/mars/data/TM_trained_models.tar.gz](http://snap.stanford.edu/mars/data/TM_trained_models.tar.gz).
+Trained models for each tissue in Tabula Muris can be downladed from [http://snap.stanford.edu/mars/data/TM_trained_models.tar.gz](http://snap.stanford.edu/mars/data/TM_trained_models.tar.gz).
 
 ## Contact
 Please contact Maria Brbic at [email protected] for questions.