ProteinMotion
Reference navigation
On this page

CLASS · v0.9.1

TimeSeriesPlot

A vector trace with a cursor linked to scene time or a protein trajectory.

python
from proteinmotion import TimeSeriesPlot

Constructor

python
TimeSeriesPlot(
    times,
    values,
    *,
    protein=None,
    title='',
    xlabel='Time (s)',
    ylabel='Value',
    position=(0.64, 0.56),
    size=(0.32, 0.34),
    color='#f5d477',
    ylim=None,
    reveal=False,
    live_value=None,
    grid=False,
    tips=True,
)

Parameters

ParameterDefaultDescription
timesRequiredStrictly increasing finite x coordinates, one for each value.
valuesRequiredOne finite value or NaN per time sample; NaN leaves a gap.
proteinkeyword onlyNoneOptional protein whose current trajectory state drives the cursor. Supply one sample per trajectory state.
titlekeyword only''Text displayed above the plot or color bar.
xlabelkeyword only'Time (s)'Horizontal axis label, including units when appropriate.
ylabelkeyword only'Value'Vertical axis label, including units when appropriate.
positionkeyword only(0.64, 0.56)Image coordinates (x, y), with (0, 0) at the top-left and (1, 1) at the bottom-right.
sizekeyword only(0.32, 0.34)Plot (width, height) as fractions of the viewport.
colorkeyword only'#f5d477'Hex color or RGB values. For tint setters, None restores the representation’s base palette.
ylimkeyword onlyNoneOptional fixed (minimum, maximum) vertical limits. Defaults to the finite data range with padding.
revealkeyword onlyFalseShow only trace samples at or before the cursor.
live_valuekeyword onlyNoneOptional pure function returning the measurement at current coordinates for the cursor marker.
gridkeyword onlyFalseShow faint horizontal lines at vertical-axis ticks. Defaults to False.
tipskeyword onlyTrueDraw small arrowheads at the ends of the plot axes. Defaults to True.

Notes

Without a protein, the cursor uses scene seconds. With a protein, it follows forward, reverse, and eased playback. Supplied samples remain fixed.

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
distance()class methodRead a trajectory and trace distances between two selection centroids, in ångströms before scene transforms.
current_valuepropertyLive measurement, or linear interpolation of supplied samples at the current cursor.
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
TimeSeriesPlot.distance(first, second, *, times=None, **kwargs)

Read a trajectory and trace distances between two selection centroids, in ångströms before scene transforms.

ParameterDefaultDescription
firstRequiredFirst Region for a centroid-to-centroid distance trace.
secondRequiredSecond Region from the same protein.
timeskeyword onlyNoneStrictly increasing finite x coordinates, one for each value.
**kwargsAdditional keyword options described below or in the linked constructor.

The marker measures the current interpolated coordinates; the line connects the supplied state measurements. Omitted times use state indices.

python
TimeSeriesPlot.current_value

Live measurement, or linear interpolation of supplied samples at the current cursor.

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

Capture the current state for deterministic timeline evaluation.

Returns: State dictionary.

Inherited from plots._Plot.

python
TimeSeriesPlot.glyph_count

Number of shaped glyphs used for writing animation.

Inherited from annotations.Annotation.

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

Restore a state produced by snapshot().

ParameterDefaultDescription
stateRequiredState returned by snapshot().

Returns: None

Inherited from annotations.Annotation.

python
TimeSeriesPlot.animate

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

Inherited from annotations.Annotation.

python
TimeSeriesPlot.text_progress

Current reveal progress for glyphs and annotation lines.