Reference navigation
On this page
CLASS · v0.9.1
TimeSeriesPlot
A vector trace with a cursor linked to scene time or a protein trajectory.
from proteinmotion import TimeSeriesPlotConstructor
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
| Parameter | Default | Description |
|---|---|---|
times | Required | Strictly increasing finite x coordinates, one for each value. |
values | Required | One finite value or NaN per time sample; NaN leaves a gap. |
proteinkeyword only | None | Optional 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 only | None | Optional fixed (minimum, maximum) vertical limits. Defaults to the finite data range with padding. |
revealkeyword only | False | Show only trace samples at or before the cursor. |
live_valuekeyword only | None | Optional pure function returning the measurement at current coordinates for the cursor marker. |
gridkeyword only | False | Show faint horizontal lines at vertical-axis ticks. Defaults to False. |
tipskeyword only | True | Draw 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.
"""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)2K39 playback with a contact map, sequence strip, and Cα distance trace.
Methods and properties
| Name | Description |
|---|---|
| distance()class method | Read a trajectory and trace distances between two selection centroids, in ångströms before scene transforms. |
| current_valueproperty | Live measurement, or linear interpolation of supplied samples at the current cursor. |
| layout()method | Project text and line geometry for the renderer at the current frame. |
| 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. |
TimeSeriesPlot.distance(first, second, *, times=None, **kwargs)Read a trajectory and trace distances between two selection centroids, in ångströms before scene transforms.
| Parameter | Default | Description |
|---|---|---|
first | Required | First Region for a centroid-to-centroid distance trace. |
second | Required | Second Region from the same protein. |
timeskeyword only | None | Strictly increasing finite x coordinates, one for each value. |
**kwargs | — | Additional 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.
TimeSeriesPlot.current_valueLive measurement, or linear interpolation of supplied samples at the current cursor.
TimeSeriesPlot.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.
TimeSeriesPlot.snapshot()Capture the current state for deterministic timeline evaluation.
Returns: State dictionary.
Inherited from plots._Plot.
TimeSeriesPlot.glyph_countNumber of shaped glyphs used for writing animation.
Inherited from annotations.Annotation.
TimeSeriesPlot.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.
TimeSeriesPlot.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.
TimeSeriesPlot.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.
TimeSeriesPlot.restore(state)Restore a state produced by snapshot().
| Parameter | Default | Description |
|---|---|---|
state | Required | State returned by snapshot(). |
Returns: None
Inherited from annotations.Annotation.
TimeSeriesPlot.animateCreate a builder for fluent animation calls. Pass the result to scene.play().
Inherited from annotations.Annotation.
TimeSeriesPlot.text_progressCurrent reveal progress for glyphs and annotation lines.