ProteinMotion
Reference navigation
On this page

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,
    trajectory=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,
    show_value=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.
trajectorykeyword onlyNoneTrajectory with the same atom identities and order; None uses the protein’s trajectory.
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.
show_valuekeyword onlyTruePrint the cursor value above the plot. Set False when overlaying a second trace on the same 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 methodTrace distances with the same backbone/CA/centroid anchor policy as Distance.
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.
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
TimeSeriesPlot.distance(
    first,
    second,
    *,
    times=None,
    trajectory=None,
    anchor='backbone',
    **kwargs,
)

Trace distances with the same backbone/CA/centroid anchor policy as Distance.

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.
trajectorykeyword onlyNoneExplicit trajectory to measure and follow; defaults to the regions parent trajectory.
anchorkeyword only'backbone'backbone (default), ca, or centroid, matching Distance endpoints.
**kwargs—Additional keyword options described below or in the linked constructor.
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.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
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.