ProteinMotion
Reference navigation
On this page

CLASS · v0.9.1

ContactMap

A live binary Cα contact map with linked residue markers.

python
from proteinmotion import ContactMap

Constructor

python
ContactMap(
    protein,
    *,
    region=None,
    selection=None,
    cutoff=8.0,
    min_separation=3,
    position=(0.69, 0.12),
    size=(0.27, 0.4),
    title='Cα contacts',
    max_residues=512,
    contact_color='#65c8bd',
    highlight_color='#f5d477',
)

Parameters

ParameterDefaultDescription
proteinRequiredProtein object to read or animate.
regionkeyword onlyNoneOptional Region limiting the rows and columns.
selectionkeyword onlyNoneRegion to mark on the map edges.
cutoffkeyword only8.0Maximum Cα separation in ångströms for a contact.
min_separationkeyword only3Exclude this many neighboring topology residues within a chain, plus the diagonal.
positionkeyword only(0.69, 0.12)Image coordinates (x, y), with (0, 0) at the top-left and (1, 1) at the bottom-right.
sizekeyword only(0.27, 0.4)Plot (width, height) as fractions of the viewport.
titlekeyword only'Cα contacts'Text displayed above the plot or color bar.
max_residueskeyword only512Maximum Cα residues in a quadratic contact-map calculation; select a region for larger proteins.
contact_colorkeyword only'#65c8bd'Color of a contact cell.
highlight_colorkeyword only'#f5d477'Color marking the selected residues in the plot.

Notes

Rows follow topology order and labels use PDB author numbers. Work scales quadratically; the default limit is 512 Cα residues.

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
"""A ubiquitin NMR ensemble, contact map, sequence, and synchronized distance trace.

2K39 contains deposited NMR models. Interpolation illustrates ensemble variation;
state indices do not represent elapsed physical time. Frames are aligned on Cα
residues 1–70 to remove overall translation and rotation.
"""

from pathlib import Path

from proteinmotion import (
    ColorLegend,
    ColorScale,
    ContactMap,
    PlayTrajectory,
    Protein,
    ProteinScene,
    ResidueValues,
    SequenceTrack,
    Text,
    TimeSeriesPlot,
    linear,
)

DATA = Path(__file__).parent / "data"


class SynchronizedPlots(ProteinScene):
    def construct(self):
        protein = Protein.from_file(DATA / "2k39.cif").center()
        core = protein.select(chain="A", residues=(1, 70), atoms="CA")
        protein.trajectory = protein.trajectory.aligned(indices=core.atom_indices)
        values = ResidueValues.rmsf(protein, align=False)
        scale = ColorScale(0, 8)
        protein.color_by(values, scale=scale)
        selected = protein.select(chain="A", residues=(23, 34))
        self.add(protein, selected.highlight(style="box", padding=1.0, color="#f5d477"))
        self.camera.frame(protein, margin=1.22)
        # Offset the camera target to leave room for the plots on the right.
        self.camera.target += [19, 0, 0]
        self.add(Text("An NMR ensemble with synchronized plots", position=(0.05, 0.05), font_size=35))
        self.add(Text("2K39 · deposited model order", position=(0.05, 0.105), font_size=24))
        self.add(ContactMap(protein, selection=selected, position=(0.64, 0.16), size=(0.32, 0.36)))
        self.add(
            TimeSeriesPlot.distance(
                protein.select(residues=5, atoms="CA"),
                protein.select(residues=70, atoms="CA"),
                title="Cα 5 → Cα 70",
                position=(0.64, 0.54),
                size=(0.32, 0.29),
            )
        )
        self.add(
            SequenceTrack(
                protein,
                selection=selected,
                title="Helix: residues 23–34",
                position=(0.05, 0.85),
                size=(0.91, 0.13),
            )
        )
        self.add(
            ColorLegend(
                scale, title="Aligned ensemble RMSF", unit="Å", position=(0.05, 0.68), size=(0.29, 0.12)
            )
        )
        self.wait(0.5)
        self.play(PlayTrajectory(protein), run_time=9, rate_func=linear)
        self.wait(0.5)
Output Preview · 10.0 s · 60 fps
NMR states with linked plots

2K39 playback with a contact map, sequence strip, and Cα distance trace.

Methods and properties

NameDescription
matrixpropertySymmetric boolean contact matrix evaluated from the protein’s current coordinates.
layout()methodProject text and line geometry for the renderer at the current frame.
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
ContactMap.matrix

Symmetric boolean contact matrix evaluated from the protein’s current coordinates.

Returns: 4 × 4 array.

python
ContactMap.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
ContactMap.snapshot()

Capture the current state for deterministic timeline evaluation.

Returns: State dictionary.

Inherited from plots._Plot.

python
ContactMap.glyph_count

Number of shaped glyphs used for writing animation.

Inherited from annotations.Annotation.

python
ContactMap.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
ContactMap.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
ContactMap.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
ContactMap.restore(state)

Restore a state produced by snapshot().

ParameterDefaultDescription
stateRequiredState returned by snapshot().

Returns: None

Inherited from annotations.Annotation.

python
ContactMap.animate

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

Inherited from annotations.Annotation.

python
ContactMap.text_progress

Current reveal progress for glyphs and annotation lines.