Skip to content

Commit

Permalink
Update 'Getting Started' with recent example
Browse files Browse the repository at this point in the history
  • Loading branch information
WillHannon-MCB committed Apr 2, 2024
1 parent 666e7fb commit c85c046
Showing 1 changed file with 21 additions and 25 deletions.
46 changes: 21 additions & 25 deletions introduction/getting-started/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,50 +79,46 @@ The remaining arguments are all _optional_ and configure the look and interactio
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/).
:::

Now, let's use `configure-dms-viz` on some example data. 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.
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**

```bash
configure-dms-viz format \
--name LyCoV-1404 \
--input tests/sars2/escape/LyCoV-1404_avg.csv \
--sitemap tests/sars2/site_numbering_map.csv \
--metric escape_mean \
--structure 6xr8 \
--output tests/sars2/output/LyCoV-1404.json \
--metric-name Escape \
--join-data tests/sars2/muteffects_observed.csv \
--filter-cols "{'effect': 'Functional Effect', 'times_seen': 'Times Seen'}" \
--tooltip-cols "{'times_seen': '# Obsv', 'effect': 'Func Eff.'}"
--name "REGN mAb Cocktail" \
--input tests/SARS2-RBD-REGN-DMS/input/REGN_escape.csv \
--sitemap tests/SARS2-RBD-REGN-DMS/sitemap/sitemap.csv \
--metric "mut_escape" \
--metric-name "Escape" \
--structure "6XDG" \
--included-chains "E" \
--condition "condition" \
--condition-name "Antibody" \
--output ./REGN_escape.json
```

Here, we've specified that we want the dataset to be called `LyCoV-1404` and we've pointed to the file location of the [input data](https://github.com/dms-viz/configure_dms_viz/blob/main/tests/sars2/escape/LyCoV-1404_avg.csv) and [sitemap](https://github.com/dms-viz/configure_dms_viz/blob/main/tests/sars2/site_numbering_map.csv). In addition, we've specified that we want to use the protein structure `6xr8` from the [RSCB PDB](https://www.rcsb.org/) and that we want to visualize the `escape_mean` column of the input dataset. We've also specified some _optional_ arguments including [additional data](/preparing-data/command-line-api/#join-data), [filters](/preparing-data/command-line-api/#filter-cols), [tooltips](/preparing-data/command-line-api/#tooltip-cols), and the [name](/preparing-data/command-line-api/#name) we want to show up for the metric we're visualizing.
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).

The result of this command should be a message printed to the terminal that looks like this:

**Output**

```md
Formatting data for visualization using the 'escape_mean' column from 'tests/sars2/escape/LyCoV-1404_avg.csv'...
Formatting data for visualization using the 'mut_escape' column from 'tests/SARS2-RBD-REGN-DMS/input/REGN_escape.csv'...

Joining data from 1 dataframe.

Using sitemap from 'tests/sars2/site_numbering_map.csv'.
Using sitemap from 'tests/SARS2-RBD-REGN-DMS/sitemap/sitemap.csv'.

'protein_site' column is not present in the sitemap. Assuming that the reference sites correspond to protein sites.

Warning: duplicate column names exist between mutation dataframe and join dataframe. Dropping ['times_seen'] from join data.

About 85.76% of the wildtype residues in the data match the corresponding residues in the structure.
About 11.96% of the data sites are missing from the structure.
About 95.98% of the wildtype residues in the data match the corresponding residues in the structure.
About 4.02% of the data sites are missing from the structure.

Success! The visualization json was written to 'tests/sars2/output/LyCoV-1404.json'
Success! The visualization JSON was written to './REGN_escape.json'
```

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 message provides some information from the `configure-dms-viz format` command for your dataset. In addition to this message, there will be a `.json` file located where you specified the output path.

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 arguments along with an optional description of the datasets. For more details on combining datasets, check out the [API](/preparing-data/command-line-api/).
This is how you 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 which takes a list of `.json` files as 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/).

Expand All @@ -147,10 +143,10 @@ Alternatively, if your raw `.json` file is hosted somewhere online – like on
<img src="/assets/remote-upload-example.png" alt="Remote Upload" />
</div>

You can try yourself by pasting the following link into the URL text box:
You can try it yourself by pasting the following link into the URL text box:

```md
https://raw.githubusercontent.com/dms-viz/configure_dms_viz/main/tests/sars2/output/sars2.json
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/).

0 comments on commit c85c046

Please sign in to comment.