ProteinMotion
Reference navigation
On this page

Heatmap

A matrix of colored cells with a color bar; rows and columns can be residues.

python
from proteinmotion import Heatmap

Constructor

python
Heatmap(
    values,
    *,
    protein=None,
    rows=None,
    columns=None,
    scale=None,
    title='',
    unit='',
    xlabel='',
    ylabel='',
    position=(0.64, 0.1),
    size=(0.32, 0.56),
    highlight=None,
    highlight_color='#f5d477',
    max_cells=160,
    colorbar=True,
)

Parameters

ParameterDefaultDescription
valuesRequired2D array, or a function returning one that is called again when coordinates change.
proteinkeyword onlyNoneProtein whose residues label the rows and columns.
rowskeyword onlyNoneTopology residue indices or a Region for the rows; None uses every polymer residue.
columnskeyword onlyNoneTopology residue indices or a Region for the columns; None uses the rows.
scalekeyword onlyNoneColorScale shared by the structure, plots, and legend. None derives limits from finite values.
titlekeyword only''Text displayed above the plot or color bar.
unitkeyword only''Unit shown above the color bar.
xlabelkeyword only''Horizontal axis label, including units when appropriate.
ylabelkeyword only''Vertical axis label, including units when appropriate.
positionkeyword only(0.64, 0.1)Image coordinates (x, y), with (0, 0) at the top-left and (1, 1) at the bottom-right.
sizekeyword only(0.32, 0.56)Plot (width, height) as fractions of the viewport.
highlightkeyword onlyNoneRegion whose rows and columns are marked at the edges.
highlight_colorkeyword only'#f5d477'Color marking the selected residues in the plot.
max_cellskeyword only160Larger matrices are averaged into at most this many cells per side.
colorbarkeyword onlyTrueDraw the color bar.

Example and output

This excerpt runs inside a scene’s construct() method. The full example file includes imports, structure loading, and camera setup. Run it from a repository checkout.

Code Full script
python
"""AlphaFold confidence for calmodulin, then hydropathy and conservation on ubiquitin.

Part 1 colors the AlphaFold DB model of human calmodulin (AF-P0DP23-F1, v6) by
pLDDT and shows its predicted aligned error. The two lobes are confident on their
own, but their relative position is not: the PAE blocks between them are high.
Part 2 colors the ubiquitin surface (PDB 1UBQ) by Kyte–Doolittle hydropathy, then
by conservation across the Pfam ubiquitin family seed alignment (PF00240).
"""

from pathlib import Path

from proteinmotion import (
    ColorByProperty,
    ColorLegend,
    FadeIn,
    FadeOut,
    Focus,
    Heatmap,
    Protein,
    ProteinScene,
    ResidueValues,
    Text,
    Unwrite,
    Write,
)

DATA = Path(__file__).parent / "data"
MUTED = "#a3b3c7"


class ConfidenceAndConservation(ProteinScene):
    def construct(self):
        aspect = self.width / self.height
        model = Protein.from_file(DATA / "AF-P0DP23-F1-model_v6.cif").cartoon().center()
        model.color_by("plddt")
        c_lobe = model.select(residues=(82, 148))
        pae = Heatmap.pae(
            model,
            DATA / "AF-P0DP23-F1-predicted_aligned_error_v6.json",
            highlight=c_lobe,
            position=(0.63, 0.14),
            size=(0.34, 0.6),
        ).with_panel()
        plddt = ColorLegend(ResidueValues.plddt(model), position=(0.05, 0.82))
        title = Text("AlphaFold confidence", font_size=46, font="semibold", position=(0.05, 0.07))
        subtitle = Text("Calmodulin, AF-P0DP23-F1", font_size=26, color=MUTED, position=(0.051, 0.135))
        self.add(model)
        self.camera.frame(model, margin=0.95, aspect=aspect, screen_position=(0.32, 0.5))
        self.play(Write(title), FadeIn(subtitle), FadeIn(pae), FadeIn(plddt), run_time=1.5)
        self.play(self.camera.animate.orbit(0.8), run_time=4)
        self.play(FadeOut(model), FadeOut(pae), FadeOut(plddt), FadeOut(subtitle), Unwrite(title), run_time=1)

        ubiquitin = Protein.from_file(DATA / "1ubq.cif").surface(color="hydropathy").center()
        hydropathy = ResidueValues.hydropathy(ubiquitin)
        conservation = ResidueValues.conservation(ubiquitin, DATA / "pf00240-seed.sto")
        title = Text("Hydropathy", font_size=46, font="semibold", position=(0.05, 0.07))
        subtitle = Text("Ubiquitin surface, PDB 1UBQ", font_size=26, color=MUTED, position=(0.051, 0.135))
        legend = ColorLegend(hydropathy, position=(0.05, 0.82))
        self.camera.theta, self.camera.phi = 0.0, 0.0
        self.play(
            FadeIn(ubiquitin),
            Write(title),
            FadeIn(subtitle),
            FadeIn(legend),
            Focus(self.camera, ubiquitin, margin=0.9, aspect=aspect),
            run_time=1.5,
        )
        self.play(self.camera.animate.orbit(0.9), run_time=3)
        swap = Text("Conservation", font_size=46, font="semibold", position=(0.05, 0.07))
        source = Text(
            "Pfam PF00240 seed alignment, 59 sequences", font_size=26, color=MUTED, position=(0.051, 0.135)
        )
        consurf = ColorLegend(conservation, position=(0.05, 0.82))
        self.play(
            ColorByProperty(ubiquitin, conservation, stagger=0.4),
            Unwrite(title),
            FadeOut(subtitle),
            FadeOut(legend),
            Write(swap),
            FadeIn(source),
            FadeIn(consurf),
            run_time=2.5,
        )
        self.play(self.camera.animate.orbit(1.2), run_time=4)
Output Preview · 17.5 s · 60 fps
Confidence and conservation

AlphaFold calmodulin pLDDT and PAE, then the ubiquitin surface by hydropathy and Pfam conservation.

Methods and properties

NameDescription
pae()class methodAlphaFold predicted aligned error from AlphaFold DB, ColabFold, or AlphaFold 3 files, a .npy file, or an array.
distances()class methodLive residue distances in ångströms, or their change from a reference structure.
matrixpropertyCompute the view-projection matrix for the given image aspect ratio.
layout()methodProject text and line geometry for the renderer at the current frame.
with_panel()method · inherited from _PlotDraw a rounded card behind the plot so molecules passing behind it stay hidden.
snapshot()method · inherited from _PlotCapture the current state for deterministic timeline evaluation.
glyph_countproperty · inherited from _PlotNumber of shaped glyphs used for writing animation.
set_opacity()method · inherited from AnnotationSet or animate opacity in [0, 1].
move_to()method · inherited from AnnotationSet or animate text position in normalized image coordinates.
shift()method · inherited from AnnotationTranslate the object by an offset.
restore()method · inherited from AnnotationRestore a state produced by snapshot().
animateproperty · inherited from AnnotationCreate a builder for fluent animation calls. Pass the result to scene.play().
text_progressproperty · inherited from AnnotationCurrent reveal progress for glyphs and annotation lines.
python
Heatmap.pae(protein, source, *, title='Predicted aligned error', **kwargs)

AlphaFold predicted aligned error from AlphaFold DB, ColabFold, or AlphaFold 3 files, a .npy file, or an array.

ParameterDefaultDescription
proteinRequiredProtein object to read or animate.
sourceRequiredPAE JSON or .npy file, parsed JSON, or a square array with one row per polymer residue.
titlekeyword only'Predicted aligned error'Text displayed above the plot.
**kwargs—Additional keyword options described below or in the linked constructor.
python
Heatmap.distances(
    protein,
    *,
    region=None,
    anchor='backbone',
    reference=None,
    max_distance=None,
    max_residues=600,
    title=None,
    **kwargs,
)

Live residue distances in ångströms, or their change from a reference structure.

ParameterDefaultDescription
proteinRequiredProtein object to read or animate.
regionkeyword onlyNoneRegion limiting the residues; its ligands, ions and water are left out. None uses every polymer residue.
anchorkeyword only'backbone'"backbone" uses Cα (C4′ for nucleotides); "centroid" uses residue centroids.
referencekeyword onlyNoneProtein with the same residues, or coordinates in this protein's atom order; the plot shows the change.
max_distancekeyword onlyNoneUpper color limit in ångströms; None rounds the largest initial value up.
max_residueskeyword only600Maximum residues in the live quadratic calculation.
titlekeyword onlyNoneText displayed above the plot.
**kwargs—Additional keyword options described below or in the linked constructor.
python
Heatmap.matrix

Compute the view-projection matrix for the given image aspect ratio.

Returns: 4 × 4 array.

python
Heatmap.layout(camera, width, height)

Project text and line geometry for the renderer at the current frame.

ParameterDefaultDescription
cameraRequiredCamera used to project or frame objects.
widthRequiredImage width in pixels.
heightRequiredImage height in pixels.

Returns: AnnotationLayout containing glyph placements and line paths.

Inherited from plots._Plot.

python
Heatmap.with_panel(color='#0b1220', opacity=1.0, padding=18)

Draw a rounded card behind the plot so molecules passing behind it stay hidden.

ParameterDefaultDescription
color'#0b1220'Card color.
opacity1.0Card opacity in [0, 1].
padding18Margin around the plot in design pixels at 1080p.

Inherited from plots._Plot.

python
Heatmap.snapshot()

Capture the current state for deterministic timeline evaluation.

Returns: State dictionary.

Inherited from plots._Plot.

python
Heatmap.glyph_count

Number of shaped glyphs used for writing animation.

Inherited from annotations.Annotation.

python
Heatmap.set_opacity(opacity)

Set or animate opacity in [0, 1].

ParameterDefaultDescription
opacityRequiredOpacity in [0, 1], from transparent to opaque.

Returns: The object or animation builder.

Inherited from annotations.Annotation.

python
Heatmap.move_to(position)

Set or animate text position in normalized image coordinates.

ParameterDefaultDescription
positionRequiredImage coordinates (x, y), with (0, 0) at the top-left and (1, 1) at the bottom-right.

Returns: The annotation or animation builder.

Inherited from annotations.Annotation.

python
Heatmap.shift(offset)

Translate the object by an offset.

ParameterDefaultDescription
offsetRequiredOffset (x, y) in design pixels at 1080p for residue labels; normalized image units for text shifts.

Returns: The object or animation builder.

Inherited from annotations.Annotation.

python
Heatmap.restore(state)

Restore a state produced by snapshot().

ParameterDefaultDescription
stateRequiredState returned by snapshot().

Returns: None

Inherited from annotations.Annotation.

python
Heatmap.animate

Create a builder for fluent animation calls. Pass the result to scene.play().

Inherited from annotations.Annotation.

python
Heatmap.text_progress

Current reveal progress for glyphs and annotation lines.