euxhenh / cellar

Interactive software tool for the assignment of cell types in single-cell studies.

Cellar is an interactive tool for analyzing single-cell omics data. Cellar is built in Python using the Dash framework and relies on several open-source packages.

The app is developed and actively maintained by the Systems Biology Group at Carnegie Mellon University. Our web-server running Cellar can be accessed here. See below for a local installation.

An accompanying paper and supplementary files can be accessed via Nature Communications.

The documentation includes details on how to use Cellar and the data types it supports. These include but are not limited to scRNA-seq, scATAC-seq, CODEX, SNARE-seq, sciRNA-seq, Visium. Cellar supports preprocessing, dimensionality reduction, clustering, DE gene testing, enrichment analysis, cluster and gene visualization modules, projection to spatial tiles, label transfer, and semi-supervised clustering among others. The documentation also contains several written tutorials. Video tutorials are also available.

Links

• Cellar Web Server: https://cellar.cmu.hubmapconsortium.org/app/cellar
• Official Source Code Repository: https://github.com/euxhenh/cellar
• Documentation & Tutorials: https://euxhenh.github.io/cellar/
• Video Tutorials: https://www.youtube.com/playlist?list=PL5sLSLkTYpWgfBQ0M8ObfBIqDMAzx0-D2
• Issue Tracker: https://github.com/euxhenh/cellar/issues
• Paper: https://www.nature.com/articles/s41467-022-29744-0
• DOI: https://zenodo.org/badge/latestdoi/372980254

Local Installation

Docker Installation

Probably the easiest way to install Cellar locally is using Docker. The image name is euxhen/cellar and can be pulled with:

docker pull euxhen/cellar

After the pull is complete, running Cellar is as simple as:

docker run --rm -p 8050:8050 euxhen/cellar

and visiting localhost:8050 on your web browser.

Manual Installation

A manual installation involves cloning the Cellar repository and installing the necessary Python and R packages. To run Cellar you will need at least Python 3.7 and R 4.0. We recommend using a Conda environment for installing the dependencies. For a full list of dependencies and installation instructions please refer to the documentation.

Citation

If you use Cellar in your work, we would appreciate citations to Cellar's paper

@article{Hasanaj2022,
    author = {Euxhen Hasanaj and Jingtao Wang and Arjun Sarathi and Jun Ding and Ziv Bar-Joseph},
    issn = {2041-1723},
    issue = {1},
    journal = {Nature Communications 2022 13:1},
    month = {4},
    pages = {1-6},
    publisher = {Nature Publishing Group},
    title = {Interactive single-cell data analysis using Cellar},
    volume = {13},
    year = {2022},
}

Contributing

We welcome code contributions as well as feature requests. To request new features please raise an issue in the links provided above or directly send us an email.

cellar's Issues

`dataset_dict` is static and doesn't track changes in the `DATA_PATH`

At the moment, uploading a new dataset to the DATA_PATH through command line (not through cellar UI) doesn't change the drop-down content in the dataset selector. So, every time I upload a dataset to the server, cellar needs to be restarted. One way to resolve it would be to update the drop-down content on every click to Load Data. Do you think it's a reasonable solution? I could make a PR to fix it.

Coloring by an arbitrary cell metadata column (enhancement)

To my understanding, currently there is no way to color the dataset by anything but cluster id. Having a color column selector would add a lot to usability. For example, adding a drop-down to the left of "Change Color Palette". Seems like a very easy fix. Do you plan adding such functionality? If it would help, I can submit a PR for that.

How to create a mirror with my own example data?

Hi,
It's an amazing job,and I want to create a mirror on my website with my example data.

May I ask how can I create a site mirror with default data?

It's like when you go to a website and show the content after click on "LOAD" to display .

Upload File

Hello.

Great Tool!
I could run Cellar in one of my samples, 10x data, worked great.
I still don't know the better way to upload the whole batch as one file to be analyzed.
Can you give a help with it?

Dataset upload support for multi-user environments

While using your public web-server, it looks like the uploaded datasets are not persistent. However, if I run an instance myself, they're simply stored in the uploaded sub-folder. Consequently, every user sees everything anyone uploads to the server. And in case of a name conflict, an older dataset gets overwritten without any warning. Is there any way to make these uploaded datasets temporary and user-specific?

Runs abnormally, no styles

Hello,
whether it is running locally with docker or running on the web, it is found that the website is not loaded correctly, and some styles are not displayed. What do I need to do to use it normally?

cellar crashes with "Illegal instruction" on non-AVX2 cpu [fix included]

Hi, and thanks for sharing your work!

We're running this at DUG Technology on behalf of a client and experiencing a crash when it runs on a machine that doesn't support AVX2. The failure mode looks something like this:

$ python -v main.py 
...
# code object from '/usr/local/conda/cellar/lib/python3.8/site-packages/faiss/__pycache__/swigfaiss.cpython-38.pyc'
# extension module 'faiss._swigfaiss' loaded from '/usr/local/conda/cellar/lib/python3.8/site-packages/faiss/_swigfaiss.so'
# extension module 'faiss._swigfaiss' executed from '/usr/local/conda/cellar/lib/python3.8/site-packages/faiss/_swigfaiss.so'
import 'faiss._swigfaiss' # <_frozen_importlib_external.ExtensionFileLoader object at 0x2b5e21c82b50>
import 'faiss.swigfaiss' # <_frozen_importlib_external.SourceFileLoader object at 0x2b5e21b2f970>
import 'faiss.loader' # <_frozen_importlib_external.SourceFileLoader object at 0x2b5e2151dd00>
import 'faiss' # <_frozen_importlib_external.SourceFileLoader object at 0x2b5e2150e8b0>
# /usr/local/conda/cellar/lib/python3.8/site-packages/faiss/__pycache__/swigfaiss_avx2.cpython-38.pyc matches /usr/local/conda/cellar/lib/python3.8/site-packages/faiss/swigfaiss_avx2.py
# code object from '/usr/local/conda/cellar/lib/python3.8/site-packages/faiss/__pycache__/swigfaiss_avx2.cpython-38.pyc'
Illegal instruction

Upon closer investigation of the faiss package it does include non-AVX2 python bindings, and we tracked the problem down to this line (introduced in 8226fe1):

controller/cellar/core/_cluster.py:5:from faiss.swigfaiss_avx2 import compute_PQ_dis_tables_dsub2

Which pulls in the AVX2 implementation regardless of what CPU type cellar is actually running on. faiss actually imports all the symbols from swigfaiss into the top-level namespace (see faiss/loader.py), so changing cluster.py to the following is enough to fix the problem:

from faiss import compute_PQ_dis_tables_dsub2

and this will still use AVX2 when available.

Missing `data/uploaded` folder in the Docker

Thank you for developing this amazing tool!
I'm trying to deploy it for our datasets, and simply using the docker throws an error on dataset upload:

docker run --rm -p 8050:8050 -v /home/azureuser/data:/home/nonroot/cellar/data euxhen/cellar

ERROR: Exception on /_dash-update-component [POST]
Traceback (most recent call last):
File "/home/nonroot/.conda/envs/cellar/lib/python3.8/site-packages/flask/app.py", line 2077, in wsgi_app
response = self.full_dispatch_request()
File "/home/nonroot/.conda/envs/cellar/lib/python3.8/site-packages/flask/app.py", line 1525, in full_dispatch_request
rv = self.handle_user_exception(e)
File "/home/nonroot/.conda/envs/cellar/lib/python3.8/site-packages/flask/app.py", line 1523, in full_dispatch_request
rv = self.dispatch_request()
File "/home/nonroot/.conda/envs/cellar/lib/python3.8/site-packages/flask/app.py", line 1509, in dispatch_request
return self.ensure_sync(self.view_functions[rule.endpoint])(**req.view_args)
File "/home/nonroot/.conda/envs/cellar/lib/python3.8/site-packages/dash/dash.py", line 1383, in dispatch
response.set_data(func(*args, outputs_list=outputs_list))
File "/home/nonroot/.conda/envs/cellar/lib/python3.8/site-packages/dash/_callback.py", line 151, in add_context
output_value = func(*func_args, **func_kwargs) # %% callback invoked %%
File "/home/nonroot/cellar/controller/data_uploader.py", line 46, in upload_data
with open(os.path.join(DATA_PATH, 'uploaded', filename), "wb") as f:
FileNotFoundError: [Errno 2] No such file or directory: 'data/uploaded/processed.h5ad'

If I log in to the container (docker run --rm -p 8050:8050 -v /home/azureuser/data:/home/nonroot/cellar/data -it --entrypoint /bin/bash euxhen/cellar) and create a subfolder manually (mkdir data/uploaded), it starts working fine.

UPDATE: I just realized that the problem was in the -v /home/azureuser/data:/home/nonroot/cellar/data part. It overrides the whole data folder, which is incorrect. Instead, the data folder should be mounted to /home/nonroot/cellar/data/server. So the solution would be to update the documentation, describing that either the mounted directory should have subfolders server and uploaded, or that it should be mounted to /home/nonroot/cellar/data/server.

UPDATE 2: Looking at other content of the data folder, it looks like normal functioning of Cellar requires the following files:

data/ASCT-B_tables
data/geneIdsNamesHuman.csv
data/geneIdsNamesMouse.csv

So, full mounting of the data folder should not be recommended, I guess?