dash_bio.NglMoleculeViewer Examples and Reference

NglMoleculeViewer

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

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.

import dash_bio as dashbio
from dash import Dash, dcc, html, Input, Output, callback
from dash.exceptions import PreventUpdate
import dash_bio.utils.ngl_parser as ngl_parser

app = Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/datasets/master/Dash_Bio/Molecular/"


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"),
])

@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(debug=True)

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_bio as dashbio
from dash import Dash, dcc, html, Input, Output, callback
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(__name__)

data_path = "https://raw.githubusercontent.com/plotly/datasets/master/Dash_Bio/Molecular/"


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"),
])

@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(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_bio as dashbio
from dash import Dash, dcc, html, Input, Output, callback
from dash.exceptions import PreventUpdate
import dash_bio.utils.ngl_parser as ngl_parser

app = Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/datasets/master/Dash_Bio/Molecular/"


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"),
])

@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(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_bio as dashbio
from dash import Dash, dcc, html, Input, Output, callback
import dash_bio.utils.ngl_parser as ngl_parser

app = Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/datasets/master/Dash_Bio/Molecular/"


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"),
])

@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(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_bio as dashbio
from dash import Dash, dcc, html, Input, Output, callback
import dash_bio.utils.ngl_parser as ngl_parser

app = Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/datasets/master/Dash_Bio/Molecular/"


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"),
])


@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(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_bio as dashbio
from dash import Dash, dcc, html, Input, Output, State, callback
import dash_bio.utils.ngl_parser as ngl_parser

app = Dash(__name__)

data_path = "https://raw.githubusercontent.com/plotly/datasets/master/Dash_Bio/Molecular/"


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"),
])

@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(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:start-end@atom1,atom2

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

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_bio as dashbio
from dash import Dash, dcc, html, Input, Output, callback
from dash.exceptions import PreventUpdate
import dash_bio.utils.ngl_parser as ngl_parser

app = 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:629-819@700,750,800", value="5L73.A:629-819@700,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"),
])

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

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

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

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:

backgroundColor (string; optional)
cameraType (string; optional)
quality (string; optional)

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:

antialias (boolean; optional)
defaultFilename (string; optional)
transparent (boolean; optional)
trim (boolean; optional)

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

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:start-end@atom1,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.

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:

aaRange (string; required)
chain (string; required)
chosen (dict; optional)

chosen is a dict with keys:
- atoms (string; required)
- residues (string; required)
color (string; required)
config (dict; optional)

config is a dict with keys:
- input (string; required)
- type (string; required)
ext (string; optional)
filename (string; required)
resetView (boolean; required)
selectedValue (string; required)
uploaded (boolean; required)

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:

chosenAtomsColor (string; required)
chosenAtomsRadius (number; required)
molSpacingXaxis (number; required)
representations (list of strings; optional)
sideByside (boolean; required)

loading_state (dict; optional):
Object that holds the loading state object coming from dash-renderer.

loading_state is a dict with keys:

component_name (string; optional):
Holds the name of the component that is loading.
is_loading (boolean; optional):
Determines if the component is loading or not.
prop_name (string; optional):
Holds which property is loading.