Reference navigation

On this page

CLASS · v0.9.1

Region

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

from proteinmotion import Region

Constructor

Region(protein, atom_indices)

Parameters

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`atom_indices`	Required	Nonempty collection of zero-based atom indices.

Notes

Create selections with protein.select(). Combine regions from the same protein with the | operator. Residue numbers in select() use PDB author numbering; atom_indices are zero-based.

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
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].
animateproperty	Create a builder for residue color and opacity animations.
distance_to()method	Create a ruler to another region. Extra options go to Distance.
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.

select()

View source

Region.select(protein, *, chain=None, residues=None, atoms=None)

Select atoms by author chain, residue number, and atom name.

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.

Returns: Region

A residue tuple is an inclusive range. A list selects individual numbers. Empty selections raise ValueError.

positions

View source

Region.positions

Current atom coordinates in the protein’s local coordinate frame.

Returns: Array with shape (selected atoms, 3), in ångströms.

model_matrix

View source

Region.model_matrix

Current 4 × 4 transform from local to world coordinates.

position

View source

Region.position

Translation of the parent protein in world coordinates.

world_positions

View source

Region.world_positions

Selected atom coordinates after the parent’s display transform.

or()

View source

Region.__or__(other)

Combine selections from the same protein with region_a | region_b.

Parameter	Default	Description
`other`	Required	Another Region from the same protein for a union, or an endpoint Region for a distance.

Returns: Region

highlight()

View source

Region.highlight(
    *,
    style='sphere',
    color='#f2ba67',
    opacity=None,
    padding=None,
    line_width=0.12,
)

Create a sphere, box, or atom highlight around the selection.

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.

Returns: RegionHighlight

set_color()

View source

Region.set_color(color)

Apply a tint across all representations. None restores the base palette.

Parameter	Default	Description
`color`	Required	Hex color or RGB values. For tint setters, None restores the representation’s base palette.

Returns: The object or a Colorize animation.

set_opacity()

View source

Region.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.

animate

View source

Region.animate

Create a builder for residue color and opacity animations.

Returns: RegionAnimate

distance_to()

View source

Region.distance_to(other, **kwargs)

Create a ruler to another region. Extra options go to Distance.

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.

Returns: Distance

callout()

View source

Region.callout(text, **kwargs)

Create a label connected by a line to this region. Extra options go to Callout.

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

Returns: Callout

label()

View source

Region.label(text=None, **kwargs)

Create one amino-acid label. Extra options go to ResidueLabel.

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

Returns: ResidueLabel