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.
build()class method	Build an ideal peptide with every heavy atom from one-letter codes and torsion angles.
secondary_structureproperty	Current H/E/C state of each residue, as the cartoon draws it.
set_secondary_structure()method	Set one H/E/C state per residue for drawing; can change between animations.
assign_secondary_structure()method	Assign helix, strand and coil with DSSP from the current coordinates.
torsions()method	Measure φ, ψ, ω and χ1–χ5 in degrees for all residues, or a selection.
set_torsions()method	Set torsions in degrees immediately, for every residue; see SetTorsions.
summary()method	Describe available molecular selections.
set_style()method	Apply a reusable molecular representation style.
reset_style()method	Clear atom appearance overrides and reset cartoon thickness.
show_atoms()method	Show ball-and-stick detail over the active representation. Chained animations may also change color, opacity, or transforms.
hide_atoms()method	Hide ball-and-stick detail while retaining the active representation.
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.
fetch()class method	Download a PDB entry or AlphaFold DB model once, keep it in the cache, and load it.
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 protein secondary structure and nucleotide backbone tubes with selectable base shapes.
ribbon()method	Show a continuous backbone ribbon.
set_bases()method	Set nucleotide base shapes and optional dimensions before a scene begins. Use BaseStyle for an animated change.
ball_and_stick()method	Show atom spheres and covalent bond cylinders, with element colors by default.
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.
`resname`keyword only	`None`	Residue name or names, such as "ASP" or ["HEM", "ATP"]; case-insensitive.
`ligands`keyword only	`False`	Select non-polymer residues other than water and single-atom ions.
`ions`keyword only	`False`	Select single-atom, non-carbon residues outside the traced chains, such as Ca²⁺ or Zn²⁺.
`water`keyword only	`False`	Select water residues (HOH, WAT, SOL, and common MD names); load them with include_water=True.
`within`keyword only	`None`	Distance in ångströms; keeps whole residues with any atom this close to of.
`of`keyword only	`None`	Region or Protein used as the reference for within; its own residues are excluded when it belongs to the same protein.
`residue_range`keyword only	`None`	Inclusive author residue-number range, e.g. (23, 34); do not also pass residues.
`element`keyword only	`None`	Element symbol or collection of symbols, e.g. C or [N, O].
`secondary`keyword only	`None`	Secondary-structure code or collection: H (helix), E (sheet), C (coil).
`polymer`keyword only	`None`	True selects polymer atoms, False selects non-polymers, None does not filter.
`icode`keyword only	`None`	Author insertion code or collection; an empty string selects no insertion code.
`required`keyword only	`True`	Raise if nothing matches; False returns None for an optional static selection.
`updating`keyword only	`False`	Re-evaluate membership on access. False (default) freezes membership.

Parameter	Default	Description
`sequence`	Required	One-letter codes for the 20 standard amino acids, or a list of residue names.
`conformation`	`'extended'`	helix, alpha, 310, pi, strand, beta, parallel, antiparallel, ppii, extended, or left.
`phi`keyword only	`None`	φ in degrees, one value or one per residue; overrides the conformation.
`psi`keyword only	`None`	ψ in degrees, one value or one per residue; overrides the conformation.
`omega`keyword only	`180.0`	ω in degrees, one value or one per residue.
`chain`keyword only	`'A'`	Chain ID.
`first`keyword only	`1`	Number of the first residue.
`hydrogens`keyword only	`False`	Add amide H atoms.

Parameter	Default	Description
`chain`keyword only	`None`	Author chain ID or IDs; None selects all chains.
`residues`keyword only	`None`	Author residue number, list, or inclusive (first, last) range.

Parameter	Default	Description
`conformation`keyword only	`None`	Sets φ and ψ together, as in SetTorsions.
`anchor`keyword only	`'center'`	Part that stays still, as in SetTorsions.
`secondary`keyword only	`'auto'`	"auto" updates the cartoon to the new DSSP states; "keep" leaves it unchanged.
`**angles`	—	phi, psi, omega, or chi1–chi5 in degrees, as in SetTorsions.

Parameter	Default	Description
`donors`keyword only	`None`	Donor Region or atom indices; None uses standard amino-acid and canonical nucleotide base templates.
`acceptors`keyword only	`None`	Acceptor Region or atom indices; None uses standard amino-acid and canonical nucleotide base templates.
`max_distance`keyword only	`3.5`	Maximum donor–acceptor distance in ångströms.
`min_angle`keyword only	`150`	Minimum donor–hydrogen–acceptor angle in degrees.
`hydrogens`keyword only	`'auto'`	"explicit", "auto", or "backbone"; controls the use of loaded or inferred hydrogens.
`donor_h_cutoff`keyword only	`1.3`	Maximum donor–hydrogen assignment distance in ångströms.

Parameter	Default	Description
`charges`	`'formal'`	"formal" side-chain templates or one charge per atom, in elementary charge units.
`dielectric`keyword only	`80`	Positive relative dielectric constant.
`screening_length`keyword only	`8`	Positive exponential screening length in ångströms; None disables screening.
`cutoff`keyword only	`12`	Distance cutoff in ångströms.
`min_energy`keyword only	`0.05`	Minimum absolute pair energy to include, in kcal/mol.
`exclude_same_residue`keyword only	`True`	Exclude pairs within the same residue.
`exclude_bonded`keyword only	`True`	Exclude directly bonded pairs.

Parameter	Default	Description
`path`	Required	Input or output file path, as specified by the operation.
`chains`keyword only	`None`	Author chain ID or a collection of IDs; None loads all chains.
`include_water`keyword only	`False`	Retain crystallographic waters; default False.
`include_hydrogens`keyword only	`False`	Retain explicit hydrogen/deuterium atoms; default False. Enable for side-chain and nucleotide hydrogen-bond analysis.
`secondary`keyword only	`'auto'`	"auto" uses the file's helix and sheet records, or DSSP when it has none; "dssp" always computes; "file" uses records only.
`assembly`keyword only	`None`	Biological assembly to build from the deposited chains, such as "1"; None keeps the deposited chains.

Parameter	Default	Description
`identifier`	Required	Four-character PDB ID such as "4HHB", or AlphaFold DB ID such as "AF-P0DP23-F1".
`cache`keyword only	`None`	Download folder; None uses PROTEINMOTION_CACHE or ~/.cache/proteinmotion.
`**options`	—	from_file() options, such as assembly="1" or chains="A".

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
`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	`None`	Spacing in Å between wire points.
`grid_spacing`keyword only	`None`	Surface grid spacing in Å. Smaller values add detail; preferred over legacy resolution.
`color`keyword only	`'secondary'`	Palette: secondary, base, rainbow, chain, or a fixed color. Surfaces also accept element.
`update`keyword only	`'rebuild'`	"rebuild" recalculates the surface as coordinates change; "deform" moves the reference mesh.
`max_voxels`keyword only	`8000000`	Maximum surface grid cells; increase this limit for large structures or finer grids.

Parameter	Default	Description
`color`keyword only	`'secondary'`	Palette: secondary, base, rainbow, chain, or a fixed color. Surfaces also accept element.
`bases`keyword only	`'slabs'`	Nucleotide base style: slabs, rings, sticks, ladder, or none. None in Representation preserves the current style.
`backbone_radius`keyword only	`0.38`	Positive nucleotide cartoon tube radius in ångströms.
`base_thickness`keyword only	`0.36`	Positive slab/ring thickness in ångströms.
`base_radius`keyword only	`0.16`	Positive base-stick and connector radius in ångströms.
`atom_scale`keyword only	`None`	Multiplier applied to element van der Waals radii for ball-and-stick atoms.
`bond_radius`keyword only	`None`	Covalent bond cylinder radius in ångströms.

Parameter	Default	Description
`color`keyword only	`'rainbow'`	Palette: secondary, base, rainbow, chain, or a fixed color. Surfaces also accept element.
`width`keyword only	`1.05`	Ribbon width in ångströms.
`bases`keyword only	`'none'`	Nucleotide base style: slabs, rings, sticks, ladder, or none. None in Representation preserves the current style.

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.
`color`keyword only	`'element'`	Palette: element, base, chain, rainbow, secondary, or a fixed color.

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
`style`	Required	slabs, rings, sticks, ladder, or none.
`backbone_radius`keyword only	`None`	Positive nucleotide cartoon tube radius in ångströms.
`base_thickness`keyword only	`None`	Positive slab/ring thickness in ångströms.
`base_radius`keyword only	`None`	Positive base-stick and connector radius in ångströms.