Cirrocumulus
----------------

Cirrocumulus is an interactive visualization tool for large-scale single-cell genomics data, with the following features:

* Visualize datasets in h5ad_, `10x h5`_, Xenium_, loom_, Seurat_, TileDB_, or zarr_ formats
* View MERFISH_ or other spatial transcriptomics data overlaid on an image
* Easily deploy on a laptop, on-premise server, cloud VM, or Google App Engine
* Share the current visualization state in a URL
* Share datasets securely with collaborators
* Create dotplots, heatmaps, and violin plots to explore relationships between categorical variables and expression
* Generate composition plots to inspect cluster makeup
* Explore complete differential expression results generated by `Scanpy`_ or `Pegasus`_/`Cumulus`_
* Interactively create and share “AND” or “OR” filters
* Collaboratively annotate cell types in real time, optionally using a controlled vocabulary (`example ontology`_)
* Quickly load multiple features from predefined lists (`see example`_)
* Explore multiple features and embeddings simultaneously
* Fast interactive exploration of 2 and 3-d embeddings of millions of cells, including zoom, pan, rotate (3-d), and lasso tools
* Save publication quality images
* Highly customizable - for example, set the color map, point size, or whether to use fog for 3-d embeddings to fade distant points


Quick Start
-------------

Install the package::

    pip install cirrocumulus

Launch cirrocumulus via the command line::

    cirro launch <path_to_dataset>

- Launch accepts more than one dataset to enable quick dataset switching or to combine modalities (e.g gene fusions and expression) stored in separate files.


Example Data
^^^^^^^^^^^^^

- Download `3k PBMCs from a healthy donor data`_ and launch::

    cirro launch pbmc3k.h5ad --markers markers.json


- Download `human lymph node spatial data`_ and launch::

    cirro launch V1_Human_Lymph_Node/V1_Human_Lymph_Node.h5ad --spatial V1_Human_Lymph_Node/spatial


.. image:: images/play3d.gif

Complete documentation available at https://cirrocumulus.readthedocs.io


.. _3k PBMCs from a healthy donor data: https://github.com/klarman-cell-observatory/cirrocumulus/raw/master/docs/pbmc3k.zip
.. _human lymph node spatial data: https://github.com/klarman-cell-observatory/cirrocumulus/raw/master/docs/V1_Human_Lymph_Node.zip
.. _h5ad: https://anndata.readthedocs.io/
.. _loom: https://linnarssonlab.org/loompy/format/
.. _STAR-Fusion: https://github.com/STAR-Fusion/STAR-Fusion/wiki
.. _Seurat: https://satijalab.org/seurat/
.. _see example: https://github.com/klarman-cell-observatory/cirrocumulus/raw/master/docs/markers.json
.. _Pegasus: http://pegasus.readthedocs.io/
.. _Cumulus: https://cumulus.readthedocs.io/en/stable/cumulus.html
.. _Scanpy: https://scanpy.readthedocs.io/
.. _TileDB: https://tiledb.com/
.. _zarr: https://zarr.readthedocs.io/
.. _example ontology: http://www.obofoundry.org/ontology/cl.html
.. _10x h5: https://support.10xgenomics.com/spatial-gene-expression/software/pipelines/latest/advanced/h5_matrices
.. _MERFISH: https://www.biorxiv.org/content/10.1101/2023.03.06.531121v1
.. _Xenium: https://www.10xgenomics.com/support/in-situ-gene-expression/documentation/steps/onboard-analysis/at-a-glance-xenium-output-files
