From fc45fb38990b8dcbe16319df14a27872b9caa79e Mon Sep 17 00:00:00 2001 From: Justin Kiggins Date: Wed, 19 Dec 2018 13:18:16 -0800 Subject: [PATCH] creates FAQ page in docs (#522) * creates FAQ page * revise index.md * tweaks --- docs/data.md | 0 docs/fag.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 19 +++++++------ 3 files changed, 85 insertions(+), 8 deletions(-) create mode 100644 docs/data.md create mode 100644 docs/fag.md diff --git a/docs/data.md b/docs/data.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/fag.md b/docs/fag.md new file mode 100644 index 00000000..7a24206d --- /dev/null +++ b/docs/fag.md @@ -0,0 +1,74 @@ +--- +layout: default +title: FAQ +description: Frequently Asked Questions +--- + + +# data formatting + +## 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. + +## 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] +``` + +## 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. + +## 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`. + +## 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 + +## When I start _cellxgene_, I get an error `Unexpected HTTP response 500, INTERNAL SERVER ERROR -- Out of range float values are not JSON compliant` in the web UI, or `Warning: JSON encoding failure - suggest trying --nan-to-num command line option` in the CLI. What can I do? + +At the moment, _cellxgene_ is unable to transmit floating point NaN or Infinity values to the web UI (due to a limitation on data serialization method in use). We expect to resolve this in a future release, but in the meantime, you can work around this issue by starting cellxgene with the `--nan-to-num` command line option, ie, `cellxgene launch data.h5ad --nan-to-num`. + +This option will convert all NaNs to zero, and all positive/negative infinities to the min/max of the data element within which the value was found (eg, +Infinity within an `obs` annotation will be converted to the maximum finite value in that annotation). This option will increase startup time, so we recommend only using it when the dataset contains NaN/Infinities. + +# installing and building + +## I tried to `pip install cellxgene` and got a 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. + +## 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. + +# algorithms + +## How are you computing and sorting differential expression results? + +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`. diff --git a/docs/index.md b/docs/index.md index 25a0852a..97fea87a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,20 +1,23 @@ -# cellxgene +_cellxgene_ is an interactive data explorer for single-cell transcriptomics data designed to handle large datasets (1 million cells or more) and integrate with your favorite analysis tools -cellxgene is an interactive data explorer for single-cell transcriptomics data designed to handle large datasets (1 million cells or more) and integrate with your favorite analysis tools +## features + +- Flexible selection and coloring of cells +- Differential expression of arbitrary sets of cells +- Single-gene analyses ## getting started install the package > `> pip install cellxgene` -preprocess the data for use with cellxgene (optional) -> `> cellxgene --prepare dataset.h5ad -o processed.h5ad` - launch the web app > `> cellxgene --launch processed.h5ad` -## features +## getting help -### help and contact +We'd love to hear from you! -Have questions, suggestions, or comments? You can come hang out with us by joining the [CZI Science Slack](https://join-cziscience-slack.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! +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 any errors, [report bugs on Github](https://github.com/chanzuckerberg/cellxgene/issues).