Protein

A molecular structure with fixed atom identities, coordinates, and display settings.

from proteinmotion import Protein

Constructor

Protein(topology, xyz, *, trajectory=None)

Parameters

Parameter	Default	Description
`topology`	Required	Atom identities, residues, bonds, and chains in a Topology object.
`xyz`	Required	Finite coordinates with shape (atoms, 3), in ångströms.
`trajectory`keyword only	`None`	Trajectory with the same atom identities and order; None uses the protein’s trajectory.

Notes

Use from_file() for PDB/mmCIF or from_trajectory() for coordinate ensembles. Distances and radii use ångströms; rotation angles use radians. Immediate setters return the protein for chaining.

Attributes

Name	Description
`topology`	Atoms, residues, covalent bonds, and chain segments.
`trajectory`	Coordinate states associated with this protein.
`position`	World translation as a 3-vector.
`orientation`	3 × 3 rotation matrix.
`size`	Positive uniform scale factor.
`opacity`	Global opacity in [0, 1].
`trajectory_frame`	Current fractional trajectory state, updated by PlayTrajectory and restored by seeking.

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

p = ubiquitin().surface(resolution=0.7).cartoon()
frame(self, p)
self.wait(1)
for name in ("ribbon", "ball_and_stick", "surface"):
    self.play(Representation(p, name), run_time=1.2)
    self.play(Rotate(p, 0.45), run_time=1.5)

Output Preview · 9.1 s · 60 fps

Representation changes

Cartoon, ribbon, ball-and-stick, and SES surface.

Full source: Representations Download MP4

Methods and properties

Name	Description
select()method	Select atoms by author chain, residue number, and atom name.
label_residues()method	Create labels for the selected residues. Extra options go to ResidueLabels.
hydrogen_bonds()method	Create a hydrogen-bond analysis. Options go to HydrogenBonds.
electrostatics()method	Create a screened Coulomb analysis. Options go to Electrostatics.
from_file()class method	Load PDB or mmCIF coordinates and retain all models with matching atom identities.
from_trajectory()class method	Create a protein from the trajectory’s topology and first frame.
positionsproperty	Current atom coordinates in the protein’s local coordinate frame.
atom_progressproperty	Current interpolation fraction for each atom.
atom_opacitiesproperty	Current per-atom opacity, including global opacity and residue fades.
set_positions()method	Replace coordinates while preserving atom identities and topology.
copy()method	Copy the protein’s current state for independent animation; topology and trajectory are shared.
center()method	Move the molecular centroid to the world origin.
shift()method	Translate the object by an offset.
rotate()method	Rotate around the molecular centroid.
scale()method	Scale around the molecular centroid.
set_opacity()method	Set or animate opacity in [0, 1].
set_color()method	Apply a tint across all representations. None restores the base palette.
color_by()method	Apply residue property colors and optional cartoon thickness before adding the protein to a scene.
color_residues()method	Apply a tint to the selected residues in every representation.
set_residue_opacity()method	Set opacity on the selected residues.
surface()method	Show a van der Waals, solvent-accessible, or voxel solvent-excluded surface.
cartoon()method	Show helices, sheet arrows, and coils as a cartoon.
ribbon()method	Show a continuous backbone ribbon.
ball_and_stick()method	Show element-colored atom spheres and covalent bond cylinders.
with_secondary_structure()method	Assign helix, sheet, and coil labels before adding the protein to a scene.
animateproperty	Create a builder for protein transforms, opacity, and color animation.
model_matrixproperty	Current 4 × 4 transform from local to world coordinates.
snapshot()method	Capture the current state for deterministic timeline evaluation.
restore()method	Restore a state produced by snapshot().

Parameter	Default	Description
`chain`keyword only	`None`	Author chain ID or a collection of IDs; None selects all chains.
`residues`keyword only	`None`	Author residue number, inclusive (first, last) tuple, or list of individual numbers.
`atoms`keyword only	`None`	Atom name or list of names, such as "CA"; None selects all atom names.

Parameter	Default	Description
`charges`	`'formal'`	"formal" side-chain templates or one charge per atom, in elementary charge units.
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

Parameter	Default	Description
`path`	Required	Input or output file path, as specified by the operation.
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

Parameter	Default	Description
`angle`	Required	Rotation angle in radians.
`axis`	`(0, 1, 0)`	Nonzero 3D rotation axis; it is normalized internally.

Parameter	Default	Description
`values`	Required	Numerical input values; see the shape and missing-value rules for this object.
`scale`keyword only	`None`	ColorScale shared by the structure, plots, and legend. None derives limits from finite values.
`thickness`keyword only	`None`	Optional (minimum, maximum) positive cartoon cross-section scale factors. Missing values use 1.

Parameter	Default	Description
`color`	Required	Hex color or RGB values. For tint setters, None restores the representation’s base palette.
`chain`keyword only	`None`	Author chain ID or a collection of IDs; None selects all chains.
`residues`keyword only	`None`	Author residue number, inclusive (first, last) tuple, or list of individual numbers.

Parameter	Default	Description
`opacity`	Required	Opacity in [0, 1], from transparent to opaque.
`chain`keyword only	`None`	Author chain ID or a collection of IDs; None selects all chains.
`residues`keyword only	`None`	Author residue number, inclusive (first, last) tuple, or list of individual numbers.

Parameter	Default	Description
`kind`keyword only	`'ses'`	Surface type: "vdw", "sas", or "ses".
`probe_radius`keyword only	`1.4`	Solvent probe radius in ångströms.
`resolution`keyword only	`0.7`	Surface grid spacing in ångströms; smaller values increase detail and cost.
`color`keyword only	`'secondary'`	Base palette: "secondary", "rainbow", "chain", or a fixed color.
`update`keyword only	`'rebuild'`	"rebuild" recalculates the surface as coordinates change; "deform" moves the reference mesh.
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

Parameter	Default	Description
`color`keyword only	`'rainbow'`	Base palette: "secondary", "rainbow", "chain", or a fixed color.
`width`keyword only	`1.05`	Ribbon width in ångströms.

Parameter	Default	Description
`atom_scale`keyword only	`0.3`	Multiplier applied to element van der Waals radii for ball-and-stick atoms.
`bond_radius`keyword only	`0.14`	Covalent bond cylinder radius in ångströms.