From 35dc0b028af75d500159b1c454efc7ac04741708 Mon Sep 17 00:00:00 2001 From: WillHannon-MCB Date: Fri, 17 May 2024 20:17:48 +0000 Subject: [PATCH] deploy: 1dd41e614686990d419ed2e23f1bfb436330d9de --- 404.html | 2 +- README.html | 2 +- ...=> preparing-data_command-line-api_index.md.1a1ec969.js} | 2 +- ...eparing-data_command-line-api_index.md.1a1ec969.lean.js} | 0 hashmap.json | 2 +- index.html | 2 +- introduction/getting-started/index.html | 2 +- introduction/what-is-dms-viz/index.html | 2 +- preparing-data/command-line-api/index.html | 6 +++--- preparing-data/data-requirements/index.html | 2 +- project-info/contact-info/index.html | 2 +- project-info/contributing-guide/index.html | 2 +- visualizing-data/vignettes/index.html | 2 +- visualizing-data/web-tool-api/index.html | 2 +- 14 files changed, 15 insertions(+), 15 deletions(-) rename assets/{preparing-data_command-line-api_index.md.0c4c3b00.js => preparing-data_command-line-api_index.md.1a1ec969.js} (76%) rename assets/{preparing-data_command-line-api_index.md.0c4c3b00.lean.js => preparing-data_command-line-api_index.md.1a1ec969.lean.js} (100%) diff --git a/404.html b/404.html index 4aef039..b1afdff 100644 --- a/404.html +++ b/404.html @@ -15,7 +15,7 @@
dms-viz

Appearance

404

PAGE NOT FOUND

But if you don't change your direction, and if you keep looking, you may end up where you are heading.
Take me home
- + \ No newline at end of file diff --git a/README.html b/README.html index f67d745..824e3c5 100644 --- a/README.html +++ b/README.html @@ -20,7 +20,7 @@
dms-viz

Appearance

dms-viz-docs ​

This repo contains the code for the website hosting the documentation for dms-viz.github.io, both the configuration tool and the main visualization tool.

Developing ​

These docs were created with VitePress. To develop the docs, follow the instructions below:

  1. Clone the repository
bash
git clone git@github.com:dms-viz/dms-viz-docs.git
 cd dms-viz-docs
git clone git@github.com:dms-viz/dms-viz-docs.git
 cd dms-viz-docs
  1. Install node packages
bash
npm install
npm install
  1. Start the development server
bash
npx vitepress dev
npx vitepress dev

Now, you should be able to see the website built locally. Changes to the website should be automatically reflected on the page. For details on the routing structure and how to develop a VitePress site, go to the documentation for VitePress.

Deploying ​

The docs are hosted on GitHub pages via a specific gh-pages branch and builds are automated using GitHub Actions via this deployment script. The website will build on pull requests and pushes to the main branch.

- + \ No newline at end of file diff --git a/assets/preparing-data_command-line-api_index.md.0c4c3b00.js b/assets/preparing-data_command-line-api_index.md.1a1ec969.js similarity index 76% rename from assets/preparing-data_command-line-api_index.md.0c4c3b00.js rename to assets/preparing-data_command-line-api_index.md.1a1ec969.js index 51f1b25..7ba333d 100644 --- a/assets/preparing-data_command-line-api_index.md.0c4c3b00.js +++ b/assets/preparing-data_command-line-api_index.md.1a1ec969.js @@ -1 +1 @@ -import{_ as e,o,c as a,Q as t}from"./chunks/framework.9ad6f510.js";const f=JSON.parse('{"title":"Command Line API","description":"","frontmatter":{},"headers":[],"relativePath":"preparing-data/command-line-api/index.md","filePath":"preparing-data/command-line-api/index.md"}'),s={name:"preparing-data/command-line-api/index.md"},n=t('

Command Line API ​

You'll need to use the command line tool configure-dms-viz to prepare your data for dms-viz. Follow the instructions in Getting Started to install configure-dms-viz on your operating system.

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 for interactive visualization of your data. Below is an overview of the process of using configure-dms-viz.

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 format \\\n    --name <experiment_name> \\\n    --input <input_csv> \\\n    --metric <metric_column> \\\n    --structure <pdb_structure> \\\n    --output <output_json> \\\n    [optional_arguments]
configure-dms-viz format \\\n    --name <experiment_name> \\\n    --input <input_csv> \\\n    --metric <metric_column> \\\n    --structure <pdb_structure> \\\n    --output <output_json> \\\n    [optional_arguments]

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 add a markdown description of your joined datasets by specifying the path to a .md file with your desired description:

bash
configure-dms-viz join \\\n    --input <input_jsons> \\\n    --output <output_json> \\\n    --description <markdown_description>
configure-dms-viz join \\\n    --input <input_jsons> \\\n    --output <output_json> \\\n    --description <markdown_description>

Advanced Usage ​

This is the most basic usage of configure-dms-viz; however, configure-dms-viz is a flexible formatting tool that provides many options for customizing your analysis. In addition to the description of the command line API below, we'll detail some highlights of the customization available through configure-dms-viz.

Custom Filters ​

configure-dms-viz allows you to specify quantitative columns in your input data to use as dynamic filters in dms-viz. The columns you specify will populate sliders in the sidebar under "Filters". By dragging the slider, you filter out the mutations or sites in the visualization with values less than the selected value for the column you specify.

To add filters with configure-dms-viz, specify quantitative columns using the --filter-cols flag by providing a dictionary that establishes your chosen columns and the name that will appear in the visualization (i.e. "{'effect': 'Functional Effect', 'times_seen': 'Times Seen'}"). In this example, the columns that are used as filters are effect and times_seen in the input data, and the names that will label the filters are Functional Effect and Times Seen.

In addition to specifying filters, you can set their default value and limits with the --filter-limits flag by providing a dictionary formatted like so: "{'effect': [min, value, max], 'times_seen': [min, value, max]}". You can only specify the min and max (i.e. [min, max]), but it's highly recommended that you set a default value for the filter that makes sense for your data.

Check out vignette #2 in the Vignettes for an example visualization that uses filters.

Custom Tooltips ​

In a similar process to adding custom filters, configure-dms-viz allows you to specify columns to include as tooltips. Tooltips are shown for each mutation in your dataset and will appear when you center your mouse over a mutation in the heatmap plot on the left of the visualization.

Use the --tooltip-cols flag to specify columns that should provide information through tooltips by providing a dictionary like so: "{'times_seen': '# Obsv', 'effect': 'Func Eff.'}", where the key is the column's name and the value is the label as it should appear in the tooltip.

configure-dms-viz format ​

This subcommand formats your data for dms-viz. Below is a description of each argument.

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 argument.

WARNING

Make sure that you're joining files with unique values for the dataset name.

',25),i=[n];function l(c,r,p,d,h,u){return o(),a("div",null,i)}const y=e(s,[["render",l]]);export{f as __pageData,y as default}; +import{_ as e,o,c as a,Q as t}from"./chunks/framework.9ad6f510.js";const f=JSON.parse('{"title":"Command Line API","description":"","frontmatter":{},"headers":[],"relativePath":"preparing-data/command-line-api/index.md","filePath":"preparing-data/command-line-api/index.md"}'),s={name:"preparing-data/command-line-api/index.md"},n=t('

Command Line API ​

You'll need to use the command line tool configure-dms-viz to prepare your data for dms-viz. Follow the instructions in Getting Started to install configure-dms-viz on your operating system.

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 for interactive visualization of your data. Below is an overview of the process of using configure-dms-viz.

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 format \\\n    --name <experiment_name> \\\n    --input <input_csv> \\\n    --metric <metric_column> \\\n    --structure <pdb_structure> \\\n    --output <output_json> \\\n    [optional_arguments]
configure-dms-viz format \\\n    --name <experiment_name> \\\n    --input <input_csv> \\\n    --metric <metric_column> \\\n    --structure <pdb_structure> \\\n    --output <output_json> \\\n    [optional_arguments]

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 add a markdown description of your joined datasets by specifying the path to a .md file with your desired description:

bash
configure-dms-viz join \\\n    --input <input_jsons> \\\n    --output <output_json> \\\n    --description <markdown_description>
configure-dms-viz join \\\n    --input <input_jsons> \\\n    --output <output_json> \\\n    --description <markdown_description>

Advanced Usage ​

This is the most basic usage of configure-dms-viz; however, configure-dms-viz is a flexible formatting tool that provides many options for customizing your analysis. In addition to the description of the command line API below, we'll detail some highlights of the customization available through configure-dms-viz.

Custom Filters ​

configure-dms-viz allows you to specify quantitative columns in your input data to use as dynamic filters in dms-viz. The columns you specify will populate sliders in the sidebar under "Filters". By dragging the slider, you filter out the mutations or sites in the visualization with values less than the selected value for the column you specify.

To add filters with configure-dms-viz, specify quantitative columns using the --filter-cols flag by providing a dictionary that establishes your chosen columns and the name that will appear in the visualization (i.e. "{'effect': 'Functional Effect', 'times_seen': 'Times Seen'}"). In this example, the columns that are used as filters are effect and times_seen in the input data, and the names that will label the filters are Functional Effect and Times Seen.

In addition to specifying filters, you can set their default value and limits with the --filter-limits flag by providing a dictionary formatted like so: "{'effect': [min, value, max], 'times_seen': [min, value, max]}". You can only specify the min and max (i.e. [min, max]), but it's highly recommended that you set a default value for the filter that makes sense for your data.

Check out vignette #2 in the Vignettes for an example visualization that uses filters.

Custom Tooltips ​

In a similar process to adding custom filters, configure-dms-viz allows you to specify columns to include as tooltips. Tooltips are shown for each mutation in your dataset and will appear when you center your mouse over a mutation in the heatmap plot on the left of the visualization.

Use the --tooltip-cols flag to specify columns that should provide information through tooltips by providing a dictionary like so: "{'times_seen': '# Obsv', 'effect': 'Func Eff.'}", where the key is the column's name and the value is the label as it should appear in the tooltip.

configure-dms-viz format ​

This subcommand formats your data for dms-viz. Below is a description of each argument.

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 argument.

WARNING

Make sure that you're joining files with unique values for the dataset name.

',25),i=[n];function l(c,r,p,d,h,u){return o(),a("div",null,i)}const y=e(s,[["render",l]]);export{f as __pageData,y as default}; diff --git a/assets/preparing-data_command-line-api_index.md.0c4c3b00.lean.js b/assets/preparing-data_command-line-api_index.md.1a1ec969.lean.js similarity index 100% rename from assets/preparing-data_command-line-api_index.md.0c4c3b00.lean.js rename to assets/preparing-data_command-line-api_index.md.1a1ec969.lean.js diff --git a/hashmap.json b/hashmap.json index 614f1fc..5b34fad 100644 --- a/hashmap.json +++ b/hashmap.json @@ -1 +1 @@ -{"readme.md":"005f15fd","preparing-data_data-requirements_index.md":"717b07de","index.md":"8da19304","introduction_what-is-dms-viz_index.md":"88742ba4","visualizing-data_web-tool-api_index.md":"5e7333ff","preparing-data_command-line-api_index.md":"0c4c3b00","introduction_getting-started_index.md":"e66d30c7","visualizing-data_vignettes_index.md":"bbf0e4e1","project-info_contact-info_index.md":"836345db","project-info_contributing-guide_index.md":"a0189d70"} +{"visualizing-data_web-tool-api_index.md":"5e7333ff","project-info_contact-info_index.md":"836345db","index.md":"8da19304","project-info_contributing-guide_index.md":"a0189d70","visualizing-data_vignettes_index.md":"bbf0e4e1","introduction_getting-started_index.md":"e66d30c7","preparing-data_data-requirements_index.md":"717b07de","readme.md":"005f15fd","introduction_what-is-dms-viz_index.md":"88742ba4","preparing-data_command-line-api_index.md":"1a1ec969"} diff --git a/index.html b/index.html index 9a8f761..9ed28a6 100644 --- a/index.html +++ b/index.html @@ -18,7 +18,7 @@
dms-viz

Appearance

dms-viz.github.io

Visualize mutation-level data on a 3D protein structure with a flexible web-based toolkit

Getting Started
Vignettes
Use the Tool!
📈

Flexible Inputs

Our command line tool helps you format your data for visualization.

🛠️

Lots of Customization

Customize how your data is visualized and the look of the protein structure.

🔗

Shareable URLs

Share your visualization in papers or with collaborators via URL links.

- + \ No newline at end of file diff --git a/introduction/getting-started/index.html b/introduction/getting-started/index.html index 1ae568c..1f507cf 100644 --- a/introduction/getting-started/index.html +++ b/introduction/getting-started/index.html @@ -69,7 +69,7 @@ About 4.02% of the data sites are missing from the structure. Success! The visualization JSON was written to './REGN_escape.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 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.

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.

Visualizing ​

There are two ways to upload data into dms-viz. You can either upload a local specification file from your computer, or you can provide a link to a remote specification file hosted somewhere like GitHub.

Local ​

To upload a local file, you simply click on the Upload Data section and choose a file from your machine.

Local Upload

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 .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.

Remote Upload

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-RBD-REGN-DMS/output/SARS2-RBD-REGN-DMS.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. 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.

- + \ No newline at end of file diff --git a/introduction/what-is-dms-viz/index.html b/introduction/what-is-dms-viz/index.html index ceaffd0..adef7a1 100644 --- a/introduction/what-is-dms-viz/index.html +++ b/introduction/what-is-dms-viz/index.html @@ -18,7 +18,7 @@
dms-viz

Appearance

What is dms-viz? ​

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.

Ready to use the tool?

Skip to the Getting Started guide to learn how to prepare your data.

Purpose ​

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.

Interested in what the visualizations look like?

Check out these examples to see dms-viz in action.

Why use dms-viz? ​

  • Flexible Inputs

    Our command-line tool, configure-dms-viz, helps streamline data formatting by facilitating 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

    We've designed dms-viz with customization in mind. You can tailor the appearance of the protein structure to fit your needs. Furthermore, you can extend the functionality of the tool with custom filters, tooltips, colors, and more.

  • Shareable URLs

    If your data is hosted online (e.g. in a GitHub 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.

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 API.
  2. A web-based visualization tool written in Javascript using primarily the libraries D3.js for making the visualizations and NGL.js for creating interactive molecular structures.

If you're interested in contributing, check out the Contributing Guide for details.

Citation ​

If you end up using dms-viz in your paper, please cite us!

md
Citation pending...
Citation pending...
- + \ No newline at end of file diff --git a/preparing-data/command-line-api/index.html b/preparing-data/command-line-api/index.html index 6cf9399..7f1d975 100644 --- a/preparing-data/command-line-api/index.html +++ b/preparing-data/command-line-api/index.html @@ -11,7 +11,7 @@ - + @@ -35,8 +35,8 @@ --description <markdown_description>
configure-dms-viz join \
     --input <input_jsons> \
     --output <output_json> \
-    --description <markdown_description>

Advanced Usage ​

This is the most basic usage of configure-dms-viz; however, configure-dms-viz is a flexible formatting tool that provides many options for customizing your analysis. In addition to the description of the command line API below, we'll detail some highlights of the customization available through configure-dms-viz.

Custom Filters ​

configure-dms-viz allows you to specify quantitative columns in your input data to use as dynamic filters in dms-viz. The columns you specify will populate sliders in the sidebar under "Filters". By dragging the slider, you filter out the mutations or sites in the visualization with values less than the selected value for the column you specify.

To add filters with configure-dms-viz, specify quantitative columns using the --filter-cols flag by providing a dictionary that establishes your chosen columns and the name that will appear in the visualization (i.e. "{'effect': 'Functional Effect', 'times_seen': 'Times Seen'}"). In this example, the columns that are used as filters are effect and times_seen in the input data, and the names that will label the filters are Functional Effect and Times Seen.

In addition to specifying filters, you can set their default value and limits with the --filter-limits flag by providing a dictionary formatted like so: "{'effect': [min, value, max], 'times_seen': [min, value, max]}". You can only specify the min and max (i.e. [min, max]), but it's highly recommended that you set a default value for the filter that makes sense for your data.

Check out vignette #2 in the Vignettes for an example visualization that uses filters.

Custom Tooltips ​

In a similar process to adding custom filters, configure-dms-viz allows you to specify columns to include as tooltips. Tooltips are shown for each mutation in your dataset and will appear when you center your mouse over a mutation in the heatmap plot on the left of the visualization.

Use the --tooltip-cols flag to specify columns that should provide information through tooltips by providing a dictionary like so: "{'times_seen': '# Obsv', 'effect': 'Func Eff.'}", where the key is the column's name and the value is the label as it should appear in the tooltip.

configure-dms-viz format ​

This subcommand formats your data for dms-viz. Below is a description of each argument.

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 argument.

WARNING

Make sure that you're joining files with unique values for the dataset name.

- + --description <markdown_description>

Advanced Usage ​

This is the most basic usage of configure-dms-viz; however, configure-dms-viz is a flexible formatting tool that provides many options for customizing your analysis. In addition to the description of the command line API below, we'll detail some highlights of the customization available through configure-dms-viz.

Custom Filters ​

configure-dms-viz allows you to specify quantitative columns in your input data to use as dynamic filters in dms-viz. The columns you specify will populate sliders in the sidebar under "Filters". By dragging the slider, you filter out the mutations or sites in the visualization with values less than the selected value for the column you specify.

To add filters with configure-dms-viz, specify quantitative columns using the --filter-cols flag by providing a dictionary that establishes your chosen columns and the name that will appear in the visualization (i.e. "{'effect': 'Functional Effect', 'times_seen': 'Times Seen'}"). In this example, the columns that are used as filters are effect and times_seen in the input data, and the names that will label the filters are Functional Effect and Times Seen.

In addition to specifying filters, you can set their default value and limits with the --filter-limits flag by providing a dictionary formatted like so: "{'effect': [min, value, max], 'times_seen': [min, value, max]}". You can only specify the min and max (i.e. [min, max]), but it's highly recommended that you set a default value for the filter that makes sense for your data.

Check out vignette #2 in the Vignettes for an example visualization that uses filters.

Custom Tooltips ​

In a similar process to adding custom filters, configure-dms-viz allows you to specify columns to include as tooltips. Tooltips are shown for each mutation in your dataset and will appear when you center your mouse over a mutation in the heatmap plot on the left of the visualization.

Use the --tooltip-cols flag to specify columns that should provide information through tooltips by providing a dictionary like so: "{'times_seen': '# Obsv', 'effect': 'Func Eff.'}", where the key is the column's name and the value is the label as it should appear in the tooltip.

configure-dms-viz format ​

This subcommand formats your data for dms-viz. Below is a description of each argument.

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 argument.

WARNING

Make sure that you're joining files with unique values for the dataset name.

+ \ No newline at end of file diff --git a/preparing-data/data-requirements/index.html b/preparing-data/data-requirements/index.html index 0219d14..e671f76 100644 --- a/preparing-data/data-requirements/index.html +++ b/preparing-data/data-requirements/index.html @@ -18,7 +18,7 @@
dms-viz

Appearance

Data Requirements ​

There are only two pieces of information you need for dms-viz:

  1. You'll need input data. Your data should have a quantitative metric associated with mutations to a protein sequence.
  2. You'll need a 3D structure for your protein. The structure can be associated with an RCSB ID or provided in a custom .pdb file.

Everything beyond these two requirements is optional.

There are certain cases where you will need to provide additional information. For example, if the reference positions in your input data don't match the reference positions in your .pdb file, you'll need to specify a sitemap. Also, if you have data from another dataset that you wish to include in filters or tooltips, you can provide join data to merge with the input data.

The formatting requirements for the input data and optional data are explained below in detail.

Input Data ​

The Input Data is the mutation-based data that you'd like to summarize and visualize on an interactive protein structure. It must contain a column with a quantitative metric that's associated with mutations in a protein sequence. For example, this data could be a fitness score associated with mutations to a protein, or a score that represents how a mutation changes antibody binding to an antigen. For detailed examples of use cases for dms-viz, check out these Vignettes.

Important!

The input data must be in .csv format. If your data is tabular but in another format, please convert it to .csv.

The input data must contain the following columns with exactly these names:

  • site or reference_site ​

    This column should contain the site in the protein at which each measurement was made. This column can be numeric (i.e., [1, 2, 3, 4]) or it can contain strings (i.e., [1, 2, 2a, 2b, 3]). Additionally, the sites do not need to be continuous (i.e., [1, 4, 5, 8]). The order of your sites is assumed to be their order in the data unless it is specified in the Sitemap using the sequential_site column. These reference sites will label the x-axis of all summary plots in dms-viz. In addition, the site or reference_site in the input data is assumed to match the position in the provided protein structure. If the sites are numbered differently between your data and protein structure, you must specify the correct mapping in the protein_site column of the Sitemap.

    For more details on what we mean by 'reference_site', check out the description of the sitemap file.

  • mutant ​

    This column should contain the identity of the mutation that each measurement is associated with. These mutations should be represented using the IUPAC single-letter codes along with symbols for stop codons and gaps (i.e., R, M, P, *, -). If you need to extend or shrink this alphabet, you can do so using the --alphabet flag of configure-dms-viz.

  • wildtype ​

    This column should contain the wildtype identity of residues at a given site in the protein. For example, if a Proline (P) was mutated to an Alanine (A) at position 120 in the protein (P120A), there should be a P in the wildtype column for every row where the value of the site column is 120. This column will also be used to check how well the sequence of the protein structure you provided matches your data. Significant discrepancies can indicate that you're reference, sequential, and protein sites are misaligned.

In addition to these three mandatory columns, you will also need to specify a metric column. The identity of this column is specified with the --metric flag of configure-dms-viz, and it can have any name:

  • <metric> ​

    This column should contain the quantitative metric that you'd like to summarize and view on a protein structure. For example, this column could be called fitness and contain a score that reflects how individual mutations alter a protein's fitness.

Optionally, depending on the design of your experiment, you can also include a "condition column" that specifies how your data is grouped if there are multiple conditions. In other words, you are required to specify this column if there are multiple measurements for the same mutations.

  • condition ​

    This column should only be included if there are multiple measurements in the <metric> column for the same site/mutation combinations. For example, you'll need a condition column if your data contains a measurement like an antibody's escape for multiple 'epitopes' in an antigen. This column contains a unique identifier that's used to delineate between these measurements for each mutation. This 'identifier' will show up in an interactive legend next to the visualization.

Sitemap ​

The Sitemap is a tabular .csv file that specifies the order of the site (reference_site) column in your input data and, optionally, how the site column corresponds to the numbering in the protein structure you provide.

Important!

The sitemap must be in .csv format. If your data is tabular but in another format, please convert it to .csv.

  • reference_site ​

    This column must correspond to the site or reference_site column in your input data. If the protein_site isn't provided, this column is also assumed to correspond to the identity of the sites in the protein structure

    The reference_site refers to the identity of the sites that are mutated in your dataset. These sites will ultimately label the x-axis of the visualization. These 'reference' sites can sometimes differ from the sequential_site (described below); for example, the current SARS-CoV-2 Spike protein variants have insertions and deletions that cause the widely used Wuhan-Hu-1 'reference' numbering to differ from the sequential, numeric order of the data.

  • sequential_site ​

    This column is the sequential order of the reference sites and must be a numeric column. This will determine the order of the protein sites in the visualizations.

  • protein_site ​

    Optionally, this column is only necessary if the reference_site sites are different from the sites (residue numbering) in your provided protein structure. If they are different, this column is the position in the protein structure that corresponds to the reference_site values in your data.

  • chains ​

Optionally, this column is only necessary if you've provided the protein_site column and there are multiple reference_site sites for the same value of protein_site. This might be the case if your data corresponds to discontinuous chains in the protein structure. For example, if your data is measured over two separate chains with overlapping numbering schemes. For example, Influenza HA protein structures usually have separate chains with overlapping numbering for the stalk and the head. So the reference sites 102 and 30(HA) might both correspond to the residue number 102 in the PDB file. In that case, the only way to distinguish between them on the structure is with the identity of the chain (i.e. A vs. B). This column should have chains in the same format as the chains provided to --included-chains (i.e. a space-separated string of chains: "A B C D").

Join Data ​

Optionally, you might have some additional data that you want to combine with your Input Data. You do this so you can include columns from this Join Data in the filters or tooltips of your visualization. This option helps streamline that workflow.

Important!

The join data must be in .csv format. If your data is tabular but in another format, please convert it to .csv.

You can specify more than one .csv file if there are multiple sources of data that you want to take columns from. Check out the API reference entry on the --join-data flag for more details.

The Join Data must contain a site, wildtype, and mutant column, as these are used to join your incoming data with the Input Data.

- + \ No newline at end of file diff --git a/project-info/contact-info/index.html b/project-info/contact-info/index.html index f5c93c1..93cb347 100644 --- a/project-info/contact-info/index.html +++ b/project-info/contact-info/index.html @@ -18,7 +18,7 @@
dms-viz

Appearance

Contact Us ​

dms-viz was created by Will Hannon in the Bloom lab at Fred Hutch Cancer Center. If you're interested in other projects the Bloom lab is working on, check out the Bloom lab's Twitter feed.

Suggestions or Issues? ​

If you have any suggestions for how to improve the tool, or if you encounter any bugs, please post an issue on GitHub. If you're interested in improving the command line tool configure-dms-viz, post your issue here. If you're having issues with the visualization tool, please post here.

- + \ No newline at end of file diff --git a/project-info/contributing-guide/index.html b/project-info/contributing-guide/index.html index c226073..9777af7 100644 --- a/project-info/contributing-guide/index.html +++ b/project-info/contributing-guide/index.html @@ -22,7 +22,7 @@ cd configure_dms_viz

4. Install Dependencies ​

With Poetry, setting up the project environment and installing dependencies is easy:

bash
poetry install
poetry install

Contributing Guidelines ​


1. Work on a New Branch ​

Don't work directly on the main branch. Create a new branch for your feature or bug fix.

bash
git checkout -b your-new-feature-or-fix
git checkout -b your-new-feature-or-fix

2. Document Your Changes ​

Make sure to add comments to your code appropriately. If you're introducing a new feature or making significant changes, update the README.md file as necessary.

3. Commit Your Changes ​

Make granular commits with meaningful commit messages. This makes it easier to review your contributions.

4. Versioning ​

Versioning follows semantic versioning (i.e. X.Y.Z.) where each component represents:

  1. Major version (X): This number is incremented when there are breaking changes that require updates to the web tool API.

  2. Minor version (Y): This number is incremented when new features are added in a backward-compatible manner.

  3. Patch version (Z): This number is incremented when backward-compatible bug fixes are introduced.

Important!

Make sure that the version is incremented in the pyproject.toml, otherwise publishing to PyPI will fail. Also, make sure to update the CHANGELOG to document your changes.

4. Push to Your Fork ​

Push the changes to your forked repository.

bash
git push origin your-new-feature-or-fix
git push origin your-new-feature-or-fix

5. Create a Pull Request ​

Once you're done with your changes and you think it's ready for review, create a pull request from your forked repository to the original repository.

Code Formatting ​

The code is formatted using Black, which will be installed as a development dependence by Poetry. Linting is handled by Ruff, which will also be installed by Poetry.

Contributing to dms-viz.github.io ​

Thanks for your interest in contributing to the visualization component of dms-viz! Below is a quick guide for developing the website along with some guidelines for contributing.

Developing ​


Environment Setup ​

The development of dms-viz utilizes npm, the JavaScript package manager, and Vite, the build tool.

To begin contributing, follow these steps:

  1. Clone the repository to your local machine.

  2. Install the necessary dependencies specified in the package.json file by running the command:

bash
npm install
npm install

Interactive Server ​

To start development, you'll need to run the local server using Vite. This can be done with the command:

bash
npm run dev
npm run dev

This command will start a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

How to Contribute ​

Contributions are made through the Fork and Pull Request workflow. If you're unfamiliar with this workflow, here's a simplified overview:

  1. Create a fork of the dms-viz repository on your own GitHub account.

  2. Make your changes in your forked repository.

  3. Once you're done with your changes, create a pull request to propose your changes to dms-viz.

  4. Your pull request will then be reviewed and, if everything looks good, your changes will be merged into the main repository.

TIP

Remember to fetch the latest changes from the main repository before you start working on new features or fixes.

Code Guidelines ​

We aim for clean and consistent code across the entire project. To this end, we use ESLint for linting and Prettier for code formatting. Make sure to install these extensions in your code editor. Before making a Pull Request, ensure your code adheres to these formatting guidelines.

Versioning ​

To ensure backward compatibility with older versions of specifications generated by configure_dms-viz, our web-based visualization tool employs a systematic versioning strategy. Whenever there are major updates or modifications to the tool, that might affect the existing JSON specifications or the overall behavior of the visualization, we introduce a new version. Here's how the versioning system works:

Version Routes ​

Each version of the tool is accessible through separate routes. If there are multiple major versions with breaking changes, the route is designated as Vx/, where x is the version (i.e., V1/, V2/, and so on). This approach allows us to introduce new features and updates without affecting the existing links to views created with earlier versions of the tool. Users can continue to access and interact with their existing plots through the respective versioned routes.

Sharing URLs ​

This means that if you put a URL link in a paper, this link will automatically contain the version route, ensuring that the visualization will remain accessible and function correctly even after newer versions are released. For instance, a plot created with the version 0 pre-release of the tool will have a URL structure like: https://dms-viz.github.io/V0/<unique_plot_identifier>.

Contributing to the documentation ​

The repository for the documentation is located under the dms-viz GitHub organization here.

Developing ​

The docs are created with VitePress. To develop the docs, follow the instructions below:

  1. Clone the repository
bash
git clone git@github.com:dms-viz/dms-viz-docs.git
 cd dms-viz-docs
git clone git@github.com:dms-viz/dms-viz-docs.git
 cd dms-viz-docs
  1. Install node packages
bash
npm install
npm install
  1. Start the development server
bash
npx vitepress dev
npx vitepress dev

Now, you should be able to see the website built locally. Changes to the website should be automatically reflected on the page. For details on the routing structure and how to develop a VitePress site, go to the documentation for VitePress.

Deploying ​

The docs are hosted on GitHub pages via a specific gh-pages branch and builds are automated using GitHub Actions via this deployment script. The website will build on pull requests and pushes to the main branch.

- + \ No newline at end of file diff --git a/visualizing-data/vignettes/index.html b/visualizing-data/vignettes/index.html index 01aae32..8dadb92 100644 --- a/visualizing-data/vignettes/index.html +++ b/visualizing-data/vignettes/index.html @@ -127,7 +127,7 @@ --title "IAV PB1 Deep Mutational Scan" \ --description "Deep mutational scan of influenza virus A/WSN/1933(H1N1) PB1 RdRp subunit"

This results in an output .json file that can be visualized in the dms-viz right away. You can visualize this with dms-viz below, or you can click here to see the visualization on a separate page.

- + \ No newline at end of file diff --git a/visualizing-data/web-tool-api/index.html b/visualizing-data/web-tool-api/index.html index df17c10..8b94f6e 100644 --- a/visualizing-data/web-tool-api/index.html +++ b/visualizing-data/web-tool-api/index.html @@ -19,7 +19,7 @@
dms-viz

Appearance

Web Tool API ​

Uploading Data ​

There are two ways to upload data into dms-viz. You can either upload a local specification file from your computer, or you can provide a link to a remote specification file hosted somewhere like GitHub. You'll find the options for uploading data under the Upload Data section of the side menu.

Local ​

To upload a local file, you simply click on the Upload Data section and choose a file from your machine.

Local Upload

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.

Remote Upload

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/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 provide a markdown description (also hosted remotely) of the datasets.

Providing A Description ​

If you've uploaded data that's stored on a server like GitHub by following the Remote instructions, you can optionally provide a link to a markdown (.md) file that will be displayed below the main visualization in a collapsible container.

Markdown Description

Just like the remote .json specification, the link to the markdown is saved in the URL path and the description will load automatically when someone accesses the updated URL.

Chart Configuration ​

dms-viz provides a handful of ways to navigate and customize the visualization. You can find these options under the Chart Options tab in the side menu.

Chart Options

  • Dataset ​

    Although configure-dms-viz will return only a single .json specification, it is possible to combine multiple .json specifications in a single file to visualize. If there are multiple datasets in the .json file, you can navigate between these using the Dataset dropdown menu. The name that appears in the dropdown for each dataset depends on the --name flag.

    Additionally, next to the Dataset dropdown menu there is an information icon ⓘ. By clicking on this icon, a short description of the dataset appears above the top plot. The description can be specified using the --description flag.

  • Condition ​

    If your input data has multiple measurements for each mutation/site combination that are distinguished by some condition (specified by the --condition flag), an interactive legend appears under Chart Options.

    Although the default label that appears above the legend is Condition, you can specify the label using the --condition_name flag.

  • Summary Metric ​

    Use the Summary Metric dropdown menu to choose how to summarize the metric across every mutation at each site. Choose between the mean, min, max, and sum. The resulting summary is displayed in the line plot and on the protein structure.

  • Floor ​

    Use the Floor checkbox to choose whether the data should be floored at 0.

  • Display Mutation Count ​

    Use the Display Mutation Count checkbox to replace the summary plot above the line plot with a density plot showing the number of mutations that have been sampled at each site. For example, if four mutants have been observed at site 10 in the protein (A, T, Q, and M), the height at that site will be four.

Protein Configuration ​

dms-viz provides a handful of ways to navigate and customize the 3D protein structure. You can find these options under the Protein Configuration tab in the side menu.

Protein Options

There are four components of the protein structure whose appearances can be controlled separately. For each of these separate components, you can alter the color, representation, and opacity.

ComponentDescription
ProteinAll 'polymer' chains in the protein structure that have corresponding data (included in the --included-chains flag).
SelectionThe residues in Protein that have been selected by the user.
PeripheralThe chains that are aren't excluded (by the --exclude-chains flag) but don't have corresponding data (aren't included in the --included-chainss).
LigandIf Show Ligands is checked, the ligands (i.e. glycans, small molecules, etc...) in the structure.

For each of these separate components, there are options to change the following:

  • Representation ​

    How the structure is represented (i.e. surface, ball and stick, etc...).

  • Color ​

    The color of the molecules. All of the molecules for a given component will be the same color, however, ligands can be colored by element.

  • Opacity ​

    The opacity of the component. This can help illustrate the molecular structure with the metric superimposed on the surface of the protein.

Interaction ​

There are a multitude of ways to interact with dms-viz. Below, you'll find some examples of what this interaction can look like.

Chart ​

You can zoom in and out of regions of your data by brushing (click and drag) over the area plot.

You can mouse over sites on the line/point and mutations on the heatmap to see details in a pop-up tooltip and you can select sites to see in the heatmap by clicking on points in the line/point plot.

You can select sites on the protein structure by brushing (click and drag) over points in the line/point plot.

To deselect sites, you can either double-click on the line/point plot or hold down the option key ⌥ and brush over the sites that you want to deselect.

If there is more than one condition in your data, an interactive legend will appear in the Chart Options You can select a condition to color the protein structure with by clicking on a condition in the legend.

Finally, you can remove or add conditions to the line/point plot by holding down the option key ⌥ while clicking.

Protein ​

You can reorient and zoom into the protein structure by clicking and dragging it around the window. You can also reset the protein structure to its original orientation by pressing the R button on your keyboard.

Sharing ​

The visualizations that you create with dms-viz can be shared with collaborators and in manuscripts. There are three ways to go about this:

1. Share the .json file ​

You can simply share the .json specifications that you create with configure-dms-viz.

2. Share static images ​

If you're only interested in a particular plot or protein, you can save and download .png images. Under the Download Session tab in the side menu, you'll see buttons to download an image of both the plot and the protein.

Download Options

3. Share the URL links ​

If your data is hosted on a remote server like GitHub, you can copy the link from your session. This link keeps track of your data, an optional description, and all of the configuration options that you've selected.

- + \ No newline at end of file