Reference navigation

On this page

ResidueValues

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

from proteinmotion import ResidueValues

Constructor

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

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.
`scale`keyword only	`None`	Preset ColorScale used by color_by, ColorByProperty, and ColorLegend when they get no scale.

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.
`scale`	Preset ColorScale, or one fitted to the values.

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
scaleproperty	Scale around the molecular centroid.
from_mapping()class method	Load keyed values using (chain, author number[, insertion code]); omissions become NaN.
hydropathy()class method	Residue hydropathy (positive = hydrophobic); NaN for non-amino acids. Scales: "kyte-doolittle" (default) or "eisenberg". Modified residues use their parent amino acid where the structure records one.
conservation()class method	Sequence conservation from 0 (variable) to 1 (invariant) for each residue. ``alignment`` is a FASTA, A3M, Stockholm or Clustal file, or a list of aligned sequences. The query (``query`` by name or index, by default the sequence most similar to the structure) is aligned to every protein chain it matches (``chain`` restricts this). The score is 1 − H/ln 20, where H is the Shannon entropy of the column's amino acids with Henikoff sequence weights, scaled by the fraction of sequences without a gap there. The preset color scale spans the 5th–95th percentile of this protein's scores.
plddt()class method	AlphaFold pLDDT per residue, read from the B-factor field or a confidence JSON file. AlphaFold models store pLDDT in the B-factor column; ``source`` may instead be an AlphaFold DB ``confidence_v*.json`` file or a ColabFold scores file.
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.

scale

View source

ResidueValues.scale

Scale around the molecular centroid.

Returns: The protein or animation builder.

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.

hydropathy()

View source

ResidueValues.hydropathy(protein, scale='kyte-doolittle')

Residue hydropathy (positive = hydrophobic); NaN for non-amino acids. Scales: "kyte-doolittle" (default) or "eisenberg". Modified residues use their parent amino acid where the structure records one.

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`scale`	`'kyte-doolittle'`	"kyte-doolittle" (default) or "eisenberg".

conservation()

View source

ResidueValues.conservation(protein, alignment, *, chain=None, query=None, weighting=True)

Sequence conservation from 0 (variable) to 1 (invariant) for each residue. ``alignment`` is a FASTA, A3M, Stockholm or Clustal file, or a list of aligned sequences. The query (``query`` by name or index, by default the sequence most similar to the structure) is aligned to every protein chain it matches (``chain`` restricts this). The score is 1 − H/ln 20, where H is the Shannon entropy of the column's amino acids with Henikoff sequence weights, scaled by the fraction of sequences without a gap there. The preset color scale spans the 5th–95th percentile of this protein's scores.

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`alignment`	Required	FASTA, A3M, Stockholm, or Clustal file, or a list of aligned sequences.
`chain`keyword only	`None`	Chains to map; None maps every chain the query matches.
`query`keyword only	`None`	Name or index of the query sequence; None picks the sequence most similar to the structure.
`weighting`keyword only	`True`	Weight sequences by the Henikoff method.

plddt()

View source

ResidueValues.plddt(protein, source=None)

AlphaFold pLDDT per residue, read from the B-factor field or a confidence JSON file. AlphaFold models store pLDDT in the B-factor column; ``source`` may instead be an AlphaFold DB ``confidence_v*.json`` file or a ColabFold scores file.

Parameter	Default	Description
`protein`	Required	Protein object to read or animate.
`source`	`None`	AlphaFold DB confidence or ColabFold scores JSON; None reads the B-factor column.

b_factors()

View source

ResidueValues.b_factors(protein, *, atoms='backbone', 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	`'backbone'`	backbone selects Cα for proteins or C4′/P for nucleotides. Also accepts an atom name, or None for the per-residue mean.
`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='backbone',
    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 backbone anchors (Cα for proteins, C4′/P for nucleotides).
`atoms`keyword only	`'backbone'`	backbone selects Cα/C4′/P; an atom name selects that atom; None averages atomic mean-square fluctuations per residue.
`stride`keyword only	`1`	Read every nth frame; a positive integer.

Default alignment uses Cα/C4′/P anchors. Unwrap periodic MD coordinates before analysis. NMR RMSF describes variation across deposited models.