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

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:  
-<img src="prepare-cmd-example.jpg" width="700" />
+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

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