Reference navigation
On this page
Heatmap
A matrix of colored cells with a color bar; rows and columns can be residues.
from proteinmotion import HeatmapConstructor
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
| Parameter | Default | Description |
|---|---|---|
values | Required | 2D array, or a function returning one that is called again when coordinates change. |
proteinkeyword only | None | Protein whose residues label the rows and columns. |
rowskeyword only | None | Topology residue indices or a Region for the rows; None uses every polymer residue. |
columnskeyword only | None | Topology residue indices or a Region for the columns; None uses the rows. |
scalekeyword only | None | ColorScale 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 only | None | Region whose rows and columns are marked at the edges. |
highlight_colorkeyword only | '#f5d477' | Color marking the selected residues in the plot. |
max_cellskeyword only | 160 | Larger matrices are averaged into at most this many cells per side. |
colorbarkeyword only | True | Draw 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.
"""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)AlphaFold calmodulin pLDDT and PAE, then the ubiquitin surface by hydropathy and Pfam conservation.
Methods and properties
| Name | Description |
|---|---|
| pae()class method | AlphaFold predicted aligned error from AlphaFold DB, ColabFold, or AlphaFold 3 files, a .npy file, or an array. |
| distances()class method | Live residue distances in ångströms, or their change from a reference structure. |
| matrixproperty | Compute the view-projection matrix for the given image aspect ratio. |
| layout()method | Project text and line geometry for the renderer at the current frame. |
| with_panel()method · inherited from _Plot | Draw a rounded card behind the plot so molecules passing behind it stay hidden. |
| snapshot()method · inherited from _Plot | Capture the current state for deterministic timeline evaluation. |
| glyph_countproperty · inherited from _Plot | Number of shaped glyphs used for writing animation. |
| set_opacity()method · inherited from Annotation | Set or animate opacity in [0, 1]. |
| move_to()method · inherited from Annotation | Set or animate text position in normalized image coordinates. |
| shift()method · inherited from Annotation | Translate the object by an offset. |
| restore()method · inherited from Annotation | Restore a state produced by snapshot(). |
| animateproperty · inherited from Annotation | Create a builder for fluent animation calls. Pass the result to scene.play(). |
| text_progressproperty · inherited from Annotation | Current reveal progress for glyphs and annotation lines. |
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.
| Parameter | Default | Description |
|---|---|---|
protein | Required | Protein object to read or animate. |
source | Required | PAE 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. |
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.
| Parameter | Default | Description |
|---|---|---|
protein | Required | Protein object to read or animate. |
regionkeyword only | None | Region 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 only | None | Protein with the same residues, or coordinates in this protein's atom order; the plot shows the change. |
max_distancekeyword only | None | Upper color limit in ångströms; None rounds the largest initial value up. |
max_residueskeyword only | 600 | Maximum residues in the live quadratic calculation. |
titlekeyword only | None | Text displayed above the plot. |
**kwargs | — | Additional keyword options described below or in the linked constructor. |
Heatmap.matrixCompute the view-projection matrix for the given image aspect ratio.
Returns: 4 × 4 array.
Heatmap.layout(camera, width, height)Project text and line geometry for the renderer at the current frame.
| Parameter | Default | Description |
|---|---|---|
camera | Required | Camera used to project or frame objects. |
width | Required | Image width in pixels. |
height | Required | Image height in pixels. |
Returns: AnnotationLayout containing glyph placements and line paths.
Inherited from plots._Plot.
Heatmap.with_panel(color='#0b1220', opacity=1.0, padding=18)Draw a rounded card behind the plot so molecules passing behind it stay hidden.
| Parameter | Default | Description |
|---|---|---|
color | '#0b1220' | Card color. |
opacity | 1.0 | Card opacity in [0, 1]. |
padding | 18 | Margin around the plot in design pixels at 1080p. |
Inherited from plots._Plot.
Heatmap.snapshot()Capture the current state for deterministic timeline evaluation.
Returns: State dictionary.
Inherited from plots._Plot.
Heatmap.glyph_countNumber of shaped glyphs used for writing animation.
Inherited from annotations.Annotation.
Heatmap.set_opacity(opacity)Set or animate opacity in [0, 1].
| Parameter | Default | Description |
|---|---|---|
opacity | Required | Opacity in [0, 1], from transparent to opaque. |
Returns: The object or animation builder.
Inherited from annotations.Annotation.
Heatmap.move_to(position)Set or animate text position in normalized image coordinates.
| Parameter | Default | Description |
|---|---|---|
position | Required | Image 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.
Heatmap.shift(offset)Translate the object by an offset.
| Parameter | Default | Description |
|---|---|---|
offset | Required | Offset (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.
Heatmap.restore(state)Restore a state produced by snapshot().
| Parameter | Default | Description |
|---|---|---|
state | Required | State returned by snapshot(). |
Returns: None
Inherited from annotations.Annotation.
Heatmap.animateCreate a builder for fluent animation calls. Pass the result to scene.play().
Inherited from annotations.Annotation.
Heatmap.text_progressCurrent reveal progress for glyphs and annotation lines.