ResidueValues

One measurement per topology residue, with identity checks and optional units.

from proteinmotion import ResidueValues

Constructor

ResidueValues(protein, values, *, name='Value', unit='')

Parameters

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`values`	Required	One finite number or NaN per topology residue, including selected hetero residues.
`name`keyword only	`'Value'`	Measurement name for labels and legends.
`unit`keyword only	`''`	Displayed distance unit: "Å", "nm", or an empty suffix. The distance property uses ångströms.

Attributes

Name	Description
`values`	Read-only array of per-residue values.
`keys`	Chain, author residue number, insertion code, and residue name in topology order.
`name`	Measurement name.
`unit`	Measurement unit.

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 Full script

"""Map 1UBQ Cα B factors to residue color and cartoon thickness."""

from pathlib import Path

from proteinmotion import (
    ColorByProperty,
    ColorLegend,
    ColorScale,
    Protein,
    ProteinScene,
    Representation,
    ResidueValues,
    Rotate,
    Text,
)

DATA = Path(__file__).parent / "data"


class NumericalProperties(ProteinScene):
    def construct(self):
        protein = Protein.from_file(DATA / "1ubq.cif").center()
        values = ResidueValues.b_factors(protein)
        scale = ColorScale(0, 40)
        self.add(protein)
        self.camera.frame(protein, margin=1.08)
        self.add(Text("Residue properties", position=(0.06, 0.07), font_size=42))
        self.add(Text("Ubiquitin · Cα B factors", position=(0.06, 0.13), font_size=25))
        self.add(ColorLegend(scale, title="B factor", unit="Å²", position=(0.06, 0.8)))
        self.play(
            ColorByProperty(protein, values, scale=scale, thickness=(0.6, 1.8), residue_delay=0.012),
            Rotate(protein, 0.25),
            run_time=2.5,
        )
        self.wait(0.5)
        self.play(Representation(protein, "ball_and_stick"), run_time=1.5)
        self.play(Rotate(protein, 0.3), run_time=1)
        self.play(Representation(protein, "surface"), run_time=1.5)
        self.play(Rotate(protein, 0.25), run_time=1.5)

Output Preview · 8.5 s · 60 fps

B factors across representations

1UBQ B factors control residue color and cartoon thickness.

Full source: NumericalProperties Download MP4

Methods and properties

Name	Description
from_mapping()class method	Load keyed values using (chain, author number[, insertion code]); omissions become NaN.
b_factors()class method	Read first-model B factors, or stored confidence values when the source file uses that convention.
rmsf()class method	Calculate per-residue RMSF in ångströms by streaming trajectory frames.

from_mapping()

View source

ResidueValues.from_mapping(protein, values, *, name='Value', unit='')

Load keyed values using (chain, author number[, insertion code]); omissions become NaN.

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`values`	Required	Dictionary of residue identity keys and scalar values. Unknown or ambiguous keys raise an error.
`name`keyword only	`'Value'`	Measurement name for labels and legends.
`unit`keyword only	`''`	Displayed distance unit: "Å", "nm", or an empty suffix. The distance property uses ångströms.

b_factors()

View source

ResidueValues.b_factors(protein, *, atoms='CA', name='B factor', unit='Å²')

Read first-model B factors, or stored confidence values when the source file uses that convention.

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`atoms`keyword only	`'CA'`	Atom name such as CA, or None for the mean of the residue’s selected atoms.
`name`keyword only	`'B factor'`	Measurement name for labels and legends.
`unit`keyword only	`'Å²'`	Displayed distance unit: "Å", "nm", or an empty suffix. The distance property uses ångströms.

rmsf()

View source

ResidueValues.rmsf(
    protein,
    trajectory=None,
    *,
    align=True,
    alignment=None,
    atoms='CA',
    stride=1,
)

Calculate per-residue RMSF in ångströms by streaming trajectory frames.

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`trajectory`	`None`	Trajectory with the same atom identities and order; None uses the protein’s trajectory.
`align`keyword only	`True`	Fit each frame to the first sampled frame before computing fluctuations.
`alignment`keyword only	`None`	Region used to fit frames to the first sampled frame; defaults to all Cα atoms.
`atoms`keyword only	`'CA'`	Atom name, or None to average atomic mean-square fluctuations within each residue.
`stride`keyword only	`1`	Read every nth frame; a positive integer.

Default alignment uses Cα atoms. For MD, unwrap periodic coordinates first. NMR RMSF describes variation across deposited models.