Update documentation to reflect split commands

introduction/getting-started/index.md

@@ -2,7 +2,7 @@
 
 ## 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 specifcy 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 a visualization. Below are some quickstart instructions to get you oriented.
+Using **`dms-viz`** involves two steps. First, using a command line tool called [`configure-dms-viz`](https://pypi.org/project/configure-dms-viz/), you specifcy 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.
 
 ::: tip Want to Skip Ahead?
 If you're insterested 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/).
@@ -46,16 +46,16 @@ You should see the help message for the tool printed to the terminal.
 
 ## 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 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`.
 
 ::: tip Looking for more details?
-For a detailed explaination of the features of `configure_dms_viz` as well as the command line API check out the reference [here](/preparing-data/command-line-api/).
+For a detailed explaination of the features of `configure_dms_viz` check out the reference [here](/preparing-data/command-line-api/).
 :::
 
-To format your data, you execute the `configure-dms-viz` command with the required and optional arguments as needed:
+`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:
 
 ```bash
-configure-dms-viz \
+configure-dms-viz format \
     --name <experiment_name> \
     --input <input_csv> \
     --metric <metric_column> \
@@ -85,7 +85,7 @@ Now, let's use `configure-dms-viz` on some example data. This data is included i
 **Input**
 
 ```bash
-configure-dms-viz \
+configure-dms-viz format \
    --name LyCoV-1404 \
    --input tests/sars2/escape/LyCoV-1404_avg.csv \
    --sitemap tests/sars2/site_numbering_map.csv \
@@ -121,7 +121,11 @@ About 11.96% of the data sites are missing from the structure.
 Success! The visualization json was written to 'tests/sars2/output/LyCoV-1404.json'
 ```
 
-This message provides some information about the `configure-dms-viz` run on your dataset. In addition to this message, there should be a `.json` file located where you specified the output path ([`tests/sars2/output/LyCoV-1404.json`](https://github.com/dms-viz/configure_dms_viz/blob/main/tests/sars2/output/LyCoV-1404.json)). In the next section, you'll take this `.json` visualization file and visualize your data with [**`dms-viz`**](https://dms-viz.github.io/).
+This message provides some information about the `configure-dms-viz format` run on your dataset. In addition to this message, there should be a `.json` file located where you specified the output path ([`tests/sars2/output/LyCoV-1404.json`](https://github.com/dms-viz/configure_dms_viz/blob/main/tests/sars2/output/LyCoV-1404.json)).
+
+This is how you can use `configure-dms-viz` to format a single dataset. You can optionally combine multiple datasets into a single `.json` specification file using the `configure-dms-viz join` command. this command takes a list of `.json` files as an arguments along with an optional description of the datasets. For more details on combining datasets, check out the [API](/preparing-data/command-line-api).
+
+For now, since we're only visualizing a single dataset, we can skip this step. In the next section, you'll take this `.json` visualization file and visualize your data with [**`dms-viz`**](https://dms-viz.github.io/).
 
 ## Visualizing
 
@@ -151,4 +155,4 @@ You can try yourself by pasting the following link into the URL text box:
 https://raw.githubusercontent.com/dms-viz/configure_dms_viz/main/tests/sars2/output/sars2.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. Also, this approach allows you to proivde a markdown description (also hosted remotely) of the datasets. For more details on using the web-based portion 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. 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/).

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

@@ -1,30 +1,30 @@
 # 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 suite of tools that help you take quantitative data associated with mutations to a protein and analyze that data using intutive visual summaries in the context of a 3D protein structure. Visualizations created with **`dms-viz`** are intended to be _flexible_, _customizable_, and _shareable_.
+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 intutive visual summaries in the context of an interactive 3D protein structure. Visualizations created with **`dms-viz`** are intended to be _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 own data, or you can see what the visualization tool looks like [here](https://dms-viz.github.io/).
 :::
 
 ## Purpose
 
-Understanding the repercussions of mutations on a protein's structure, function, and evolutionary trajectory is invaluable, especially in the realm of infectious disease research. The advancement of high-throughput techniques, such as deep-mutational scanning (_the 'DMS' which lends this project its name_), coupled with the expansion of viral surveillance sequencing, has massivley increased our access to data on the impacts of various mutations in proteins across different contexts. Increasingly, studies leverage this pool of data to accomplish a range of objectives, from mapping antibody and serum escape by viral glycoproteins \[[1]()\] to determining the influence of numerous mutations on viral fitness \[[2]()\], inferring viral fitness from extensive phylogenies \[[3]()\], and understanding the fluctuating effects of mutations as a result of epistasis \[[4]()\].
+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.
 
-To further facilitate the analysis of mutation-level data, we have developed **`dms-viz`**, envisioned as the successor to the remarkable tool [**`dms-view`**](https://dms-view.github.io/). The latter pioneered the integration of summary visualizations with interactive 3D protein structures, streamlining the workflow for analyzing mutation-level data. Building on the strengths of **`dms-view`**, we aimed to create a tool that was _adaptable_ to various types of input data, offering enhanced _customization_ options through the addition of filters and other manipulations. Furthermore, we preserved the _shareable_ links that were a feature of dms-view, while also incorporating the functionality to utilize privately stored local data, enhancing both accessibility and privacy.
+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 softwares. 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?
 
 - **Flexible Inputs**
 
-  Utilize our command-line tool, `configure-dms-viz`, to streamline data formatting effortlessly. It facilitates the integration of data from varied sources into a singular, universal `.json` specification file. Moreover, this tool makes it easy to incorporate additional datasets from different locations, stipulate custom filters and tooltips, and identify common errors.
+  Our command-line tool, `configure-dms-viz`, helps streamline data formatting by facillitating the integration of data from different sources into a singular, universal `JSON` specification file. Moreover, `configure-dms-viz` helps you define custom filters and tooltips, and identify common errors.
 
 - **Customizable Visualizations**
 
-  Experience unparalleled customization with your visualizations. You have the liberty to select the appearance of the protein structure, visualize multiple conditions per dataset, and extend functionalities with custom filters, tooltips, and beyond.
+  We've designed **`dms-viz`** with customization in mind. You can tailor the appearance of the protein structure to fit your needs. Futhermore, you can extend the functionality of the tool with custom filters, tooltips, colors, and more.
 
 - **Shareable URLs**
 
-  Should your data be hosted online (like in a [GitHub](https://github.com/) repository), sharing becomes a breeze with URLs that can automatically load the visualizations. Moreover, these URLs retain the configuration settings of your visualization, enhancing the sharing experience. However, if you don't want to host your data online, you can still use **`dms-viz`** on your local files.
+  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
 

preparing-data/command-line-api/index.md

@@ -1,13 +1,13 @@
-# Command Line Interface
+# Command Line API
 
 ## Basic Usage
 
-`configure_dms_viz` is a command-line tool designed to create a `.JSON` format specification file for [**`dms-viz`**](https://dms-viz.github.io/). 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`** 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`**](https://dms-viz.github.io/). 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`** for interactive visualization of your data. Below is an overview of the process of using `configure_dms_viz`.
 
-To format your data, you execute the `configure-dms-viz` command with the required and optional arguments as needed:
+`configure-dms-viz` has two commands; `format` and `join`. To format your data, you execute the `configure-dms-viz format` command with the required and optional arguments as needed:
 
 ```bash
-configure-dms-viz \
+configure-dms-viz format \
     --name <experiment_name> \
     --input <input_csv> \
     --metric <metric_column> \
@@ -17,13 +17,24 @@ configure-dms-viz \
     [optional_arguments]
 ```
 
-## Command Line API
+This creates a single dataset that can be loaded into **`dms-viz`**. However, in some cases, you might want to visualize multiple datasets simultaneously. To do this, you use the `configure-dms-viz join` command. The `join` command takes a list of formatted `.json` files and combines them into a single `.json` specification file containing each dataset. Optionally, you can also provide a description of the file by specifying the path to a `.md` file with your desired description:
+
+```bash
+configure-dms-viz join \
+    --input <input_jsons> \
+    --output <output_json> \
+    --description <markdown_description>
+```
+
+## `configure-dms-viz format`
+
+_This subcommand formats your data for **`dms-viz`**. Below is a description of each arguement._
 
 - ### `--input`
 
   `<string>`
 
-  Path to a CSV file with site- and mutation-level data to visualize on a protein structure. [See details here](/preparing-data/data-requirements/) for required columns and format.
+  Path to a `.csv` file with site- and mutation-level data to visualize on a protein structure. [See details here](/preparing-data/data-requirements/) for required columns and format.
 
 - ### `--name`
 
@@ -35,7 +46,7 @@ configure-dms-viz \
 
   `<string>`
 
-  Path to a CSV file containing a map between reference sites in the experiment and sequential sites. [See details here](/preparing-data/data-requirements/) for required columns and format.
+  Path to a `.csv` file containing a map between reference sites in the experiment and sequential sites. [See details here](/preparing-data/data-requirements/) for required columns and format.
 
 - ### `--metric`
 
@@ -53,7 +64,7 @@ configure-dms-viz \
 
   `<string>`
 
-  Path to save the \*.json file containing the data for the visualization tool.
+  Path to save the `\*.json` file containing the data for the visualization tool.
 
 - ### `--condition`
 
@@ -77,7 +88,7 @@ configure-dms-viz \
 
   `<list>`
 
-  A comma separated list of CSV file with data to join to the visualization data. This data can then be used in the visualization tooltips or filters. [See details here](/preparing-data/data-requirements/) for formatting requirements.
+  A comma separated list of `.csv` file with data to join to the visualization data. This data can then be used in the visualization tooltips or filters. [See details here](/preparing-data/data-requirements/) for formatting requirements.
 
 - ### `--tooltip-cols`
 
@@ -150,3 +161,26 @@ configure-dms-viz \
   `<string>`
 
   A short title to appear above the plot.
+
+## `configure-dms-viz join`
+
+_This subcommand joins multiple formatted `.json` datasets into one that you can then visualize with **`dms-viz`**. Below is a description of each arguement._
+
+- ### `--input`
+
+  `<list>`
+
+  A comma separated list of paths to the `.json` visualization files created by `configure-dms-viz format`. I.e. `--input path/to/my/specification_1.json, path/to/my/specification_2.json, path/to/my/specification_3.json`
+
+- ### `--output`
+
+  `<string>`
+
+  Path to save the joined `\*.json` file for the visualization tool.
+
+
+- ### `--description`
+
+  `<string>`
+
+  Path to a `markdown` file describing your dataset.