Interactive 3D Plots#

This guide uses the example system loaded in Visualization Example System. Please load the example system before following the rest of the tutorial.

ProteoTwirl also supports various interactive 3D plots. These visualizations will show the protein in the center, with spheres around it indicating the different angles from which the protein is viewed.

Viewing & Saving 3D Plots#

When viewing an interactive 3D visualization, there are two different ways to do this. Either they can be viewed in a Python notebook, or they can be opened in an external web browser.

In the plots below, this is controlled by the show_notebook variable. This can be set to one of three different values.

  • show_notebook is None (default): tries to check if the code is executed in a notebook and automatically sets show_notebook accordingly

  • show_notebook is False will open the visualization in a new web browser tab

  • show_notebook is True will show the visualization as a notebook widget

To save a 3D visualization, you can set html_path to a string indicating where the visualization should be saved. 3D visualizations are saved as HTML files.

Plotting Protein#

The easiest way to visualize a protein in a Python notebook is simply ending a cell with a ProteinRotation object, which will show an interactive 3D ball representation of the protein.

Showing a Protein in a Notebook#
protein_structure

However, more customizable visualizations, including visualizations outside the notebook context, are available using the plot_protein function. In addition to the view/save arguments discussed in Viewing & Saving 3D Plots, this function allows customization of atom radius and color. For example:

Plotting a Protein with plot_protein#
from ProteoTwirl.Visualization.Plot3D import plot_protein

plot_protein(
    protein_rotation    = protein_structure,
    background          = "#14181e",
    atom_color          = "Residue",
    atom_radius         = 1.0
    )

Atomic Color and Radius#

Atomic Radius#

The radius of atoms in the visualization can be determined in one of three ways.

  1. atom_radius is None, in which case the radii from protein_rotation are used

  2. atom_radius is a float, in which case all radii are set to this radius

  3. AtomRadiusFunction, a function that takes an atom and additional context as input and provides a radius

The AtomRadiusFunction is defined as shown below.

AtomRadiusFunction Signature#
def radii_function(
        index,
        angle,
        val,
        atom,
        radius,
    ) -> float:
    ...

Here index will be the index of the angle in question, angle is a tuple of the angle from which we are currently viewing the protein. If sliders are used, this can allow the radius to change depending on which angle is selected. val is related to a potential value associated with that angle, atom is the MDAnalysis Atom used to calculate the radius, and radius is the radius retrieved from the protein_rotation object.

An example custom function is presented below, which sizes each atom based on the index it has in the protein.

Custom AtomRadiusFunction#
import numpy as np

def radii_function(
        index,
        angle,
        val,
        atom,
        radius,
    ) -> float:

    # Atom IDs start at 12000 due to the selection of one segment
    radii = np.sqrt(atom.id - 12000)/(100)
    return radii


plot_protein(
    protein_rotation    = protein_structure,
    background          = "#14181e",
    atom_color          = "Element",
    atom_radius         = radii_function,
    )

Atom Color#

The color of each atom in the visualization can also be customized. There are three different options for color.

First, you can provide a string indicating a constant color, such as a hex color code.

Second, you can use one of the predefined color schemes:

  • "Element": color each atom by its element

  • "Residue": color each atom by its residue

You can also provide the name of one of the residue count properties, in which case atoms will be colored according to the residue value.

Coloring Atoms by Hydropathy#
plot_protein(
    protein_rotation    = protein_structure,
    background          = "#14181e",
    atom_color          = "Hydropathy Index",
    )

Third, you can use an AtomColorFunction, which can be defined as follows.

AtomColorFunction Signature#
def color_function(
        index,
        angle,
        val,
        atom,
    ) -> str | tuple[float, float, float]:
    ...

Here index will be the index of the angle in question, angle is a tuple of the angle from which we are currently viewing the protein. If sliders are used, this can allow the color to change depending on which angle is selected. val is related to a potential value associated with that angle, and atom is the MDAnalysis Atom used to calculate the color. The output should be either a color string or an RGB tuple.

Custom AtomColorFunction#
import numpy as np

def color_function(
        index,
        angle,
        val,
        atom,
    ) -> str:

    # Scale to roughly fit the 0-255 range for red
    id_to_int = min(255, int(np.sqrt(atom.id - 12000)/(0.3)))
    color = f"#{id_to_int:02x}0000"
    return color

plot_protein(
    protein_rotation    = protein_structure,
    background          = "#14181e",
    atom_color          = color_function,
    html_path           = "3D_Custom_Color_Function.html"
    )

Quick Property View#

Warning

Under construction - coming soon

Plotting a Property in 3D#
protein_structure.plot_property_3d(
    property    = "mean_Hydropathy",
    cmap        = "RdPu",
    size_range  = (1,20),
    background  = "#14181e",
    )

Plotting Selectors#

Warning

Under construction - coming soon

Advanced Plotting#

Warning

Under construction - coming soon