NucleicAcid

A DNA/RNA structure with base colors, nucleotide cartoons, surfaces and the Protein animation API.

View source Guide and examplesInherits Protein

from proteinmotion import NucleicAcid

Constructor

NucleicAcid(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

Loads PDB/mmCIF or trajectories. The backbone uses C4′ with P as a fallback. Modified residues retain their deposited names and use parent-base annotations when available. Protein also draws nucleic-acid chains in mixed complexes.

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

"""DNA base styles, residue colors, transparency, labels and molecular surface.

Input: RCSB PDB 1BNA, a deposited B-DNA dodecamer (no simulated motion).
Render: proteinmotion render examples/dna_styles.py DNAStyles --fps 60 -o dna.mp4
The same scene accepts --renderer eevee; Blender 4.5+ is required for EEVEE.
"""

from pathlib import Path

from proteinmotion import (
    BaseStyle,
    Colorize,
    FadeOut,
    NucleicAcid,
    ProteinScene,
    Representation,
    SetOpacity,
    Text,
    Write,
)

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


class DNAStyles(ProteinScene):
    def construct(self):
        dna = NucleicAcid.from_file(DATA / "1bna.cif").cartoon(bases="slabs").center()
        dna.rotate(1.35, axis=(1, 0, 0)).rotate(-0.28, axis=(0, 0, 1))
        self.add(dna)
        self.camera.frame(dna, aspect=self.width / self.height).zoom(1.22)
        self.camera.depth_cue = 0.3
        self.camera.set_focus(dna, chain="A", residues=(5, 8), fstop=5.6)
        self.add(Text("DNA · 1BNA", position=(0.055, 0.88), font_size=30))
        title = Text("Base slabs", position=(0.055, 0.10), font_size=46)
        self.play(Write(title), self.camera.animate.orbit(theta=0.12), run_time=1)
        self.play(self.camera.animate.orbit(theta=0.18), run_time=2)
        for style, heading in (
            ("rings", "Filled base rings"),
            ("sticks", "Base sticks"),
            ("ladder", "Ladder rods"),
        ):
            self.play(
                FadeOut(title), BaseStyle(dna, style), self.camera.animate.orbit(theta=0.10), run_time=0.8
            )
            title = Text(heading, position=(0.055, 0.10), font_size=46)
            self.play(Write(title), self.camera.animate.orbit(theta=0.12), run_time=0.8)
            self.play(self.camera.animate.orbit(theta=0.18), run_time=1.4)
        region = dna.select(chain="A", residues=(5, 8))
        other = dna.select(chain="B")
        self.play(
            FadeOut(title),
            BaseStyle(dna, "slabs"),
            Colorize(region, "#ffd47b", residue_delay=0.12),
            SetOpacity(other, 0.16),
            run_time=1.5,
        )
        label = region.callout(
            "Residues 5–8",
            subtitle="Color and opacity follow the selection",
            position=(0.67, 0.25),
            font_size=34,
            color="#ffd47b",
        )
        self.play(Write(label), self.camera.animate.orbit(theta=0.12), run_time=1)
        self.play(Representation(dna, "ball_and_stick"), run_time=1.2)
        self.play(self.camera.animate.orbit(theta=0.20), run_time=2)
        self.play(FadeOut(label), SetOpacity(other, 1), Colorize(region, None), run_time=1)
        title = Text("Molecular surface", position=(0.055, 0.10), font_size=46)
        self.play(Representation(dna, "surface"), Write(title), run_time=1.5)
        self.play(self.camera.animate.orbit(theta=0.30), run_time=2.5)
        self.wait(0.5)

Output Preview · 23.2 s · 60 fps

DNA base styles

1BNA: slabs, rings, sticks, ladder rods, residue styling and a surface.

Full source: DNAStyles Download MP4

Methods and properties

Name	Description
cartoon()method	Show a C4′ backbone tube with slabs, rings, sticks or ladder rods. Pass the geometry options documented on Protein.cartoon().
surface()method	Show a molecular surface using base colors by default. Pass surface options documented on Protein.surface().
select()method · inherited from Protein	Select atoms by author chain, residue number, and atom name.
build()class method · inherited from Protein	Build an ideal peptide with every heavy atom from one-letter codes and torsion angles.
secondary_structureproperty · inherited from Protein	Current H/E/C state of each residue, as the cartoon draws it.
set_secondary_structure()method · inherited from Protein	Set one H/E/C state per residue for drawing; can change between animations.
assign_secondary_structure()method · inherited from Protein	Assign helix, strand and coil with DSSP from the current coordinates.
torsions()method · inherited from Protein	Measure φ, ψ, ω and χ1–χ5 in degrees for all residues, or a selection.
set_torsions()method · inherited from Protein	Set torsions in degrees immediately, for every residue; see SetTorsions.
summary()method · inherited from Protein	Describe available molecular selections.
set_style()method · inherited from Protein	Apply a reusable molecular representation style.
reset_style()method · inherited from Protein	Clear atom appearance overrides and reset cartoon thickness.
show_atoms()method · inherited from Protein	Show ball-and-stick detail over the active representation. Chained animations may also change color, opacity, or transforms.
hide_atoms()method · inherited from Protein	Hide ball-and-stick detail while retaining the active representation.
label_residues()method · inherited from Protein	Create labels for the selected residues. Extra options go to ResidueLabels.
hydrogen_bonds()method · inherited from Protein	Create a hydrogen-bond analysis. Options go to HydrogenBonds.
electrostatics()method · inherited from Protein	Create a screened Coulomb analysis. Options go to Electrostatics.
from_file()class method · inherited from Protein	Load PDB or mmCIF coordinates and retain all models with matching atom identities.
fetch()class method · inherited from Protein	Download a PDB entry or AlphaFold DB model once, keep it in the cache, and load it.
from_trajectory()class method · inherited from Protein	Create a protein from the trajectory’s topology and first frame.
positionsproperty · inherited from Protein	Current atom coordinates in the protein’s local coordinate frame.
atom_progressproperty · inherited from Protein	Current interpolation fraction for each atom.
atom_opacitiesproperty · inherited from Protein	Current per-atom opacity, including global opacity and residue fades.
set_positions()method · inherited from Protein	Replace coordinates while preserving atom identities and topology.
copy()method · inherited from Protein	Copy the protein’s current state for independent animation; topology and trajectory are shared.
center()method · inherited from Protein	Move the molecular centroid to the world origin.
shift()method · inherited from Protein	Translate the object by an offset.
rotate()method · inherited from Protein	Rotate around the molecular centroid.
scale()method · inherited from Protein	Scale around the molecular centroid.
set_opacity()method · inherited from Protein	Set or animate opacity in [0, 1].
set_color()method · inherited from Protein	Apply a tint across all representations. None restores the base palette.
color_by()method · inherited from Protein	Apply residue property colors and optional cartoon thickness before adding the protein to a scene.
color_residues()method · inherited from Protein	Apply a tint to the selected residues in every representation.
set_residue_opacity()method · inherited from Protein	Set opacity on the selected residues.
ribbon()method · inherited from Protein	Show a continuous backbone ribbon.
set_bases()method · inherited from Protein	Set nucleotide base shapes and optional dimensions before a scene begins. Use BaseStyle for an animated change.
ball_and_stick()method · inherited from Protein	Show atom spheres and covalent bond cylinders, with element colors by default.
with_secondary_structure()method · inherited from Protein	Assign helix, sheet, and coil labels before adding the protein to a scene.
animateproperty · inherited from Protein	Create a builder for protein transforms, opacity, and color animation.
model_matrixproperty · inherited from Protein	Current 4 × 4 transform from local to world coordinates.
snapshot()method · inherited from Protein	Capture the current state for deterministic timeline evaluation.
restore()method · inherited from Protein	Restore a state produced by snapshot().

Parameter	Default	Description
`color`keyword only	`'base'`	Base palette: base, chain, rainbow, secondary, or a fixed color.
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

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

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.