dash_bio.NglMoleculeViewer Examples and Reference

see NglMoleculeViewer in action.

Graph

An example of a default NglMoleculeViewer component without any extra properties.

import dash
import dash_bio as dashbio
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output
from dash.exceptions import PreventUpdate
import dash_bio_utils.ngl_parser as ngl_parser

app = dash.Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/dash-bio-docs-files/master/"

dropdown_options = [
    {"label": "1BNA", "value": "1BNA"},
    {"label": "MPRO", "value": "MPRO"},
    {"label": "PLPR", "value": "PLPR"},
    {"label": "5L73", "value": "5L73"},
    {"label": "NSP2", "value": "NSP2"}
]

app.layout = html.Div([
    dcc.Markdown('''
    ### NglMoleculeViewer Controls

    * Rotate Stage: Left-click on the viewer and move the mouse to rotate the stage.
    * Zoom: Use the mouse scroll-wheel to zoom in and out of the viewer.
    * Pan: Right click on the viewer to pan the stage.
    * Individual Molecule Interaction: Left click on the molecule to interact with, then hold the
    `CTRL` key and use right and left click mouse buttons to rotate and pan individual molecules.
    '''),
    dcc.Dropdown(
        id="default-ngl-molecule-dropdown",
        options=dropdown_options,
        placeholder="Select a molecule",
        value="1BNA"
    ),
    dashbio.NglMoleculeViewer(id="default-ngl-molecule"),
])

@app.callback(
    Output("default-ngl-molecule", 'data'),
    Output("default-ngl-molecule", "molStyles"),
    Input("default-ngl-molecule-dropdown", "value")
)
def return_molecule(value):

    if (value is None):
        raise PreventUpdate

    molstyles_dict = {
        "representations": ["cartoon", "axes+box"],
        "chosenAtomsColor": "white",
        "chosenAtomsRadius": 1,
        "molSpacingXaxis": 100,
    }

    data_list = [ngl_parser.get_data(data_path=data_path, pdb_id=value, color='red',reset_view=True, local=False)]

    return data_list, molstyles_dict

if __name__ == '__main__':
    app.run_server(debug=True)

NglMoleculeViewer Controls

  • Rotate Stage: Left-click on the viewer and move the mouse to rotate the stage.
  • Zoom: Use the mouse scroll-wheel to zoom in and out of the viewer.
  • Pan: Right click on the viewer to pan the stage.
  • Individual Molecule Interaction: Left click on the molecule to interact with, then hold the
    CTRL key and use right and left click mouse buttons to rotate and pan individual molecules.

Customization

Molecule Styles

Molecule styles and representations can be styled with the molStyles property which accepts a dict of arguments. Molecule representations can be combined and stacked together by setting a list of representations. The following representations are available:
- Molecules Styles: backbone, ball+stick, cartoon, hyperball, licorice, line, ribbon, rope, spacefill, surface, trace, tube
- Additional Representations: axes, axes+box, helixorient, unitcell

With the sideByside key, we can choose whether multiple molecules should be represented side-by-side or intertwined. Note that in sideByside mode, the molecules cannot be independently rotated or panned.

import dash
import dash_bio as dashbio
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output
import dash_bio_utils.ngl_parser as ngl_parser

representation_options = [
    {"label": "backbone", "value": "backbone"},
    {"label": "ball+stick", "value": "ball+stick"},
    {"label": "cartoon", "value": "cartoon"},
    {"label": "hyperball", "value": "hyperball"},
    {"label": "licorice", "value": "licorice"},
    {"label": "axes+box", "value": "axes+box"},
    {"label": "helixorient", "value": "helixorient"}
]

app = dash.Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/dash-bio-docs-files/master/"

app.layout = html.Div([
    dcc.Dropdown(id="nglstyle-dropdown", options=representation_options,
                 multi=True, value=["cartoon", "axes+box"]),
    dcc.RadioItems(
        id="nglstyle-radio",
        options=[
            {'label': 'sideByside', 'value': "True"},
            {'label': 'Independent', 'value': "False"},
        ],
        value="False"
    ),
    dashbio.NglMoleculeViewer(id="nglstyle-ngl"),
])

@app.callback(
    Output("nglstyle-ngl", 'data'),
    Output("nglstyle-ngl", "molStyles"),
    Input("nglstyle-dropdown", "value"),
    Input("nglstyle-radio", "value")
)
def return_molecule(style, sidebyside):

    sidebyside_bool = sidebyside == "True"

    molstyles_dict = {
        "representations": style,
        "chosenAtomsColor": "red",
        "chosenAtomsRadius": 1,
        "molSpacingXaxis": 100,
        "sideByside": sidebyside_bool
    }

    data_list = [ngl_parser.get_data(data_path=data_path, pdb_id=molecule, color='red',
                                     reset_view=True, local=False)
                 for molecule in ['NSP2', 'NSP4']]

    return data_list, molstyles_dict

if __name__ == '__main__':
    app.run_server(debug=True)

Multiple Molecules

Multiple molecules can be visualized by adding entries to the data list. In the example below, we use multiple dropdown selections to add molecules to the stage. Each molecule can have its own set of atoms and residues highlighted. Individual molecules can be interacted with by holding down the CTRL key. If adding or removing molecules from the stage, make sure the resetView prop is set to false.

import dash
import dash_bio as dashbio
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output
from dash.exceptions import PreventUpdate
import dash_bio_utils.ngl_parser as ngl_parser

app = dash.Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/dash-bio-docs-files/master/"

dropdown_options = [
    {"label": "1BNA", "value": "1BNA"},
    {"label": "MPRO", "value": "MPRO"},
    {"label": "PLPR", "value": "PLPR"},
    {"label": "5L73", "value": "5L73"},
    {"label": "NSP2", "value": "NSP2"}
]

app.layout = html.Div([
    dcc.Dropdown(
        id="ngl-multi-dropdown",
        options=dropdown_options,
        value=["1BNA", "MPRO"],
        multi=True
    ),
    dashbio.NglMoleculeViewer(id="ngl-multiple"),
])

@app.callback(
    Output("ngl-multiple", 'data'),
    Output("ngl-multiple", "molStyles"),
    Input("ngl-multi-dropdown", "value")
)
def return_molecule(value):
    if (value is None):
        raise PreventUpdate

    molstyles_dict = {
        "representations": ["cartoon", "axes+box"],
        "chosenAtomsColor": "white",
        "chosenAtomsRadius": 1,
        "molSpacingXaxis": 100,
    }
    data_list = [
        ngl_parser.get_data(
            data_path=data_path,
            pdb_id=molecule,
            color='red',
            reset_view=True,
            local=False
        )
        for molecule in value
    ]

    return data_list, molstyles_dict

if __name__ == '__main__':
    app.run_server(debug=True)

Height and Width

The Height and Width (in px or as a number) of the container in which the molecules will be displayed.

import dash
import dash_bio as dashbio
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output
import dash_bio_utils.ngl_parser as ngl_parser

app = dash.Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/dash-bio-docs-files/master/"

app.layout = html.Div([
    dcc.Slider(
        id='height-ngl-h',
        min=300,
        max=800,
        value=600,
        step=100,
        marks={300: '300px', 800: '800px'}
    ),
    dcc.Slider(
        id='width-ngl-w',
        min=300,
        max=800,
        value=600,
        step=100,
        marks={300: '300px', 800: '800px'}
    ),
    dashbio.NglMoleculeViewer(id="dimensions-ngl-hw"),
])

@app.callback(
    Output("dimensions-ngl-hw", 'data'),
    Output("dimensions-ngl-hw", "molStyles"),
    Output("dimensions-ngl-hw", "height"),
    Output("dimensions-ngl-hw", "width"),
    Input("height-ngl-h", "value"),
    Input("width-ngl-w", "value")
)
def return_molecule(height, width):
    molstyles_dict = {
        "representations": ["cartoon", "axes+box"],
        "chosenAtomsColor": "red",
        "chosenAtomsRadius": 1,
        "molSpacingXaxis": 100,
    }

    data_list = [ngl_parser.get_data(
        data_path=data_path,
        pdb_id='1BNA',
        color='red',
        reset_view=True,
        local=False
    )]

    return data_list, molstyles_dict, height, width

if __name__ == '__main__':
    app.run_server(debug=True)

Stage

Similar to the molecular styles, the stage parameters can also be set. The background color, quality of the render, and the camera perspective are part of the stageParameters prop, and can be passed as keys of a dict.

import dash
import dash_bio as dashbio
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output
import dash_bio_utils.ngl_parser as ngl_parser

app = dash.Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/dash-bio-docs-files/master/"

app.layout = html.Div([
    dcc.Dropdown(
        id="ngl-stage-color-dropdown",
        value='white',
        options=[{"label": s.capitalize(), "value": s} for s in ["black", "white"]]
    ),
    dcc.Dropdown(
        id="ngl-stage-quality-dropdown",
        value='auto',
        options=[
            {"label": s.capitalize(), "value": s}
            for s in ["auto", "low", "medium", "high"]
        ]
    ),
    dcc.Dropdown(
        id="ngl-stage-camera-dropdown",
        value='perspective',
        options=[
            {"label": s.capitalize(), "value": s}
            for s in ["perspective", "orthographic"]
        ]
    ),
    dashbio.NglMoleculeViewer(id="ngl-stage"),
])


@app.callback(
    Output("ngl-stage", 'data'),
    Output("ngl-stage", "molStyles"),
    Output("ngl-stage", "stageParameters"),
    Input("ngl-stage-color-dropdown", "value"),
    Input("ngl-stage-quality-dropdown", "value"),
    Input("ngl-stage-camera-dropdown", "value")
)
def return_molecule(color, quality, camera):
    molstyles_dict = {
        "representations": ["cartoon", "axes+box"],
        "chosenAtomsColor": "white",
        "chosenAtomsRadius": 1,
        "molSpacingXaxis": 100,
    }

    stage_params = {
        "quality": quality,
        "backgroundColor": color,
        "cameraType": camera
    }

    data_list = [
        ngl_parser.get_data(
            data_path=data_path,
            pdb_id=molecule,
            color='red',
            reset_view=True,
            local=False
        )
        for molecule in ['1BNA', 'PLPR']
    ]

    return data_list, molstyles_dict, stage_params

if __name__ == '__main__':
    app.run_server(debug=True)

Saving an Image

An image with the selected parameters can be saved as a .PNG by flagging the downloadImage property. With the imageParameters optional dict, we can specify whether to enable antialias, transparency, or trim, and set the filename for the saved image.

import dash
import dash_bio as dashbio
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output, State
import dash_bio_utils.ngl_parser as ngl_parser

app = dash.Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/dash-bio-docs-files/master/"

app.layout = html.Div([
    html.Button(id='save-ngl-simg', n_clicks=0, children="Download Image"),
    dcc.Input(id='file-ngl-simg', placeholder="Enter filename"),
    dashbio.NglMoleculeViewer(id="download-ngl-simg"),
])

@app.callback(
    Output("download-ngl-simg", 'data'),
    Output("download-ngl-simg", "molStyles"),
    Output("download-ngl-simg", "downloadImage"),
    Output("download-ngl-simg", "imageParameters"),
    Input("save-ngl-simg", "n_clicks"),
    State("file-ngl-simg", "value")
)
def return_molecule(n_clicks, filename):
    molstyles_dict = {
        "representations": ["cartoon", "axes+box"],
        "chosenAtomsColor": "red",
        "chosenAtomsRadius": 1,
        "molSpacingXaxis": 100,
    }

    data_list = [ngl_parser.get_data(data_path=data_path, pdb_id='1BNA', color='red',reset_view=True, local=False)]

    imageParameters = {
        "antialias": True,
        "transparent": True,
        "trim": True,
        "defaultFilename": filename
    }
    downloadImage = False

    if n_clicks > 0:
        downloadImage = True

    return data_list, molstyles_dict, downloadImage, imageParameters

if __name__ == '__main__':
    app.run_server(debug=True)

Selecting Molecule Chains and Atoms

The molecule data must be entered in a specific format to define how many molecules should be shown and/or which chains on those molecules are shown. Specific ranges of amino acids and atoms on the molecule can be highlighted as well. To see which filtering options are available to use with a particular molecule, it may be helpful to view the PDB file entries for a range of atoms which specify the atom names, the residues they belong to, and a one-letter code for the chain.

The following format needs to be used:

pdbID1.chain:[email protected],atom2

The dash_bio_utils.ngl_parser helper function can help simplify this process by generating the appropriate data format based on the string provided in the above format as the pdb_id argument. It will return a dictionary with the contents of the PDB file, selected residues and ranges, and atoms highlighted in the color selected. Specify whether the data path is locally or remotely hosted with the local boolean argument.

The color and radius of chosen atoms can be set through the molStyles property with the “chosenAtomsColor” and “chosenAtomsRadius” keys.

import dash
import dash_bio as dashbio
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output
from dash.exceptions import PreventUpdate
import dash_bio_utils.ngl_parser as ngl_parser

app = dash.Dash(__name__)

data_path =  "https://raw.githubusercontent.com/plotly/dash-bio-docs-files/master/"

app.layout = html.Div([
    dcc.Input(id="chain-atom-input", placeholder="Eg. 5L73.A:[email protected],750,800", value="5L73.A:[email protected],750,800"),
    dcc.Dropdown(id="chain-atom-color", value='black',
                 options=[{"label": s.capitalize(), "value": s} for s in ["black", "white","red", "blue"]]),
    dashbio.NglMoleculeViewer(id="chain-atom-ngl"),
])

@app.callback(
    [Output("chain-atom-ngl", 'data'),
     Output("chain-atom-ngl", "molStyles")],
    [Input("chain-atom-input", "value"),
     Input("chain-atom-color", "value")]
)
def return_molecule(value, color):
    if (value is None):
        raise PreventUpdate

    molstyles_dict = {
        "representations": ["cartoon", "axes+box"],
        "chosenAtomsColor": color,
        "chosenAtomsRadius": 1,
        "molSpacingXaxis": 100,
    }
    data_list = [ngl_parser.get_data(
        data_path=data_path,
        pdb_id=value,
        color="red",
        reset_view=True,
        local=False
    )]

    return data_list, molstyles_dict

if __name__ == '__main__':
    app.run_server(debug=True)

NglMoleculeViewer Properties

Access this documentation in your Python terminal with:
```python

help(dash_bio.NglMoleculeViewer)
```

Our recommended IDE for writing Dash apps is Dash Enterprise’s
Data Science Workspaces,
which has typeahead support for Dash Component Properties.
Find out if your company is using
Dash Enterprise
.

id (string; optional):
The ID of this component, used to identify dash components in
callbacks. The ID needs to be unique across all of the components in
an app.

data (list of dicts; default [ { filename: 'placeholder', ext: '', selectedValue: 'placeholder', chain: 'ALL', aaRange: 'ALL', chosen: { chosenAtoms: '', chosenResidues: '', }, color: 'red', config: { input: '', type: 'text/plain', }, uploaded: False, resetView: False, },]):
The data (in JSON format) that will be used to display the molecule
filename: name of the used pdb/cif file ext: file extensions (pdb or
cif) selectedValue: pdbString chain: ALL if the whole molecule shoud
be displayed, e.g. A for showing only chain A aaRange: ALL if the
whole molecule should be displayed, e.g. 1:50 for showing only 50
atoms color: chain color chosen.atoms: string of the chosen Atoms,
e.g. 50,100,150 –> chosen eatoms changed to colored
‘ball’ chosen.residues: string of the chosen residues, e.g. 50,100,150
–> C alpha of chosen residue changed to colored ‘ball’ config.input:
content of the pdb file config.type: format of config.input uploaded:
bool if file from local storage (False) or uploaded by user (True)
resetView: bool if the selection did not change but the view should be
resettet (True).

data is a list of dicts with keys:

downloadImage (boolean; default False):
flag if download image was selected.

height (string | number; default '600px'):
The height (in px or as a number) of the container in which the
molecules will be displayed.

imageParameters (dict; default { antialias: True, transparent: True, trim: True, defaultFilename: 'dash-bio_ngl_output',}):
Parameters (in JSON format) for exporting the image.

imageParameters is a dict with keys:

molStyles (dict; default { representations: ['cartoon', 'axes+box'], chosenAtomsColor: '#ffffff', chosenAtomsRadius: 1, molSpacingXaxis: 100, sideByside: False,}):
The data (in JSON format) that will be used to style the displayed
molecule representations: one or multiple selected molecule
representation - Possible molecule styles:
‘backbone,’ball+stick’,’cartoon’, ‘hyperball’,’licorice’,’line’,
‘ribbon’,’‘rope’,’spacefill’,’surface’,’trace’,’tube’ - Possible
additional representations:
‘axes’,’axes+box’,’helixorient’,’unitcell’ chosenAtomsColor: color of
the ‘ball+stick’ representation of the chosen atoms chosenAtomsRadius:
radius of the ‘ball+stick’ representation of the chosen atoms
molSpacingXaxis: distance on the xAxis between each molecule.

molStyles is a dict with keys:

pdbString (string; optional):
Variable which defines how many molecules should be shown and/or which
chain The following format needs to be used:
pdbID1.chain:[email protected],atom2_pdbID2.chain:start-end . indicates
that only one chain should be shown : indicates that a specific amino
acids range should be shown (e.g. 1-50) @ indicates that chosen atoms
should be highlighted (e.g. @50,100,150) _ indicates that more than
one protein should be shown.

stageParameters (dict; default { quality: 'medium', backgroundColor: 'white', cameraType: 'perspective',}):
Parameters (in JSON format) for the stage object of ngl. Currently
implemented are render quality, background color and camera type
quality: auto, low, medium, high (default: auto) backgroundColor:
white / black (default: white) cameraType: perspective / orthographic
(default: perspective).

stageParameters is a dict with keys:

width (string | number; default '600px'):
The width (in px or as a number) of the container in which the
molecules will be displayed.

Example Data