atomic: Atomic structures

Atomic data, such as molecules read from a Protein Databank file, is managed in C++ data structures which are made available through the following equivalent Python classes:

Also lines between atoms depicting distances or missing segments of a protein backbone are represented as pseudobonds:

Efficient collections of molecular objects and molecular surfaces are also available

Atomic data classes

class AtomicStructure(name, atomic_structure_pointer=None, initialize_graphical_attributes=True)

Bases: AtomicStructureData, Model

Molecular model including atomic coordinates. The data is managed by the AtomicStructureData base class which provides access to the C++ structures.

atoms

All atoms of the structure in an Atoms instance.

copy(name)

Return a copy of this structure with a new name. No atoms or other components of the structure are shared between the original and the copy.

delete()

Delete this structure.

pseudobond_groups

Dictionary mapping name to PseudobondGroup for pseudobond groups belonging to this structure. Read only.

select_atom(atom, toggle=False, selected=True)

Select or unselect a specified Atom. If selected is false then it unselects this atom.

select_atoms(atoms, toggle=False, selected=True)

Select or unselect Atoms. If selected is false then it unselects the atoms.

select_residue(residue, toggle=False, selected=True)

Select a specified Residue. If selected is false then it unselects the residue. Selecting a residue is equivalent to select all the residue atoms.

shown_atom_count()

Number of atoms displayed.

surfaces()

List of MolecularSurface objects for this structure.

all_atomic_structures(session)

List of all AtomicStructure objects.

all_atoms(session)

All atoms in all structures as an Atoms collection.

selected_atoms(session)

All selected atoms in all structures as an Atoms collection.

class Atom(atom_pointer)

An atom includes physical and graphical properties such as an element name, coordinates in space, and color and radius for rendering.

To create an Atom use the AtomicStructure new_atom() method.

BALL_STYLE = 2

Draw mode that displays a reduced atom radius, but larger than bond radius.

HIDE_RIBBON = 1

Hide mask for backbone atoms in ribbon.

SPHERE_STYLE = 1

Draw mode that uses full atom radius.

STICK_STYLE = 3

Draw mode that displays an atom size that matches bond radius.

bfactor

B-factor, floating point value.

bonded_atoms

Atoms connnected to this atom directly by one bond. Read only.

bonds

Bonds connected to this atom as an array of Bond objects. Read only.

chain_id

Protein Data Bank chain identifier. Limited to 4 characters. Read only string.

color

Color RGBA length 4 numpy uint8 array.

connects_to(atom)

Whether this atom is directly bonded to a specified atom.

coord

Coordinates as a numpy length 3 array, 64-bit float values.

display

Whether to display the atom. Boolean value.

draw_mode

Controls how the atom is depicted. Can be SPHERE_STYLE, BALL_STYLE or STICK_STYLE.

element_name

Chemical element name. Read only.

element_number

Chemical element number. Read only.

hide

Whether atom is hidden (overrides display). Integer bitmask.

in_chain

Whether this atom belongs to a polymer. Read only.

is_backbone

Whether this a protein or nucleic acid backbone atom.

name

Atom name. Maximum length 4 characters. Read only.

num_bonds

Number of bonds connected to this atom. Read only.

radius

Radius of atom.

residue

Residue the atom belongs to.

scene_coord

Atom center coordinates in the global scene coordinate system. This accounts for the Drawing positions for the hierarchy of models this atom belongs to.

selected

Whether the atom is selected.

structure

AtomicStructure the atom belongs to.

visible

Whether atom is display and not hidden. Read only integer.

class AtomicStructureData(mol_pointer=None)

This is a base class of AtomicStructure. This base class manages the atomic data while the derived class handles the graphical 3-dimensional rendering using OpenGL.

atoms

Atoms collection containing all atoms of the structure.

bonds

Bonds collection containing all bonds of the structure.

chains

Chains collection containing all chains of the structure.

delete()

Deletes the C++ data for this atomic structure.

metadata

Dictionary with metadata. Read only.

name

Structure name, a string.

new_atom(atom_name, element_name)

Create a new Atom object. It must be added to a Residue object belonging to this structure before being used.

new_bond(atom1, atom2)

Create a new Bond joining two Atom objects.

new_residue(residue_name, chain_id, pos)

Create a new Residue.

num_atoms

Number of atoms in structure. Read only.

num_bonds

Number of bonds in structure. Read only.

num_chains

Number of chains structure. Read only.

num_coord_sets

Number of coordinate sets in structure. Read only.

num_residues

Number of residues structure. Read only.

pbg_map

Dictionary mapping name to PseudobondGroup for pseudobond groups belonging to this structure. Read only.

polymers(consider_missing_structure=True, consider_chains_ids=True)

Return a tuple of Residues objects each containing residues for one polymer. Arguments control whether a single polymer can span missing residues or differing chain identifiers.

pseudobond_group(name, create_type='normal')

Get or create a PseudobondGroup belonging to this structure.

residues

Residues collection containing the residues of this structure. Read only.

session_info(ints, floats, misc)

Gather session info; return version number

class Bond(bond_pointer)

Bond connecting two atoms.

To create a Bond use the AtomicStructure new_bond() method.

ALWAYS_DISPLAY = 2

Value of display attribute, bond is shown.

HIDE_RIBBON = 1

Hide mask for backbone bonds in ribbon.

NEVER_DISPLAY = 1

Value of display attribute, bond is not shown.

SMART_DISPLAY = 3

Value of display attribute, bond is shown only if both atoms are shown.

atoms

Two-tuple of Atom objects that are the bond end points.

color

Color RGBA length 4 numpy uint8 array.

display

Whether to display the bond, with 3 possible integer values: ALWAYS_DISPLAY, NEVER_DISPLAY, SMART_DISPLAY. TODO: Value is not currently ignored, smart display is always used.

halfbond

Whether to color the each half of the bond nearest an end atom to match that atom color, or use a single color and the bond color attribute. Boolean value.

hide

Whether bond is hidden (overrides display). Integer bitmask.

other_atom(atom)

Return the Atom at the other end of this bond opposite the specified atom.

radius

Displayed cylinder radius for the bond.

visible

Whether bond is display and not hidden. Read only integer.

class Chain(chain_pointer)

A single polymer chain such as a protein, DNA or RNA strand. A chain has a sequence associated with it. A chain may have breaks. Chain objects are not always equivalent to Protein Databank chains.

TODO: C++ sequence object is currently not available in Python.

chain_id

Chain identifier. Limited to 4 characters. Read only string.

num_residues

Number of residues belonging to this chain. Read only.

residues

Residues collection containing the residues of this chain in order. Read only.

structure

AtomicStructure that this chain belongs too. Read only.

class Element(e_pointer=None, name=None, number=6)

A chemical element having a name, number, mass, and other physical properties.

is_metal

Is atom a metal. Read only.

mass

Element atomic mass, average mass divided by 1/12 mass of carbon, taken from http://en.wikipedia.org/wiki/List_of_elements_by_atomic_weight. Read only.

name

Element name, for example C for carbon. Read only.

number

Element atomic number, for example 6 for carbon. Read only.

class Pseudobond(pbond_pointer)

A Pseudobond is a graphical line between atoms for example depicting a distance or a gap in an amino acid chain, often shown as a dotted or dashed line. Pseudobonds can join atoms belonging to different AtomicStructure`s which is not possible with a :class:`Bond.

To create a Pseudobond use the PseudobondGroup new_pseudobond() method.

ALWAYS_DISPLAY = 2

Value of display attribute, bond is shown.

NEVER_DISPLAY = 1

Value of display attribute, bond is not shown.

SMART_DISPLAY = 3

Value of display attribute, bond is shown only if both atoms are shown.

atoms

Two-tuple of Atom objects that are the bond end points.

color

Color RGBA length 4 numpy uint8 array.

display

Whether to display the bond, with 3 possible integer values: ALWAYS_DISPLAY, NEVER_DISPLAY, SMART_DISPLAY. TODO: Value is not currently ignored, smart display is always used.

halfbond

Whether to color the each half of the bond nearest an end atom to match that atom color, or use a single color and the bond color attribute. Boolean value.

length

Distance between centers of two bond end point atoms.

radius

Displayed cylinder radius for the bond.

class PseudobondGroupData(pbg_pointer)

A group of pseudobonds typically used for one purpose such as display of distances or missing segments. The category attribute names the group, for example “distances” or “missing segments”.

This base class of PseudobondGroup represents the C++ data while the derived class handles rendering the pseudobonds.

To create a PseudobondGroup use the PseudobondManager get_group() method.

category

Name of the pseudobond group. Read only string.

new_pseudobond(atom1, atom2)

Create a new pseudobond between the specified Atom objects.

num_pseudobonds

Number of pseudobonds in group. Read only.

pseudobonds

Group pseudobonds as a Pseudobonds collection. Read only.

class PseudobondManager

Per-session singleton pseudobond manager keeps track of all PseudobondGroupData objects.

get_group(category, create=True)

Get an existing PseudobondGroup or create a new one given a category name.

class Residue(residue_pointer)

A group of atoms such as an amino acid or nucleic acid. Every atom in an AtomicStructure belongs to a residue, including solvent and ions.

To create a Residue use the AtomicStructure new_residue() method.

add_atom(atom)

Add the specified Atom to this residue. An atom can only belong to one residue, and all atoms must belong to a residue.

atoms

Atoms collection containing all atoms of the residue.

chain_id

Protein Data Bank chain identifier. Limited to 4 characters. Read only string.

is_helix

Whether this residue belongs to a protein alpha helix. Boolean value.

is_sheet

Whether this residue belongs to a protein beta sheet. Boolean value.

name

Residue name. Maximum length 4 characters. Read only.

num_atoms

Number of atoms belonging to the residue. Read only.

number

Integer sequence position number as defined in the input data file. Read only.

ribbon_color

Ribbon color RGBA length 4 numpy uint8 array.

ribbon_display

Whether to display the residue in ribbon style. Boolean value.

ss_id

Secondary structure id number. Integer value.

str

String including residue’s name, sequence position, and chain ID in a readable form. Read only.

structure

AtomicStructure that this residue belongs too. Read only.

class PseudobondGroup(pbg_pointer)

A pseudobond group is a named group of Pseudobond objects such as distances that depict lines between atoms with distance labels. Pseudobond groups are managed in C++ code which is made accessible via the PseudobondGroupData base class.