Region

A selection of atoms that follows its parent protein’s coordinates.

from proteinmotion import Region

Constructor

Region(protein, atom_indices, *, allow_empty=False)

Parameters

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`atom_indices`	Required	Nonempty collection of zero-based atom indices.
`allow_empty`keyword only	`False`	Allow an empty Region, as used internally by set operations.

Notes

Use Protein.select(). Combine static selections with |, &, -, and ~. Use residue_range for inclusive author ranges. Updating queries re-evaluate membership; freeze() captures it. optional static queries use required=False.

Attributes

Name	Description
`protein`	Parent Protein object.
`atom_indices`	Read-only, sorted atom indices.
`residue_indices`	Read-only topology residue indices represented in the selection.

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()
frame(self, p)
helix = p.select(chain="A", residues=(23, 34))
marker = helix.highlight(
    style="box",
    color="#f2ba67",
    padding=1.5,
)
self.play(FadeIn(marker), run_time=0.6)
self.focus(helix, margin=1.6, run_time=1.5)
self.play(self.camera.animate.orbit(0.4), run_time=2)
self.play(FadeOut(marker), run_time=0.6)
self.focus(p, run_time=1.5)

Output Preview · 6.2 s · 60 fps

Camera focus

Ubiquitin residues 23–34.

Full source: RegionFocus Download MP4

Methods and properties

Name	Description
atom_indicesproperty	Current selected atom indices.
residue_indicesproperty	Current topology residue indices.
residue_idsproperty	Author identities (chain, residue number, insertion code).
__len__()method	Return the number of frames with len(trajectory).
freeze()method	Capture current selection membership.
filter()method	Filter within this region.
select()class method	Select atoms by author chain, residue number, and atom name.
positionsproperty	Current atom coordinates in the protein’s local coordinate frame.
model_matrixproperty	Current 4 × 4 transform from local to world coordinates.
positionproperty	Translation of the parent protein in world coordinates.
world_positionsproperty	Selected atom coordinates after the parent’s display transform.
__or__()method	Combine selections from the same protein with region_a \| region_b.
highlight()method	Create a sphere, box, or atom highlight around the selection.
set_color()method	Apply a tint across all representations. None restores the base palette.
set_opacity()method	Set or animate opacity in [0, 1].
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.
side_chains()method	A region with the side chains of this region's amino acids, joined at Cα.
animateproperty	Create a builder for residue color and opacity animations.
distance_to()method	Create a ruler to another region. Extra options go to Distance.
torsions()method	Measure φ, ψ, ω and χ1–χ5 in degrees for this region's residues.
set_torsions()method	Set this region's torsions in degrees immediately; see SetTorsions.
torsion_marker()method	A live protractor showing one torsion of this single-residue region.
callout()method	Create a label connected by a line to this region. Extra options go to Callout.
label()method	Create one amino-acid label. Extra options go to ResidueLabel.

Parameter	Default	Description
`style`keyword only	`'sphere'`	Highlight shape or line style; allowed values are specified by the constructor.
`color`keyword only	`'#f2ba67'`	Hex color or RGB values. For tint setters, None restores the representation’s base palette.
`opacity`keyword only	`None`	Opacity in [0, 1], from transparent to opaque.
`padding`keyword only	`None`	Extra highlight size in ångströms. None selects a default for the highlight style.
`line_width`keyword only	`0.12`	Line width in design pixels at 1080p for overlays; ångströms for 3D highlight boxes.

Parameter	Default	Description
`other`	Required	Another Region from the same protein for a union, or an endpoint Region for a distance.
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

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
`torsion`	`'phi'`	phi, psi, omega, or chi1–chi5.
`**kwargs`	—	TorsionMarker options.

Parameter	Default	Description
`text`	Required	Text to display.
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`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.