Update the documentation adn improve details

introduction/getting-started/index.md

@@ -2,24 +2,29 @@
 
 ## Overview
 
-Using **`dms-viz`** involves two steps. First, using a command line tool called [`configure-dms-viz`](https://pypi.org/project/configure-dms-viz/), you specify some information about your dataset to generate a `.json` format specification file. Second, you open up the [web-based tool](https://dms-viz.github.io/) and upload your specification file to generate an interactive visualization. Below are some quickstart instructions to get you oriented.
+**`dms-viz`** requires two steps:
+
+1. First, using a command line tool called [`configure-dms-viz`](https://pypi.org/project/configure-dms-viz/), you specify information about your dataset to generate a `.json` specification file.
+
+2. Second, you open up the [web tool](https://dms-viz.github.io/) and upload your `.json` specification file to generate an interactive visualization. Below are some instructions to get you oriented.
 
 ::: tip Want to Skip Ahead?
 If you're interested in the detailed command line API, check out the reference [here](/preparing-data/command-line-api/). If you've already formatted your data and you're ready to start visualizing it, check out the instructions for that [here](/visualizing-data/web-tool-api/).
 :::
-Prerequisites
 
-To start using **`dms-viz`** with your own data, you'll need to install the command line tool [`configure-dms-viz`](https://pypi.org/project/configure-dms-viz/). To use `configure-dms-viz`, you must ensure that you have the correct version of Python (3.9 or later) installed on your system.
+## Prerequisites
+
+To use **`dms-viz`** with your data, you'll need to install the command line tool [`configure-dms-viz`](https://pypi.org/project/configure-dms-viz/). To use `configure-dms-viz`, you must ensure that you have the correct version of Python (3.9 or later) installed on your system.
 
-If you are unsure whether you have the correct version of Python installed, open a terminal window (Command Prompt in Windows, Terminal in macOS, or a terminal emulator in Linux) type the following command and press Enter:
+If you are unsure whether the correct version of Python is installed, open a terminal window (Command Prompt in Windows, Terminal in macOS, or a terminal emulator in Linux) and run the following command:
 
 ```bash
 python --version
 ```
 
 Check the version number that is displayed. It should be 3.9.x or later. If the command isn't recognized or the version is earlier than 3.9, you will need to install or update Python.
 
-To install `configure-dms-viz`, you'll also need the package manager `pip`. Here's how to check if `pip` is installed and how to install it if it isn't. In the terminal window, type the following command and press Enter:
+To install `configure-dms-viz`, you'll also need the package manager `pip`. Here's how to check if `pip` is installed and how to install it if it isn't. In the terminal window, run the following command:
 
 ```bash
 pip --version
@@ -29,26 +34,26 @@ If `pip` is installed, the version number will be displayed. If it is not instal
 
 ## Installation
 
-Currently, `configure-dms-viz` is distributed on [PyPI](https://pypi.org/), allowing you to install `configure-dms-viz` using `pip`. To install the latest version of `configure-dms-viz`, type the following command into the terminal:
+Currently, `configure-dms-viz` is distributed on [PyPI](https://pypi.org/), allowing you to install `configure-dms-viz` using `pip`. To install the latest version of `configure-dms-viz`, run the following command in the terminal:
 
 ```bash
 pip install configure-dms-viz
 ```
 
-Now, `configure-dms-viz` should have been installed and you shouldn't see any error messages. You can double-check that the installation worked correctly by typing the following into the terminal:
+Now, `configure-dms-viz` should be installed. You can double-check that the installation worked by running the following command in the terminal:
 
 ```bash
 configure-dms-viz --help
 ```
 
-You should see the help message for the tool printed to the terminal.
+You should see the help message for the tool printed to the terminal's output.
 
 ## Basic Usage
 
-`configure_dms_viz` is a command-line tool designed to create a `JSON` format specification file for **`dms-viz`**. You provide the data that you'd like to visualize along with additional information to customize the analysis. The resulting specification file can be uploaded to [**`dms-viz`**](https://dms-viz.github.io/) for interactive visualization of your data. Below is an overview of the process of using `configure_dms_viz`.
+`configure_dms_viz` is a command-line tool designed to create a `.json` format specification file for **`dms-viz`**. You provide the data that you'd like to visualize along with additional information to customize the visualization. The resulting specification file is then uploaded to [**`dms-viz`**](https://dms-viz.github.io/) to create the visualization of your data. Below is an overview of the process of using `configure_dms_viz`.
 
 ::: tip Looking for more details?
-For a detailed explanation of the features of `configure_dms_viz` check out the reference [here](/preparing-data/command-line-api/).
+This example only covers the *basic* use case. You can augment `dms-viz` with custom tooltips, filters, and more. For a detailed explanation of these features, check out the reference [here](/preparing-data/command-line-api/).
 :::
 
 `configure-dms-viz` has two commands, `format` and `join`. To format a single dataset for **`dms-viz`**, you execute the `configure-dms-viz format` command with the required and optional arguments as needed:
@@ -59,29 +64,27 @@ configure-dms-viz format \
     --input <input_csv> \
     --metric <metric_column> \
     --structure <pdb_structure> \
-    --sitemap <sitemap_csv> \
     --output <output_json> \
     [optional_arguments]
 ```
 
-The information that is required to make a visualization file for **`dms-viz`** is as follows:
+The **required** arguments are:
 
 1. `--name`: The [name of your dataset](/preparing-data/command-line-api/#name) as you'd like it to appear in the visualization.
 2. `--input`: The file path to your [input data](/preparing-data/command-line-api/#input).
 3. `--metric`: The name of the column that contains [the metric](/preparing-data/command-line-api/#metric) you want to visualize.
 4. `--structure`: The [protein structure](/preparing-data/command-line-api/#structure) that you want to use as a model.
-5. `--sitemap`: [A map of the sites](/preparing-data/command-line-api/#sitemap) in your data to the sites in the reference and protein.
-6. `--output`: The file path of [the output](/preparing-data/command-line-api/#output) `.json` file.
+5. `--output`: The file path of [the output](/preparing-data/command-line-api/#output) `.json` file.
 
-The remaining arguments are all _optional_ and configure the look and interaction of your final visualization. For more details on the individual arguments, check out the [API reference](/preparing-data/command-line-api/).
+The remaining arguments are all _optional_ and configure the structure, appearance, and interaction of your final visualization. For more details on the individual arguments, check out the [API reference](/preparing-data/command-line-api/).
 
 ::: warning Before going any further
-If you plan to use `configure-dms-viz` right away, it's crucial to make sure that your data meets some initial requirements. Please check out what these requirements are [here](/preparing-data/data-requirements/).
+If you plan to use `configure-dms-viz`, it's _crucial_ that you familiarize yourself with the input data requirements. Please check out what these requirements are [here](/preparing-data/data-requirements/).
 :::
 
 Now, let's use `configure-dms-viz` with a minimal example. This data is included in the [GitHub repository](https://github.com/dms-viz/configure_dms_viz/tree/main). If you want to follow along, clone the repository and run `configure-dms-viz` from the top of the directory.
 
-**Input**
+### Input
 
 ```bash
 configure-dms-viz format \
@@ -97,11 +100,11 @@ configure-dms-viz format \
    --output ./REGN_escape.json
 ```
 
-Here, we've specified that we want the dataset to be called `REGN mAb Cocktail` (named after the Regeneron Antibody cocktail against SARS-CoV-2) and we've pointed to the [input data](https://github.com/dms-viz/configure_dms_viz/blob/main/tests/SARS2-RBD-REGN-DMS/input/REGN_escape.csv) containing scores detailing the degree of antibody escape from the `REGN mAb Cocktail`. We've also specified a [sitemap](https://github.com/dms-viz/configure_dms_viz/blob/main/tests/SARS2-RBD-REGN-DMS/sitemap/sitemap.csv) that tells the tool how sites in your data correspond to the sites in the protein structure. Then, we specified that we wanted to use the protein structure `6XDG` from the [RSCB PDB](https://www.rcsb.org/) and only show our data on chain `E` of that structure. The column in the input data that contains our data is called `mut_escape`, and we have different values of `mut_escape` for the same mutations depending on the `condition` (in this case, the condition refers to escape from each antibody in the cocktail).
+Here, we've specified that we want the dataset to be called `REGN mAb Cocktail` (named after the Regeneron Antibody cocktail against SARS-CoV-2) and we've pointed to the [input data](https://github.com/dms-viz/configure_dms_viz/blob/main/tests/SARS2-RBD-REGN-DMS/input/REGN_escape.csv) containing scores detailing the degree of antibody escape from the `REGN mAb Cocktail`. We've also specified a [sitemap](https://github.com/dms-viz/configure_dms_viz/blob/main/tests/SARS2-RBD-REGN-DMS/sitemap/sitemap.csv) that tells the tool how sites in your data correspond to the sites in the protein structure. Then, we specified that we wanted to use the protein structure `6XDG` from the [RSCB PDB](https://www.rcsb.org/) website and only display our data on chain `E` of that structure. The column in the input data that contains our data is called `mut_escape`, and we have different values of `mut_escape` for the same mutations depending on the `condition` (in this case, the condition refers to escape from each antibody in the cocktail).
 
 The result of this command should be a message printed to the terminal that looks like this:
 
-**Output**
+### Output
 
 ```md
 Formatting data for visualization using the 'mut_escape' column from 'tests/SARS2-RBD-REGN-DMS/input/REGN_escape.csv'...
@@ -137,7 +140,8 @@ To upload a local file, you simply click on the `Upload Data` section and choose
 Since the `.json` file created above should now be stored locally on your machine, you can upload this file using this approach.
 
 ### Remote
-Alternatively, if your raw `.json` file is hosted somewhere online – like on GitHub, for example – you can provide the link to this file by clicking on the `Remote` button under the `Upload Data` section.
+
+Alternatively, if your `.json` specification file is hosted somewhere online – like on GitHub, for example – you can provide the link to this file by clicking on the `Remote` button under the `Upload Data` section.
 
 <div align="center">
   <img src="/assets/remote-upload-example.png" alt="Remote Upload" />
@@ -149,4 +153,6 @@ You can try it yourself by pasting the following link into the URL text box:
 https://raw.githubusercontent.com/dms-viz/configure_dms_viz/main/tests/SARS2-RBD-REGN-DMS/output/SARS2-RBD-REGN-DMS.json
 ```
 
-This approach has some advantages. For example, after providing a link to your data, this link is saved in the URL, allowing you to share a view of **`dms-viz`** with the data pre-loaded and ready to view. For more details on using the web-based interface of **`dms-viz`** including hosting, interacting, and sharing your files, check out the [interaction reference](/visualizing-data/web-tool-api/).
+This approach has some advantages. **`dms-viz`** includes the link to your remotely stored specification in the URL, allowing you to share your visualization with the data pre-loaded. Another advantage of this approach is that changes made to the appearance of **`dms-viz`** are saved in the URL as well.
+
+For more details on using the web-based interface of **`dms-viz`** including hosting, interacting, and sharing your files, check out the [interaction reference](/visualizing-data/web-tool-api/).

introduction/what-is-dms-viz/index.md

@@ -1,18 +1,22 @@
-# What is dms-viz?
+# What is `dms-viz`?
 
-Hi there 👋, if you've got some mutation-level data that you want to view on an interactive 3D protein structure, you're in the right place! **`dms-viz`** is a tool that helps you take quantitative data associated with mutations to a protein and analyze that data using intuitive visual summaries in the context of an interactive 3D protein structure. Visualizations created with **`dms-viz`** are intended to be _flexible_, _customizable_, and _shareable_.
+Hi there 👋, if you have mutation-based data you want to view on an interactive 3D protein structure, you're in the right place! **`dms-viz`** is a tool that helps you take quantitative data associated with mutations to a protein and analyze that data with intuitive visual summaries and an interactive 3D protein structure. Visualizations created with **`dms-viz`** are _flexible_, _customizable_, and _shareable_.
 
 ::: tip Ready to use the tool?
-You can skip to the [Quickstart](/introduction/getting-started/) to learn how to prepare your data, or you can see what the visualization tool looks like [here](https://dms-viz.github.io/).
+Skip to the [Getting Started](/introduction/getting-started/) guide to learn how to prepare your data.
 :::
 
 ## Purpose
 
-Understanding how mutations impact a protein's functions is valuable for many types of biological questions. High-throughput techniques such as deep-mutational scanning (DMS) have greatly expanded the number of mutation-function datasets. For instance, DMS has been used to determine how mutations to viral proteins affect antibody escape, receptor affinity, and essential functions such as viral genome transcription and replication.
+Many biological questions require a thorough understanding of how mutations to a protein impact its functions. High-throughput techniques such as deep-mutational scanning (DMS) have greatly expanded the number of mutation-function datasets. For instance, DMS has been used to determine how mutations to viral proteins affect antibody escape, receptor affinity, and essential functions such as viral genome transcription and replication.
 
 The mutation-based data generated by these approaches is often best understood in the context of a protein’s 3D structure; for instance, to assess questions like how mutations that affect antibody escape relate to the physical antibody binding epitope on the protein. However, current approaches for visualizing mutation data in the context of a protein’s structure are often cumbersome and require multiple steps and software. To streamline the visualization of mutation-associated data in the context of a protein structure, we developed a web-based tool, **`dms-viz`**. With **`dms-viz`**, users can straightforwardly visualize mutation-based data such as those from DMS experiments in the context of a 3D protein model in an interactive format.
 
-## Why use dms-viz?
+::: tip Interested in what the visualizations look like?
+Check out these [examples](/visualizing-data/vignettes/) to see `dms-viz` in action.
+:::
+
+## Why use `dms-viz`?
 
 - **Flexible Inputs**
 
@@ -26,12 +30,12 @@ The mutation-based data generated by these approaches is often best understood i
 
   If your data is hosted online (e.g. in a [GitHub](https://github.com/) repository), you can share your data with URLs that automatically load the visualization while keeping your settings. However, if you don't want to host your data online, you can still use **`dms-viz`** with locally stored `.json` files.
 
-## Development
+## Contributing to `dms-viz`
 
 **`dms-viz`** has two components:
 
 1. A command line interface (CLI) for formatting data that was written in `Python` using the [click](https://click.palletsprojects.com/en/8.1.x/) API.
-2. A web-based visualization tool written in 'vanilla' `Javascript` using primarily the libraries [D3.js](https://d3js.org/) for making the visualizations and [NGL.js](https://nglviewer.org/#page-top) for creating interactive molecular structures.
+2. A web-based visualization tool written in `Javascript` using primarily the libraries [D3.js](https://d3js.org/) for making the visualizations and [NGL.js](https://nglviewer.org/#page-top) for creating interactive molecular structures.
 
 If you're interested in contributing, check out the [Contributing Guide](/project-info/contributing-guide/) for details.
 
@@ -40,5 +44,5 @@ If you're interested in contributing, check out the [Contributing Guide](/projec
 If you end up using **`dms-viz`** in your paper, please cite us!
 
 ```md
-TODO: Add citation here
+Citation pending...
 ```