From 922c3753333365d76e6f582453254f9bdec7ac67 Mon Sep 17 00:00:00 2001 From: Bruce Martin Date: Mon, 16 Sep 2019 15:34:14 -0700 Subject: [PATCH] Rename "layout" to "embedding" in the UI (#921) * rename "layout" to "embedding" in the UI * docs changes for layout * fix typo in data docs * new help text, per PR review --- client/src/components/menubar/index.js | 2 +- docs/data.md | 18 ++++++++++++------ docs/faq.md | 6 +++--- docs/getting-started.md | 10 +++++----- docs/prepare-cmd-example.jpg | Bin 9049 -> 0 bytes server/cli/launch.py | 16 ++++++++-------- server/cli/prepare.py | 20 ++++++++++---------- 7 files changed, 39 insertions(+), 33 deletions(-) delete mode 100644 docs/prepare-cmd-example.jpg 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 57af0f30198f32155e67d0a434b3627e3b64cbd9..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 9049 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 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)