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

@@ -437,7 +437,7 @@ class MenuBar extends React.Component {
                 }}
               >
                 <RadioGroup
-                  label="Layout Choice"
+                  label="Embedding Choice"
                   onChange={this.handleLayoutChoiceChange}
                   selectedValue={layoutChoice.current}
                 >

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:
-<img src="prepare-cmd-example.jpg" width="700" />
+
+```
+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:**
-**To download and use these datasets, run:**  
+`curl -O [URL]`
-`curl -O [URL]`  
+`unzip [filename.zip]`
-`unzip [filename.zip]`  
 `cellxgene launch [filename.h5ad] --open`
 
 ### Peripheral blood mononuclear cells

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?
 

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

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",
+        "--embedding",
-        "-l",
+        "-e",
         default=[],
         multiple=True,
-        show_default=True,
+        show_default=False,
-        help="Layout name, eg, 'umap'."
+        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 <url>"""
 
-    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:

server/cli/prepare.py

@@ -8,12 +8,12 @@ from scipy.sparse.csc import csc_matrix
 @click.command()
 @click.argument("data", nargs=1, metavar="<dataset: file or path to data>", required=True)
 @click.option(
-    "--layout",
+    "--embedding",
-    "-l",
+    "-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)