GitHub

Visualization

The visualize function returns an interactive 3D view of a structure, rendered with 3Dmol.js. The view is displayed in environments that render HTML: the VS Code plot pane, Pluto and Jupyter notebooks, and Documenter pages (like this one). In the Julia REPL, the view is opened in the default web browser. From scripts, use open_browser(view), or save the view to an HTML file with save("view.html", view).

The secondary structure shown in the cartoon representation is computed by 3Dmol.js. The 3Dmol.js library is loaded from a CDN, so an internet connection is required to display the views.

PDBTools.visualize — Function
visualize(atoms::AbstractVector{<:Atom}, [selection]; kargs...)
visualize(atoms::AbstractVector{<:Atom}, groups::Pair...; kargs...)
visualize(groups::Pair...; kargs...)

Returns an interactive 3D view of the structure, rendered with 3Dmol.js. The view is displayed in environments that render HTML (VS Code plot pane, Pluto, Jupyter notebooks, Documenter pages). It can be saved as a standalone HTML file with save("view.html", view).

Secondary structures for the cartoon representation are computed by 3Dmol.js. The optional selection (a string or function) restricts the atoms shown.

The atoms are classified as polymer (protein or nucleic acid), water, or other (ligands, ions, etc.). The main style applies to polymer atoms, and to ligands if style is not :cartoon.

Groups of atoms with different representations

Several groups of atoms can be shown in the same view, each one with its own representation. Each group is given by a Pair of the atoms and a NamedTuple of the representation options (the keyword arguments style to opacity below, and selection):

visualize(protein => (style=:cartoon,), points => (style=:dots, color="red"))

Alternatively, the groups can be defined by selections of a single vector of atoms:

visualize(atoms, "protein" => (style=:cartoon,), "resname HEM" => (style=:sticks, color="green"))

Each group is a separate model in the view, thus bonds are not computed between atoms of different groups. The same atoms can be part of more than one group (for example, to show a cartoon and the side chains of some residues). color_by must have one value per atom of the group (before selection). The other keyword arguments (hover to height) apply to the whole view.

Isosurfaces of volumetric data

Volumetric data (a VolumetricData object, as read from a .dx file with read_dx) can be shown as isosurfaces, together with the groups of atoms. Each isosurface is given by a Pair of the volumetric data and a NamedTuple with the options:

  • isovalue::Real: the value of the isosurface (required).
  • color="orange": color of the isosurface.
  • opacity::Real=1.0: opacity of the isosurface, from 0 to 1.

For example, two isosurfaces of the same data, with different values:

density = read_dx("density.dx")
visualize(
    protein => (style=:cartoon,), 
    density => (isovalue=0.1, color="orange", opacity=0.5), 
    density => (isovalue=0.3, color="red"),
)

Keyword arguments

Representation (per group):

  • style::Symbol=:cartoon: :cartoon, :sticks, :ballandstick, :spheres, :dots (small spheres), or :lines.
  • color=:auto: one of :chain, :ss (secondary structure), :spectrum (cartoon only), :element, :residue, or a color string (e.g. "red" or "#ff0000"). With :auto, cartoons are colored by chain (or by spectrum if there is a single chain), and other styles by element.
  • color_by::AbstractVector{<:Real}=nothing: a value per atom of atoms (before selection), used to color the atoms with a gradient. Overrides color.
  • colormap::Symbol=:rwb: gradient used with color_by: :rwb (red-white-blue), :roygb, or :sinebow.
  • color_range=nothing: (min, max) limits of the gradient. Defaults to the range of color_by. A reversed range, (max, min), reverses the gradient.
  • ligands::Bool=true: show non-polymer, non-water atoms (as sticks if style == :cartoon).
  • water=:auto: show water molecules (true or false). With :auto, water is shown only if there is nothing else to show (no polymer or other molecules).
  • surface::Bool=false: add a transparent molecular surface for the polymer atoms.
  • opacity::Real=1.0: opacity of the atoms, from 0 (invisible) to 1 (opaque).

View:

  • hover::Bool=true: show atom labels when the mouse is over the atoms.
  • unitcell=nothing: draw the edges of the periodic box. A 3x3 matrix with the lattice vectors as columns (as returned by read_unitcell), or a vector with the box sides, for orthorhombic boxes.
  • unitcell_origin=(0, 0, 0): position of the origin (corner) of the box, or :center to center the box on the geometric center of the atoms.
  • unitcell_color="gray": color of the box edges.
  • background="white": background color.
  • width="100%", height=400: size of the view, in pixels if given as numbers.

Example

using PDBTools
atoms = read_pdb(PDBTools.TESTPDB, "protein")
visualize(atoms)
visualize(atoms; style=:sticks, color=:residue)
visualize(atoms; color_by=beta.(atoms), colormap=:roygb)
v = visualize(atoms, "chain A"; surface=true)
visualize(atoms, "all" => (style=:cartoon,), "resname ARG" => (style=:sticks,))
visualize(read_pdb(PDBTools.TESTPBC); unitcell=read_unitcell(PDBTools.TESTPBC))
save("view.html", v)
source
PDBTools.VolumetricData — Type
VolumetricData(data::AbstractArray{<:Real,3}; origin, step)

Values of a property on a regular three-dimensional grid (for example, a density map). data[i, j, k] is the value at position origin .+ step .* (i - 1, j - 1, k - 1), where origin is the position of the first grid point, and step the spacing of the grid in each direction (a number, or a vector of three numbers).

Volumetric data can be read from and written to OpenDX (.dx) files with read_dx and write_dx, and displayed as isosurfaces with visualize.

Example

julia> using PDBTools

julia> v = VolumetricData(zeros(10, 20, 30); origin=[0.0, 0.0, 0.0], step=0.5)
PDBTools.VolumetricData: 10×20×30 grid
    origin = [0.0, 0.0, 0.0]
    step = [0.5, 0.5, 0.5]
    values from 0.0 to 0.0
source
PDBTools.read_dx — Function
read_dx(filename::AbstractString)

Reads volumetric data from a file in the OpenDX (.dx) format, as written by APBS, VMD, and other programs. Returns a VolumetricData object. Only orthogonal grids are supported.

source
PDBTools.write_dx — Function
write_dx(filename::AbstractString, v::VolumetricData)

Writes the volumetric data v to a file in the OpenDX (.dx) format, which can be read by visualization software (VMD, PyMOL, ChimeraX, 3Dmol.js).

source
PDBTools.StructureView — Type
StructureView

Object returned by visualize. It is displayed as an interactive 3D view in environments that render HTML (VS Code plot pane, Pluto, Jupyter, Documenter pages), and can be saved as a standalone HTML file with save(filename, view).

source
MolSimToolkitShared.save — Method
save(filename::AbstractString, view::StructureView)

Save the interactive structure view as a standalone HTML file, that can be opened in a web browser.

source
PDBTools.open_browser — Function
open_browser(view::StructureView; file=tempname() * ".html")

Save the interactive structure view to an HTML file and open it in the default web browser. Returns the name of the file. The browser command can be set with the BROWSER environment variable.

In the Julia REPL, the views are opened in the browser automatically when displayed.

source

Examples

By default, proteins and nucleic acids are shown as cartoons, other molecules (ligands, ions) as sticks, and water molecules are hidden (unless there is nothing else to show, or water=true). Hovering over atoms shows their residue, chain, and name:

using PDBTools
atoms = read_pdb(PDBTools.TESTPDB, "protein")
visualize(atoms)

Secondary structure coloring, with a transparent molecular surface:

visualize(atoms; color=:ss, surface=true)

Atomistic representations of a selection:

visualize(atoms, "residue <= 20"; style=:ballandstick)

Coloring the atoms by any property, with one value per atom. Here, the solvent accessible surface area of each atom:

s = sasa_particles(atoms)
visualize(atoms; color_by=[s[i] for i in eachindex(atoms)], colormap=:roygb)

Groups with different representations

Different groups of atoms can be shown with different representations in the same view. Each group is given by a pair of the atoms and a NamedTuple with the representation options (style, color, color_by, colormap, color_range, ligands, water, surface, opacity, and selection). The groups can be selections of the same vector of atoms. Here, a cartoon of the protein, and the acidic and basic residues as sticks:

visualize(atoms,
    "protein" => (color="white",),
    "acidic" => (style=:sticks, color="red"),
    "basic" => (style=:sticks, color="blue"),
)

Or the groups can be different vectors of atoms. Each group is a separate model in the view, such that bonds are not computed between atoms of different groups. For example, a set of points around the protein can be shown as dots (style=:dots), colored by a property: 

points = [
    Atom(name="X", resname="PNT", resnum=i, x=at.x + 3 * cos(i), y=at.y + 3 * sin(i), z=at.z, beta=sin(i)^2)
    for (i, at) in enumerate(select(atoms, "name CA"))
]
visualize(
    atoms => (color="white",),
    points => (style=:dots, color_by=beta.(points), colormap=:rwb, color_range=(1, 0)),
)

The opacity option sets the opacity of the atoms of each group, from 0 (invisible) to 1 (opaque). Here, the protein is shown as a transparent cartoon:

visualize(atoms, "protein" => (color="white", opacity=0.4), "acidic" => (style=:ballandstick, color="red"))

Isosurfaces of volumetric data

Volumetric data (values on a regular three-dimensional grid, as a density map) is represented by a VolumetricData object, which can be read from and written to files in the OpenDX (.dx) format with read_dx and write_dx. Volumetric data is shown as isosurfaces, given by pairs of the data and the isosurface options (isovalue, color, and opacity). Here, we build a Gaussian density centered at the oxygen atoms of the acidic residues, and show two of its isosurfaces:

oxygens = select(atoms, "acidic and sidechain and element O")
xmin, xmax = maxmin(oxygens).xmin .- 3, maxmin(oxygens).xmax .+ 3
step = 0.5
n = ceil.(Int, (xmax .- xmin) ./ step) .+ 1
data = zeros(n...)
for I in CartesianIndices(data)
    x = xmin .+ step .* (Tuple(I) .- 1)
    data[I] = sum(exp(-sum(abs2, x .- position(at)) / 4) for at in oxygens)
    data[I] < 1e-3 && (data[I] = 0.0) # negligible values
end
density = VolumetricData(data; origin=xmin, step)
visualize(
    atoms => (color="white",),
    oxygens => (style=:ballandstick, color="red"),
    density => (isovalue=0.2, color="orange", opacity=0.5),
    density => (isovalue=0.6, color="red"),
)

When showing nested isosurfaces, the inner isosurface should be opaque, otherwise it may not be visible through the outer (transparent) one.

The options that apply to the whole view (hover, unitcell, unitcell_origin, unitcell_color, background, width, and height) are given as keyword arguments.

Periodic boxes

The edges of the periodic box can be drawn by providing the unit cell, as a 3x3 matrix with the lattice vectors as columns (as returned by read_unitcell) or as a vector of box sides. By default the box origin is at (0, 0, 0); use unitcell_origin=:center for boxes centered on the system:

atoms = read_pdb(PDBTools.TESTPBC)
visualize(atoms; unitcell=read_unitcell(PDBTools.TESTPBC))
visualize(atoms; unitcell=[85.0, 85.0, 85.0], unitcell_origin=:center)