diff --git a/README.md b/README.md index ad01b38..5462750 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,66 @@ # Cell BLAST -An accurate and robust solution to large-scale cell querying +Cell BLAST is a cell querying tool for single-cell transcriptomics data. + +For each query cell, it searches for most similar cells in the reference database. +Annotations in reference cells, e.g. cell type, can then be transfered to query +cells based on cell-to-cell similarities. See our +[preprint](https://www.biorxiv.org/content/10.1101/587360v1) for details. + +![flowchart](doc/_static/flowchart.png) + +## Installing the python package + +We only support installation via pip right now. + +Installation within virtual environments are recommended, see +[virtualenv](https://virtualenv.pypa.io/en/latest/) or +[conda](https://conda.io/docs/user-guide/tasks/manage-environments.html). + +For conda, here's a one-liner to set up an empty environment +for installing Cell BLAST: + +`conda create -n cb python=3.6 && source activate cb` + +Now follow the instructions below to install Cell BLAST: + +1. Make sure you have a working version of tensorflow or tensorflow-gpu + (version >= 1.5). You can follow the + [official instructions](https://www.tensorflow.org/install/) + about how to install tensorflow (and dependencies like CUDA and CuDNN + for the GPU version), or just install via anaconda, which handles + dependencies automatically: + + For installing the GPU supported version: + `conda install tensorflow-gpu=1.8` + + For installing the CPU only version: + `conda install tensorflow=1.8` + +2. Install Cell BLAST by running: + `pip install Cell-BLAST` + +3. Check if the package can be imported in python interpreter: + `import Cell_BLAST as cb` + +Online documentation can be found [here](http://cblast.gao-lab.org/doc/index.html). + +## Web-based interface + +We also provide a [Web-based service](http://cblast.gao-lab.org/) for +off-the-shelf querying of our ACA reference panels. + +## Repository structure + +* The `Cell_BLAST` directory contains the Cell BLAST python package. +* The `Datasets` directory contains scripts used for building the ACA database. +* The `Evaluation` directory contains scripts used for benchmarking + and producing some figures of the manuscript. +* The `doc` directory contains files used to generate the online documentation. +* The `test` directory contains unit tests for the python package. + +## Contact + +Feel free to submit an issue or contact us at +[cblast@mail.cbi.pku.edu.cn](mailto:cblast@mail.cbi.pku.edu.cn) +for problems about the python package, website or database. diff --git a/doc/_static/flowchart.png b/doc/_static/flowchart.png new file mode 100644 index 0000000..0e010c4 Binary files /dev/null and b/doc/_static/flowchart.png differ diff --git a/doc/index.rst b/doc/index.rst index 93423b8..56ba5fe 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -7,18 +7,14 @@ Welcome to Cell BLAST's documentation! ====================================== **Cell_BLAST** is a single cell transcriptome querying tool, based on -a deep learning model, **DIRECTi**, which supports: +a deep generative model (currently named **DIRECTi**). -* Learning low dimensional cell embedding with intrinsic data clustering -* Semi-supervision -* Removal of batch effect / systematical bias - -**Cell_BLAST** then performs query based on parametric cell embeddings from -**DIRECTi**, using posterior distribution distances. - -Information like cell type annotation can then be transferred from reference -to query data based on Cell BLAST hits. +**Cell_BLAST** performs querying based on parametric cell embeddings from +**DIRECTi**, using posterior distribution distances. Information like cell type +annotation can then be transferred from reference to query data based on +Cell BLAST hits. +.. image:: _static/flowchart.png Contents ======== diff --git a/doc/install.rst b/doc/install.rst index 3856af4..bb32f2b 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -3,35 +3,36 @@ Installation Guide ================== -We only support installation with local archive right now. +We only support installation via pip right now. Installation within virtual environments are recommended, see https://virtualenv.pypa.io/en/latest/ or https://conda.io/docs/user-guide/tasks/manage-environments.html. For conda, here's a one-liner to set up an empty environment -for ``Cell_BLAST``: +for installing Cell BLAST: -``conda create -n cb -c anaconda python=3.6 && source activate cb`` +``conda create -n cb python=3.6 && source activate cb`` -Now follow the instructions below to install ``Cell_BLAST``: +Now follow the instructions below to install Cell BLAST: 1. Make sure you have a working version of tensorflow or tensorflow-gpu (version >= 1.5). You can follow the instructions on https://www.tensorflow.org/install/ about how to install tensorflow (and dependencies like CUDA and CuDNN for the GPU version), or just install - via the conda, which handles dependencies automatically: + via anaconda, which handles dependencies automatically: For installing the GPU supported version: - ``conda install -c anaconda tensorflow-gpu=1.8`` + ``conda install tensorflow-gpu=1.8`` For installing the CPU only version: - ``conda install -c anaconda tensorflow=1.8`` + ``conda install tensorflow=1.8`` -2. Download latest Cell_BLAST release from: - https://github.com/gao-lab/Cell_BLAST/releases/. +2. Install Cell BLAST by running: + ``pip install Cell-BLAST``. -3. Install by ``pip install Cell_BLAST-.tar.gz`` +3. Check if the package can be imported in python interpreter: + ``import Cell_BLAST as cb`` And you are good to go. diff --git a/test/.gitignore b/test/.gitignore new file mode 100644 index 0000000..4a3c2f1 --- /dev/null +++ b/test/.gitignore @@ -0,0 +1 @@ +!pollen.h5 diff --git a/test/pollen.h5 b/test/pollen.h5 new file mode 100644 index 0000000..fa05ce7 Binary files /dev/null and b/test/pollen.h5 differ