Reference navigation

On this page

Trajectory

A random-access sequence of coordinate frames in ångströms.

from proteinmotion import Trajectory

Constructor

Trajectory(frames, *, topology=None, units='angstrom', times=None, time_unit='ps')

Parameters

Parameter	Default	Description
`frames`	Required	Array or random-access sequence with shape (states, atoms, 3).
`topology`keyword only	`None`	Atom identities, residues, bonds, and chains in a Topology object.
`units`keyword only	`'angstrom'`	Input coordinate units: "angstrom" or "nm". Frames are returned in ångströms.
`times`keyword only	`None`	Strictly increasing finite x coordinates, one for each value.
`time_unit`keyword only	`'ps'`	Physical timestamp unit label, e.g. ps or ns. Does not rescale supplied times.

Notes

All frames must have the same atom count and order. len(trajectory) gives the frame count. Input nanometer coordinates are converted to ångströms when read.

Attributes

Name	Description
`topology`	Optional Topology shared by all frames.
`n_atoms`	Number of atoms per frame.

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 Scene excerpt

loaded = Protein.from_file(DATA / "2k39.cif", chains="A")
core = loaded.select(residues=(1, 70), atoms="CA")
aligned = loaded.trajectory.aligned(indices=core.atom_indices)
p = Protein.from_trajectory(aligned).cartoon().center()
frame(self, p)
self.play(
    PlayTrajectory(p, start=0, end=2, state_easing=smooth),
    run_time=6,
)
self.wait(0.5)

Output Preview · 6.5 s · 60 fps

NMR state playback

PDB 2K39 models 1–3. Interpolation shows structural variation.

Full source: NMRStates Download MP4

Methods and properties

Name	Description
timesproperty	Physical timestamps, or None when the input has no physical clock.
__len__()method	Return the number of frames with len(trajectory).
frame()method	Read a single coordinate frame.
from_npy()class method	Open a NumPy trajectory using memory mapping.
from_mdanalysis()class method	Read MD formats lazily with MDAnalysis. Requires the md extra.
aligned()method	Return an aligned trajectory, preserving physical timestamps.

times

View source

Trajectory.times

Physical timestamps, or None when the input has no physical clock.

len()

View source

Trajectory.__len__()

Return the number of frames with len(trajectory).

Returns: int

frame()

View source

Trajectory.frame(index)

Read a single coordinate frame.

Parameter	Default	Description
`index`	Required	Zero-based frame index.

Returns: float32 array with shape (atoms, 3), in ångströms.

from_npy()

View source

Trajectory.from_npy(path, *, topology=None, units='angstrom', times=None, time_unit='ps')

Open a NumPy trajectory using memory mapping.

Parameter	Default	Description
`path`	Required	Input or output file path, as specified by the operation.
`topology`keyword only	`None`	Atom identities, residues, bonds, and chains in a Topology object.
`units`keyword only	`'angstrom'`	Input coordinate units: "angstrom" or "nm". Frames are returned in ångströms.
`times`keyword only	`None`	Strictly increasing finite x coordinates, one for each value.
`time_unit`keyword only	`'ps'`	Physical timestamp unit label, e.g. ps or ns. Does not rescale supplied times.

Returns: Trajectory

from_mdanalysis()

View source

Trajectory.from_mdanalysis(
    topology_file,
    trajectory_file,
    *,
    selection='protein or nucleic',
    stride=1,
)

Read MD formats lazily with MDAnalysis. Requires the md extra.

Parameter	Default	Description
`topology_file`	Required	Topology file accepted by MDAnalysis.
`trajectory_file`	Required	Coordinate trajectory file accepted by MDAnalysis.
`selection`keyword only	`'protein or nucleic'`	MDAnalysis atom selection expression.
`stride`keyword only	`1`	Read every nth frame; a positive integer.

Returns: Trajectory

Preprocess periodic boundaries before loading. Selected atoms must be grouped by residue.

aligned()

View source

Trajectory.aligned(reference=None, *, indices=None, selection=None)

Return an aligned trajectory, preserving physical timestamps.

Parameter	Default	Description
`reference`	`None`	Reference coordinates for alignment; None uses the first frame.
`indices`keyword only	`None`	Atom indices used for the rigid fit; None uses all atoms.
`selection`keyword only	`None`	Region with at least three anchor atoms matching this trajectory topology; use instead of indices.

Returns: Trajectory