mirror of
https://github.com/chanzuckerberg/cellxgene.git
synced 2026-09-15 12:47:56 +08:00
updates the roadmap & reorganizes the README (#712)
This commit is contained in:
Justin Kiggins
244
README.md
244
README.md
@@ -2,224 +2,59 @@
|
||||
|
||||
> an interactive explorer for single-cell transcriptomics data
|
||||
|
||||
`cellxgene` is an interactive data explorer for single-cell transcriptomics datasets, such as those coming from the [Human Cell Atlas](https://humancellatlas.org). Leveraging modern web development techniques to enable fast visualizations of at least 1 million cells, we hope to enable biologists and computational researchers to explore their data, and to demonstrate general, scalable, and reusable patterns for scientific data visualization.
|
||||
_cellxgene_ is an interactive data explorer for single-cell transcriptomics datasets, such as those coming from the [Human Cell Atlas](https://humancellatlas.org). Leveraging modern web development techniques to enable fast visualizations of at least 1 million cells, we hope to enable biologists and computational researchers to explore their data, and to demonstrate general, scalable, and reusable patterns for scientific data visualization.
|
||||
|
||||
<img src="https://raw.githubusercontent.com/chanzuckerberg/cellxgene/master/docs/cellxgene-demo-1.gif" width="200" height="200" hspace="30"><img src="https://raw.githubusercontent.com/chanzuckerberg/cellxgene/master/docs/cellxgene-demo-2.gif" width="200" height="200" hspace="30"><img src="https://raw.githubusercontent.com/chanzuckerberg/cellxgene/master/docs/cellxgene-demo-3.gif" width="200" height="200" hspace="30">
|
||||
|
||||
## getting started
|
||||
- Want to install and use cellxgene? Visit the [cellxgene docs](https://chanzuckerberg.github.io/cellxgene/).
|
||||
- Want to see where we are going? Check out [our roadmap](ROADMAP.md).
|
||||
- Want to contribute? See our [contributors guide](#Contributing)
|
||||
|
||||
You'll need **python 3.6+** and **Google Chrome**.
|
||||
The web UI is tested on OSX and Windows using Chrome, and the python CLI is tested on OSX and Ubuntu (via WSL/Windows). It should work on other platforms, but if you run into trouble let us know (see [help](#help-and-contact) below).
|
||||
## quick start
|
||||
|
||||
To install run
|
||||
To install _cellxgene_ you need Python 3.6+. We recommend [installing _cellxgene_ into a conda or virtual environment.](https://chanzuckerberg.github.io/cellxgene/faq.html#how-do-i-create-a-python-36-environment-for-cellxgene)
|
||||
|
||||
```
|
||||
Install the package.
|
||||
``` bash
|
||||
pip install cellxgene
|
||||
```
|
||||
|
||||
To start exploring a dataset call
|
||||
Download an example [anndata](https://anndata.readthedocs.io/en/latest/) file
|
||||
|
||||
```
|
||||
cellxgene launch dataset.h5ad --open
|
||||
``` bash
|
||||
curl -o pbmc3k.h5ad https://raw.githubusercontent.com/chanzuckerberg/cellxgene/master/example-dataset/pbmc3k.h5ad
|
||||
```
|
||||
|
||||
If you want an example dataset download [this file](https://github.com/chanzuckerberg/cellxgene/raw/master/example-dataset/pbmc3k.h5ad) and then call
|
||||
|
||||
```
|
||||
Launch _cellxgene_
|
||||
``` bash
|
||||
cellxgene launch pbmc3k.h5ad --open
|
||||
```
|
||||
|
||||
You should see your web browser open with the following
|
||||
To learn more about what you can do with _cellxgene_, see the [Getting Started](https://chanzuckerberg.github.io/cellxgene/getting-stared/) guide.
|
||||
|
||||
<img width="450" src="https://raw.githubusercontent.com/chanzuckerberg/cellxgene/master/docs/cellxgene-opening-screenshot.png" pad="50px">
|
||||
## get in touch
|
||||
|
||||
**Note**: automatic opening of the browser with the `--open` flag only works on OS X, on other platforms you'll need to directly point to the provided link in your browser.
|
||||
Have questions, suggestions, or comments? You can come hang out with us by joining the [CZI Science Slack](https://join-cellxgene-users.herokuapp.com/) and posting in the `#cellxgene-users` channel. As mentioned above, please submit any feature requests or bugs as [Github issues](https://github.com/chanzuckerberg/cellxgene/issues). We'd love to hear from you!
|
||||
|
||||
There are several options available, such as:
|
||||
## where we are going
|
||||
|
||||
- `--layout` to specify the layout as `tsne`, `umap`, `diffmap`, `phate`, `draw_graph_fa`, or `draw_graph_fr`
|
||||
- `--title` to show a title on the explorer
|
||||
- `--open` to automatically open the web browser after launching (OS X only)
|
||||
Our goal is to enable teams of computational and experimental
|
||||
biologists to collaboratively gain insight into their single-cell RNA-seq data.
|
||||
|
||||
To see all options call
|
||||
There are 4 key features we plan to implement in the near term.
|
||||
|
||||
```
|
||||
cellxgene launch --help
|
||||
```
|
||||
- Click install and launch
|
||||
- Manual annotation workflows
|
||||
- Toggle embeddings
|
||||
- Gene information
|
||||
|
||||
There is an additional subcommand called `cellxgene prepare` that takes an existing dataset in one of several formats and applies minimal preprocessing and reformatting so that `launch` can use it (see [the next section](##data-formatting) for more info on `prepare`).
|
||||
For more detail on these features and where we are going, see [our roadmap](ROADMAP.md).
|
||||
|
||||
## data formatting
|
||||
## contributing
|
||||
|
||||
### assumptions
|
||||
We warmly welcome contributions from the community! Please submit any bug reports and feature requests through [Github issues](https://github.com/chanzuckerberg/cellxgene/issues). Please submit any direct contributions by forking the repository, creating a branch, and submitting a Pull Request. It'd be great for PRs to include test cases and documentation updates where relevant, though we know the core test suite is itself still a work in progress. And all code contributions and dependencies must be compatible with the project's open-source license (MIT). If you have any questions about this stuff, just ask!
|
||||
|
||||
The `launch` command assumes that the data is stored in the `.h5ad` format from the [`anndata`](https://anndata.readthedocs.io/en/latest/index.html) library. It also assumes that certain computations have already been performed. Briefly, the `.h5ad` format wraps a two-dimensional `ndarray` and stores additional metadata as "annotations" for either observations (referred to as `obs` and `obsm`) or variables (`var` and `varm`). `cellxgene launch` makes the following assumptions about your data (we recommend loading and inspecting your data using `scanpy` to validate these assumptions)
|
||||
|
||||
- an `obs` field has a unique identifier for every cell (you can specify which field to use with the `--obs-names` option, by default it will use the value of `data.obs_names`)
|
||||
- a `var` field has a unique identifier for every gene (you can specify which field to use with the `--var-names` option, by default it will use the value of `data.var_names`)
|
||||
- an `obsm` field contains the two-dimensional coordinates for the layout that you want to render (e.g. `X_umap` for the `umap` layout)
|
||||
- any additional `obs` fields will be rendered as per-cell continuous or categorical metadata by the app (e.g. `louvain` cluster assignments)
|
||||
|
||||
### prepare
|
||||
|
||||
The `prepare` command is included to help you format your data. It uses `scanpy` under the hood. This is especially useful if you are starting with raw unanalyzed data and are unfamiliar with `scanpy`.
|
||||
|
||||
To prepare from an existing `.h5ad` file use
|
||||
|
||||
```
|
||||
cellxgene prepare dataset.h5ad --output=dataset-processed.h5ad
|
||||
```
|
||||
|
||||
This will load the input data, calculate QC metrics, perform PCA and nearest neighbor calculations, compute `umap` and `tsne` layouts and `louvain` cluster assignments, and save the results in a new file called `dataset-processed.h5ad` that can be loaded using `cellxgene launch`. Data can be loaded from several formats, including `.h5ad` `.loom` and a `10-Genomics-formatted` `mtx` directory. Several options are available, including running one of the preprocessing `recipes` included with `scanpy`, which include steps like cell filtering and gene selection. To learn more about the `recipes` please see the `scanpy` [documentation](https://scanpy.readthedocs.io/en/latest/api/index.html#recipes).
|
||||
|
||||
Depending on the options chosen, `prepare` can take a long time to run (a few minutes for datasets with 10-100k cells, up to an hour or more for datasets with >100k cells). If you want `prepare` to run faster we recommend using the `sparse` option and only computing the layout for `umap`, using a call like this
|
||||
|
||||
```
|
||||
cellxgene prepare dataset.h5ad --output=dataset-processed.h5ad --layout=umap --sparse
|
||||
```
|
||||
|
||||
To see all options call
|
||||
|
||||
```
|
||||
cellxgene prepare --help
|
||||
```
|
||||
|
||||
**Note**: `cellxgene prepare` will only perform `louvain` clustering if you have the `python-igraph` and `louvain` packages installed. To make sure they are installed alongside `cellxgene` use
|
||||
|
||||
```
|
||||
pip install cellxgene[louvain]
|
||||
```
|
||||
|
||||
If the aforementioned optional package installation fails, you can also install these packages directly:
|
||||
|
||||
```
|
||||
pip install python-igraph louvain>=0.6
|
||||
```
|
||||
|
||||
## conda and virtual environments
|
||||
|
||||
If you use conda and want to create a conda environment for `cellxgene` you can use the following commands
|
||||
|
||||
```
|
||||
conda create --yes -n cellxgene python=3.7
|
||||
conda activate cellxgene
|
||||
pip install cellxgene
|
||||
```
|
||||
|
||||
Or you can create a virtual environment by using
|
||||
|
||||
```
|
||||
ENV_NAME=cellxgene
|
||||
python3.7 -m venv ${ENV_NAME}
|
||||
source ${ENV_NAME}/bin/activate
|
||||
pip install cellxgene
|
||||
```
|
||||
|
||||
## docker
|
||||
|
||||
We have included a dockerfile to conveniently run cellxgene from docker.
|
||||
|
||||
1. Build the image `docker build . -t cellxgene`
|
||||
2. Run the container and mount data `docker run -v "$PWD/example-dataset/:/data/" -p 5005:5005 cellxgene launch --host 0.0.0.0 data/pbmc3k.h5ad`
|
||||
- You will need to use --host 0.0.0.0 to have the container listen to incoming requests from the browser
|
||||
|
||||
## FAQ
|
||||
|
||||
<details>
|
||||
|
||||
<summary> questions about data formatting </summary>
|
||||
|
||||
<hr>
|
||||
|
||||
> Someone sent me a directory of `10X-Genomics` data with a `mtx` file and I've never used `scanpy`, can I use `cellxgene`?
|
||||
|
||||
Yep! This should only take a couple steps. We'll assume your data is in a folder called `data/` and you've successfully installed `cellxgene` with the `louvain` packages as described above. Just run
|
||||
|
||||
```
|
||||
cellxgene prepare data/ --output=data-processed.h5ad --layout=umap
|
||||
```
|
||||
|
||||
Depending on the size of the dataset, this may take some time. Once it's done, call
|
||||
|
||||
```
|
||||
cellxgene launch data-processed.h5ad --layout=umap --open
|
||||
```
|
||||
|
||||
And your web browser should open with an interactive view of your data.
|
||||
|
||||
<hr>
|
||||
|
||||
> In my `prepare` command I received the following error `Warning: louvain module is not installed, no clusters will be calculated. To fix this please install cellxgene with the optional feature louvain enabled`
|
||||
|
||||
Louvain clustering requires additional dependencies that are somewhat complex, so we don't include them by default. For now, you need to specify that you want these packages by using
|
||||
|
||||
```
|
||||
pip install cellxgene[louvain]
|
||||
```
|
||||
|
||||
<hr>
|
||||
|
||||
> I ran `prepare` and I'm getting results that look unexpected
|
||||
|
||||
You might want to try running one of the preprocessing recipes included with `scanpy` (read more about them [here](https://scanpy.readthedocs.io/en/latest/api/index.html#recipes)). You can specify this with the `--recipe` option, such as
|
||||
|
||||
```
|
||||
cellxgene prepare data/ --output=data-processed.h5ad --recipe=zheng17
|
||||
```
|
||||
|
||||
It should be easy to run `prepare` then call `cellxgene launch` a few times with different settings to explore different behaviors. We may explore adding other preprocessing options in the future.
|
||||
|
||||
<hr>
|
||||
|
||||
> I have extra metadata that I want to add to my dataset
|
||||
|
||||
Currently this is not supported directly, but you should be able to do this manually using `scanpy`. For example, this [notebook](https://github.com/falexwolf/fun-analyses/blob/master/tabula_muris/tabula_muris.ipynb) shows adding the contents of a `csv` file with metadata to an `anndata` object. For now, you could do this manually on your data in the same way and then save out the result before loading into `cellxgene`.
|
||||
|
||||
<hr>
|
||||
|
||||
> What part of the anndata objects does cellxgene pull in for visualization?
|
||||
|
||||
- `.obs` and `.var` annotations are use to extract metadata for filtering
|
||||
- `.X` is used to display expression (histograms, scatterplot & colorscale) and to compute differential expression
|
||||
- `.obsm` is used for layout
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary> questions about installing and building </summary>
|
||||
|
||||
<hr>
|
||||
|
||||
> I tried to `pip install cellxgene` and got a weird error about missing paths to an HDF5 library?
|
||||
|
||||
You probably just need to install HDF5 first. If you're on a mac, you can simply `brew install hdf5` and then try `pip install cellxgene` again.
|
||||
|
||||
> I tried to `pip install cellxgene` and got another weird error I don't understand
|
||||
|
||||
This may happen, especially as we work out bugs in our installation process! Please create a new [Github issue](https://github.com/chanzuckerberg/cellxgene/issues), explain what you did, and include all the error messages you saw. It'd also be super helpful if you call `pip freeze` and include the full output alongside your issue.
|
||||
|
||||
<hr>
|
||||
|
||||
> I'm following the developer instructions and get an error about "missing files and directories” when trying to build the client
|
||||
|
||||
This is likely because you do not have node and npm installed, we recommend using [nvm](https://github.com/creationix/nvm) if you're new to using these tools.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary> questions about algorithms </summary>
|
||||
|
||||
<hr>
|
||||
|
||||
> How are you computing and sorting differential expression results?
|
||||
|
||||
Currently we use a [Welch's _t_-test](https://en.wikipedia.org/wiki/Welch%27s_t-test) implementation including the same variance overestimation correction as used in `scanpy`. We sort the `tscore` to identify the top N genes, and then filter to remove any that fall below a cutoff log fold change value, which can help remove spurious test results. The default threshold is `0.01` and can be changed using the option `--diffexp-lfc-cutoff`. We can explore adding support for other test types in the future.
|
||||
|
||||
</details>
|
||||
|
||||
## developer guide
|
||||
### developer guide
|
||||
|
||||
This project has made a few key design choices
|
||||
|
||||
@@ -256,20 +91,7 @@ You can start the app while developing either by calling `cellxgene` or by calli
|
||||
|
||||
If you have any questions about developing or contributing, come hang out with us by joining the [CZI Science Slack](https://join-cellxgene-users.herokuapp.com/) and posting in the `#cellxgene-dev` channel.
|
||||
|
||||
## development roadmap
|
||||
|
||||
`cellxgene` is still very much in development, and we've love to include the community as we plan new features to work on. We are thinking about working on the following features over the next 3-12 months. If you are interested in updates, want to give feedback, want to contribute, or have ideas about other features we should work on, please [contact us](#help-and-contact)
|
||||
|
||||
- **Visualizaling spatial metadata** Image-based transcriptomics methods also generate large cell by gene matrices, alongside rich metadata about spatial location; we would like to render this information in `cellxgene`
|
||||
- **Visualizing trajectories** Trajectory analyses infer progression along some ordering or pseudotime; we would like `cellxgene` to render the results of these analyses when they have been performed
|
||||
- **Deploy to web** Many projects release public data browser websites alongside their publicatons; we would like to make it easy for anyone to deploy `cellxgene` to a custom URL with their own dataset that they own and operate
|
||||
- **HCA Integration** The [Human Cell Atlas](https://humancellatlas.org) is generating a large corpus of single-cell expression data and will make it available through the Data Coordination Platform; we would like `cellxgene` to be one of several different portals for browsing these data
|
||||
|
||||
## contributing
|
||||
|
||||
We warmly welcome contributions from the community! Please submit any bug reports and feature requests through [Github issues](https://github.com/chanzuckerberg/cellxgene/issues). Please submit any direct contributions by forking the repository, creating a branch, and submitting a Pull Request. It'd be great for PRs to include test cases and documentation updates where relevant, though we know the core test suite is itself still a work in progress. And all code contributions and dependencies must be compatible with the project's open-source license (MIT). If you have any questions about this stuff, just ask!
|
||||
|
||||
## inspiration and collaboration
|
||||
## inspiration
|
||||
|
||||
We've been heavily inspired by several other related single-cell visualization projects, including the [UCSC Cell Browswer](http://cells.ucsc.edu/), [Cytoscape](http://www.cytoscape.org/), [Xena](https://xena.ucsc.edu/), [ASAP](https://asap.epfl.ch/), [Gene Pattern](http://genepattern-notebook.org/), and many others. We hope to explore collaborations where useful as this community works together on improving interactive visualization for single-cell data.
|
||||
|
||||
@@ -279,9 +101,13 @@ We have been working closely with the [`scanpy`](https://github.com/theislab/sca
|
||||
|
||||
We are eager to explore integrations with other computational backends such as [`Seurat`](https://github.com/satijalab/seurat) or [`Bioconductor`](https://github.com/Bioconductor)
|
||||
|
||||
## help and contact
|
||||
## core team
|
||||
|
||||
Have questions, suggestions, or comments? You can come hang out with us by joining the [CZI Science Slack](https://join-cellxgene-users.herokuapp.com/) and posting in the `#cellxgene-users` channel. As mentioned above, please submit any feature requests or bugs as [Github issues](https://github.com/chanzuckerberg/cellxgene/issues). We'd love to hear from you!
|
||||
- Colin Megill, frontend & product design
|
||||
- Charlotte Weaver, software engineer
|
||||
- Bruce Martin, software engineer
|
||||
- Sidney Bell, computational biologist
|
||||
- Justin Kiggins, product manager
|
||||
|
||||
## reuse
|
||||
|
||||
|
||||
54
ROADMAP.md
Normal file
54
ROADMAP.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# cellxgene roadmap
|
||||
|
||||
We are very exited for _cellxgene_ to become a valuable tool in collaborations
|
||||
between computational biologists and experimental biologists working on
|
||||
single-cell transcriptomics data. _cellxgene_ is in active development, and we
|
||||
would love to include the community as we plan new features to work on. If you
|
||||
have questions of feedback about this roadmap, please submit an issue on
|
||||
GitHub.
|
||||
|
||||
Please note: this roadmap is subject to change.
|
||||
|
||||
*Last updated: April 11, 2019*
|
||||
|
||||
## what we are building now
|
||||
|
||||
In the near term, our goal is to enable teams of computational and experimental
|
||||
biologists to collaboratively explore and annotate their single-cell RNA-seq data.
|
||||
|
||||
There are 4 key features we plan to implement in the near term.
|
||||
|
||||
- Click install and launch
|
||||
- Manual annotation workflows
|
||||
- Toggle embeddings
|
||||
- Gene information
|
||||
|
||||
### simple install and launch
|
||||
|
||||
The command line interface for installing and launching cellxgene is a barrier
|
||||
for users who are not used to Python or using the command line. We plan to
|
||||
support installation and launch of cellxgene on Mac and Windows. See
|
||||
[Issue #687](https://github.com/chanzuckerberg/cellxgene/issues/687) for more details.
|
||||
|
||||
### manual annotation workflows
|
||||
|
||||
The exploratory visualization that cellxgene offers is critical for manual
|
||||
annotation workflows, especially in collaborative environments. We plan to
|
||||
support manually annotate cells with labels (i.e., cell type or QC flags) for
|
||||
downstream analysis. See [Issue #524](https://github.com/chanzuckerberg/cellxgene/issues/524)
|
||||
for more details.
|
||||
|
||||
### toggle embeddings
|
||||
|
||||
While a single dataset may have multiple embeddings calculated (tSNE, umap, in
|
||||
situ coordinates, trajectories, etc), cellxgene currently requires the user to select the
|
||||
embedding to use in the main layout at launch. We plan to support letting users
|
||||
toggle between any embedding present in a file from the cellxgene interface.
|
||||
See [Issue #594](https://github.com/chanzuckerberg/cellxgene/issues/594) for details.
|
||||
|
||||
### gene information
|
||||
|
||||
Differential expression returns only the names of genes, but no additional information
|
||||
about gene metadata, function, or known associations. We plan to help users learn
|
||||
more about genes they discover by exposing additional gene metadata. See
|
||||
[Issue #96](https://github.com/chanzuckerberg/cellxgene/issues/96) for details.
|
||||
@@ -754,7 +754,7 @@ class Graph extends React.Component {
|
||||
text="FAQ"
|
||||
/>
|
||||
<MenuItem
|
||||
href="https://join-cziscience-slack.herokuapp.com/"
|
||||
href="https://join-cellxgene-users.herokuapp.com/"
|
||||
target="_blank"
|
||||
icon="chat"
|
||||
text="Chat"
|
||||
|
||||
@@ -3,6 +3,8 @@ show_downloads: false
|
||||
baseurl: /cellxgene
|
||||
|
||||
nav:
|
||||
- title: Getting Started
|
||||
url: getting-started.html
|
||||
- title: Data
|
||||
url: data.html
|
||||
- title: FAQ
|
||||
|
||||
@@ -48,12 +48,12 @@ We use a [Welch's _t_-test](https://en.wikipedia.org/wiki/Welch%27s_t-test) impl
|
||||
|
||||
# Problems, errors, & bugs
|
||||
|
||||
#### How do I create a Python 3.6 environment for _cellxgene_?
|
||||
#### How do I create a Python environment for _cellxgene_?
|
||||
|
||||
If you use conda and want to create a [conda environment](https://conda.io/docs/user-guide/tasks/manage-environments.html) for _cellxgene_ you can use the following commands
|
||||
|
||||
```
|
||||
conda create --yes -n cellxgene python=3.6
|
||||
conda create --yes -n cellxgene python=3.7
|
||||
conda activate cellxgene
|
||||
pip install cellxgene
|
||||
```
|
||||
@@ -62,7 +62,7 @@ Or you can create a virtual environment by using
|
||||
|
||||
```
|
||||
ENV_NAME=cellxgene
|
||||
python3.6 -m venv ${ENV_NAME}
|
||||
python3.7 -m venv ${ENV_NAME}
|
||||
source ${ENV_NAME}/bin/activate
|
||||
pip install cellxgene
|
||||
```
|
||||
|
||||
116
docs/getting-started.md
Normal file
116
docs/getting-started.md
Normal file
@@ -0,0 +1,116 @@
|
||||
## getting started
|
||||
|
||||
You'll need **python 3.6+** and **Google Chrome**.
|
||||
The web UI is tested on OSX and Windows using Chrome, and the python CLI is tested on OSX and Ubuntu (via WSL/Windows). It should work on other platforms, but if you run into trouble let us know.
|
||||
|
||||
To install run
|
||||
|
||||
```
|
||||
pip install cellxgene
|
||||
```
|
||||
|
||||
To start exploring a dataset call
|
||||
|
||||
```
|
||||
cellxgene launch dataset.h5ad --open
|
||||
```
|
||||
|
||||
If you want an example dataset download [this file](https://github.com/chanzuckerberg/cellxgene/raw/master/example-dataset/pbmc3k.h5ad) and then call
|
||||
|
||||
```
|
||||
cellxgene launch pbmc3k.h5ad --open
|
||||
```
|
||||
|
||||
On Mac OS and Ubuntu, you should see your web browser open with the following
|
||||
|
||||
<img width="450" src="https://raw.githubusercontent.com/chanzuckerberg/cellxgene/master/docs/cellxgene-opening-screenshot.png" pad="50px">
|
||||
|
||||
**Note**: automatic opening of the browser with the `--open` flag only works on OS X, on other platforms you'll need to directly point to the provided link in your browser.
|
||||
|
||||
There are several options available, such as:
|
||||
|
||||
- `--layout` to specify the layout as `tsne`, `umap`, `diffmap`, `phate`, `draw_graph_fa`, or `draw_graph_fr`
|
||||
- `--title` to show a title on the explorer
|
||||
- `--open` to automatically open the web browser after launching (OS X only)
|
||||
|
||||
To see all options call
|
||||
|
||||
```
|
||||
cellxgene launch --help
|
||||
```
|
||||
|
||||
There is an additional subcommand called `cellxgene prepare` that takes an existing dataset in one of several formats and applies minimal preprocessing and reformatting so that `launch` can use it (see [the next section](##data-formatting) for more info on `prepare`).
|
||||
|
||||
## data formatting
|
||||
|
||||
### requirements
|
||||
|
||||
The `launch` command assumes that the data is stored in the `.h5ad` format from the [`anndata`](https://anndata.readthedocs.io/en/latest/index.html) library. It also assumes that certain computations have already been performed. Briefly, the `.h5ad` format wraps a two-dimensional `ndarray` and stores additional metadata as "annotations" for either observations (referred to as `obs` and `obsm`) or variables (`var` and `varm`). `cellxgene launch` makes the following assumptions about your data (we recommend loading and inspecting your data using `scanpy` to validate these assumptions)
|
||||
|
||||
- an `obs` field has a unique identifier for every cell (you can specify which field to use with the `--obs-names` option, by default it will use the value of `data.obs_names`)
|
||||
- a `var` field has a unique identifier for every gene (you can specify which field to use with the `--var-names` option, by default it will use the value of `data.var_names`)
|
||||
- an `obsm` field contains the two-dimensional coordinates for the layout that you want to render (e.g. `X_umap` for the `umap` layout)
|
||||
- any additional `obs` fields will be rendered as per-cell continuous or categorical metadata by the app (e.g. `louvain` cluster assignments)
|
||||
|
||||
### prepare
|
||||
|
||||
The `prepare` command is included to help you format your data. It uses `scanpy` under the hood. This is especially useful if you are starting with raw unanalyzed data and are unfamiliar with `scanpy`.
|
||||
|
||||
To prepare from an existing `.h5ad` file use
|
||||
|
||||
```
|
||||
cellxgene prepare dataset.h5ad --output=dataset-processed.h5ad
|
||||
```
|
||||
|
||||
This will load the input data, perform PCA and nearest neighbor calculations, compute `umap` and `tsne` layouts and `louvain` cluster assignments, and save the results in a new file called `dataset-processed.h5ad` that can be loaded using `cellxgene launch`. Data can be loaded from several formats, including `.h5ad` `.loom` and a `10-Genomics-formatted` `mtx` directory. Several options are available, including running one of the preprocessing `recipes` included with `scanpy`, which include steps like cell filtering and gene selection. To learn more about the `recipes` please see the `scanpy` [documentation](https://scanpy.readthedocs.io/en/latest/api/index.html#recipes).
|
||||
|
||||
Depending on the options chosen, `prepare` can take a long time to run (a few minutes for datasets with 10-100k cells, up to an hour or more for datasets with >100k cells). If you want `prepare` to run faster we recommend using the `sparse` option and only computing the layout for `umap`, using a call like this
|
||||
|
||||
```
|
||||
cellxgene prepare dataset.h5ad --output=dataset-processed.h5ad --layout=umap --sparse
|
||||
```
|
||||
|
||||
To see all options call
|
||||
|
||||
```
|
||||
cellxgene prepare --help
|
||||
```
|
||||
|
||||
**Note**: `cellxgene prepare` will only perform `louvain` clustering if you have the `python-igraph` and `louvain` packages installed. To make sure they are installed alongside `cellxgene` use
|
||||
|
||||
```
|
||||
pip install cellxgene[louvain]
|
||||
```
|
||||
|
||||
If the aforementioned optional package installation fails, you can also install these packages directly:
|
||||
|
||||
```
|
||||
pip install python-igraph louvain>=0.6
|
||||
```
|
||||
|
||||
## conda and virtual environments
|
||||
|
||||
If you use conda and want to create a conda environment for `cellxgene` you can use the following commands
|
||||
|
||||
```
|
||||
conda create --yes -n cellxgene python=3.7
|
||||
conda activate cellxgene
|
||||
pip install cellxgene
|
||||
```
|
||||
|
||||
Or you can create a virtual environment by using
|
||||
|
||||
```
|
||||
ENV_NAME=cellxgene
|
||||
python3.7 -m venv ${ENV_NAME}
|
||||
source ${ENV_NAME}/bin/activate
|
||||
pip install cellxgene
|
||||
```
|
||||
|
||||
## docker
|
||||
|
||||
We have included a dockerfile to conveniently run cellxgene from docker.
|
||||
|
||||
1. Build the image `docker build . -t cellxgene`
|
||||
2. Run the container and mount data `docker run -v "$PWD/example-dataset/:/data/" -p 5005:5005 cellxgene launch --host 0.0.0.0 data/pbmc3k.h5ad`
|
||||
- You will need to use --host 0.0.0.0 to have the container listen to incoming requests from the browser
|
||||
@@ -2,15 +2,15 @@ _cellxgene_ is an interactive data explorer for single-cell transcriptomics data
|
||||
|
||||
## features
|
||||
|
||||
#### Flexible selections, coloring, and differential expression of your selected sets of cells
|
||||
#### flexible selections, coloring, and differential expression of your selected sets of cells
|
||||
<img src="diffexp.gif" width="600"/>
|
||||
|
||||
#### Single-gene analyses (e.g. expression analysis)
|
||||
#### single-gene analyses (e.g. expression analysis)
|
||||
<img src="customGene.gif" width="600" />
|
||||
|
||||
## getting started
|
||||
## quick start
|
||||
|
||||
_cellxgene_ **only** supports Python 3.6. We recommend [installing _cellxgene_ into a conda or virtual environment.](/faq.html#how-do-i-create-a-python-36-environment-for-cellxgene)
|
||||
To install _cellxgene_ you need Python 3.6+. We recommend [installing _cellxgene_ into a conda or virtual environment.](/faq.html#how-do-i-create-a-python-environment-for-cellxgene)
|
||||
|
||||
Install the package.
|
||||
``` bash
|
||||
@@ -25,13 +25,17 @@ curl -o pbmc3k.h5ad https://raw.githubusercontent.com/chanzuckerberg/cellxgene/m
|
||||
|
||||
Launch _cellxgene_
|
||||
``` bash
|
||||
cellxgene launch pbmc3k.h5ad
|
||||
cellxgene launch pbmc3k.h5ad --open
|
||||
```
|
||||
|
||||
To explore more datasets already formatted for _cellxgene_, see [Data](data) or
|
||||
visit [Getting Started](getting-started) to learn more about formatting your own
|
||||
data for _cellxgene_.
|
||||
|
||||
## getting help
|
||||
|
||||
We'd love to hear from you!
|
||||
|
||||
For questions, suggestions, or accolades, [join the `#cellxgene-users` channel on the CZI Science Slack](https://join-cziscience-slack.herokuapp.com/) and say "hi!".
|
||||
For questions, suggestions, or accolades, [join the `#cellxgene-users` channel on the CZI Science Slack](https://join-cellxgene-users.herokuapp.com/) and say "hi!".
|
||||
|
||||
For any errors, [report bugs on Github](https://github.com/chanzuckerberg/cellxgene/issues).
|
||||
|
||||
Reference in New Issue
Block a user