diff --git a/client/src/components/menubar/index.js b/client/src/components/menubar/index.js index 3d7fb1ae..cbb9a32a 100644 --- a/client/src/components/menubar/index.js +++ b/client/src/components/menubar/index.js @@ -437,7 +437,7 @@ class MenuBar extends React.Component { }} > diff --git a/docs/data.md b/docs/data.md index 671004b1..5fded59c 100644 --- a/docs/data.md +++ b/docs/data.md @@ -46,8 +46,15 @@ As a quick example, let's construct a command to use `prepare` to take a raw exp We'll start off using the raw data from the pbmc3k dataset. This dataset is described [here](https://icb-scanpy.readthedocs-hosted.com/en/stable/api/scanpy.datasets.pbmc3k.html), and is available as part of the scanpy API. For this example, we'll assume this raw data is stored in a file called `pbmc3k-raw.h5ad`. -Our `prepare` compose our command looks like this: - +Our `prepare` compose our command looks like this: + +``` +cellxgene prepare pbmc3k-raw.h5ad \ + --run-qc \ # (A) + --recipe seurat \ # (B) + --layout tsne --layout umap \ # (C) + --output pbmc3k-prepared.h5ad # (D) +``` Let's look at what `prepare` is doing to our data, and how each step relates to the command above. You can see a walkthrough of what's going on under the hood for this example in [this notebook](https://github.com/chanzuckerberg/cellxgene-vignettes/blob/master/dataset-processing/pbmc3k-prepare-example.ipynb). @@ -60,10 +67,9 @@ Let's look at what `prepare` is doing to our data, and how each step relates to # Example datasets to use with cellxgene - -**To download and use these datasets, run:** -`curl -O [URL]` -`unzip [filename.zip]` +**To download and use these datasets, run:** +`curl -O [URL]` +`unzip [filename.zip]` `cellxgene launch [filename.h5ad] --open` ### Peripheral blood mononuclear cells diff --git a/docs/faq.md b/docs/faq.md index 1c014f4d..f4fab0fc 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -21,13 +21,13 @@ The output of `cellxgene prepare` is a h5ad file with your computed clusters and 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 `prepare` packages as described above. Just run ``` -cellxgene prepare data/ --output=data-processed.h5ad --layout=umap +cellxgene prepare data/ --output=data-processed.h5ad --embedding=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 +cellxgene launch data-processed.h5ad --embedding=umap --open ``` And your web browser should open with an interactive view of your data. @@ -40,7 +40,7 @@ Currently this is not supported directly, but you should be able to do this your - `.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. If an embedding has more than two components, the first two will be used for visualization. +- `.obsm` is used for embedding(s). If an embedding has more than two components, the first two will be used for visualization. #### I have a BIG dataset - how can I make cellxgene run as fast as possible? diff --git a/docs/getting-started.md b/docs/getting-started.md index 484ee8e5..9b8229ce 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -35,7 +35,7 @@ On Mac OS and Ubuntu, you should see your web browser open with the following There are several options available, such as: -- `--layout` to specify the layout as `tsne`, `umap`, `diffmap`, `phate`, `draw_graph_fa`, or `draw_graph_fr` +- `--embedding` to restrict available emdeddings in the UI, eg, `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) @@ -55,7 +55,7 @@ The `launch` command assumes that the data is stored in the `.h5ad` format from - 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) +- an `obsm` field contains the two-dimensional coordinates for the embedding that you want to render (e.g. `X_umap` for the `umap` embedding) - any additional `obs` fields will be rendered as per-cell continuous or categorical metadata by the app (e.g. `louvain` cluster assignments) ### prepare @@ -80,12 +80,12 @@ 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). +This will load the input data, perform PCA and nearest neighbor calculations, compute `umap` and `tsne` embeddings 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 +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 embedding for `umap`, using a call like this ``` -cellxgene prepare dataset.h5ad --output=dataset-processed.h5ad --layout=umap --sparse +cellxgene prepare dataset.h5ad --output=dataset-processed.h5ad --embedding=umap --sparse ``` To see all options call diff --git a/docs/prepare-cmd-example.jpg b/docs/prepare-cmd-example.jpg deleted file mode 100644 index 57af0f30..00000000 Binary files a/docs/prepare-cmd-example.jpg and /dev/null differ diff --git a/server/cli/launch.py b/server/cli/launch.py index c5d71b71..31843c4d 100644 --- a/server/cli/launch.py +++ b/server/cli/launch.py @@ -25,12 +25,12 @@ def common_args(func): """ @click.option("--title", "-t", help="Title to display (if omitted will use file name).") @click.option( - "--layout", - "-l", + "--embedding", + "-e", default=[], multiple=True, - show_default=True, - help="Layout name, eg, 'umap'." + show_default=False, + help="Embedding name, eg, 'umap'. Repeat option for multiple embeddings. Defaults to all." ) @click.option("--obs-names", default=None, metavar="", help="Name of annotation field to use for observations.") @click.option("--var-names", default=None, metavar="", help="Name of annotation to use for variables.") @@ -53,9 +53,9 @@ def common_args(func): return wrapper -def parse_engine_args(layout, obs_names, var_names, max_category_items, diffexp_lfc_cutoff): +def parse_engine_args(embedding, obs_names, var_names, max_category_items, diffexp_lfc_cutoff): return { - "layout": layout, + "layout": embedding, "max_category_items": max_category_items, "diffexp_lfc_cutoff": diffexp_lfc_cutoff, "obs_names": obs_names, @@ -101,7 +101,7 @@ def launch( open_browser, port, host, - layout, + embedding, obs_names, var_names, max_category_items, @@ -122,7 +122,7 @@ def launch( > cellxgene launch """ - e_args = parse_engine_args(layout, obs_names, var_names, max_category_items, diffexp_lfc_cutoff) + e_args = parse_engine_args(embedding, obs_names, var_names, max_category_items, diffexp_lfc_cutoff) try: data_locator = DataLocator(data) except RuntimeError as re: diff --git a/server/cli/prepare.py b/server/cli/prepare.py index bd8eb286..730e4f86 100644 --- a/server/cli/prepare.py +++ b/server/cli/prepare.py @@ -8,12 +8,12 @@ from scipy.sparse.csc import csc_matrix @click.command() @click.argument("data", nargs=1, metavar="", required=True) @click.option( - "--layout", - "-l", + "--embedding", + "-e", default=["umap", "tsne"], multiple=True, type=click.Choice(["umap", "tsne"]), - help="Layout algorithm", + help="Embedding algorithm", show_default=True, ) @click.option( @@ -42,7 +42,7 @@ from scipy.sparse.csc import csc_matrix ) def prepare( data, - layout, + embedding, recipe, output, plotting, @@ -59,7 +59,7 @@ def prepare( This tool runs a series of scanpy routines for preparing a dataset for use with cellxgene. It loads data from different formats (h5ad, loom, or a 10x directory), runs dimensionality reduction, - computes nearest neighbors, computes a layout, performs clustering, + computes nearest neighbors, computes an embedding, performs clustering, and saves the results. Includes additional options for naming annotations, ensuring sparsity, and plotting results.""" @@ -162,18 +162,18 @@ def prepare( def run_louvain(adata): sc.tl.louvain(adata) - def run_layout(adata): + def run_embedding(adata): if len(unique(adata.obs["louvain"].values)) < 10: palette = "tab10" else: palette = "tab20" - if "umap" in layout: + if "umap" in embedding: sc.tl.umap(adata) if plotting: sc.pl.umap(adata, color="louvain", palette=palette, save="_louvain") - if "tsne" in layout: + if "tsne" in embedding: sc.tl.tsne(adata) if plotting: sc.pl.tsne(adata, color="louvain", palette=palette, save="_louvain") @@ -190,12 +190,12 @@ def prepare( "run_pca": "Running PCA", "run_neighbors": "Calculating neighbors", "run_louvain": "Calculating clusters", - "run_layout": "Computing layout", + "run_embedding": "Computing embedding", } if item is not None: return names[item.__name__] - steps = [calculate_qc_metrics, make_sparse, run_recipe, run_pca, run_neighbors, run_louvain, run_layout] + steps = [calculate_qc_metrics, make_sparse, run_recipe, run_pca, run_neighbors, run_louvain, run_embedding] click.echo(f"[cellxgene] Loading data from {data}, please wait...") adata = load_data(data)