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(*args, **kw)

Bases: Structure

Molecular model including support for chains, hetero-residues, and assemblies.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class AtomsDrawing(name)

Bases: Drawing

add_drawing(d)

Experimental API . Add a child drawing.

bounds(positions=True)

Experimental API . The bounds of drawing and displayed children and displayed positions in the parent model coordinate system.

custom_x3d(stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

This is a generic version and assumes that positions are orthogonal.

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for selecting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

planes_pick(planes, exclude=None)

Experimental API . Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for selecting objects in a frustum.

class BondsDrawing(name, pick_class, picks_class)

Bases: Drawing

add_drawing(d)

Experimental API . Add a child drawing.

bounds(positions=True)

Experimental API . The bounds of drawing and displayed children and displayed positions in the parent model coordinate system.

custom_x3d(stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

This is a generic version and assumes that positions are orthogonal.

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for selecting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

planes_pick(planes, exclude=None)

Experimental API . Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for selecting objects in a frustum.

class LevelOfDetail(restore_data=None)

Bases: State

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class PickedAtom(atom, distance)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be selected (‘add’ mode), unselected (‘subtract’ mode) or toggle selected (‘toggle’ mode).

class PickedAtoms(atoms)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be selected (‘add’ mode), unselected (‘subtract’ mode) or toggle selected (‘toggle’ mode).

class PickedBond(bond, distance)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be selected (‘add’ mode), unselected (‘subtract’ mode) or toggle selected (‘toggle’ mode).

class PickedBonds(bonds)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be selected (‘add’ mode), unselected (‘subtract’ mode) or toggle selected (‘toggle’ mode).

class PickedPseudobond(pbond, distance)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be selected (‘add’ mode), unselected (‘subtract’ mode) or toggle selected (‘toggle’ mode).

class PickedPseudobonds(pbonds)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be selected (‘add’ mode), unselected (‘subtract’ mode) or toggle selected (‘toggle’ mode).

class PickedResidue(residue, distance)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be selected (‘add’ mode), unselected (‘subtract’ mode) or toggle selected (‘toggle’ mode).

class PickedResidues(residues)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

Experimental API . Cause this picked object to be selected (‘add’ mode), unselected (‘subtract’ mode) or toggle selected (‘toggle’ mode).

class RibbonDrawing(name)

Bases: Drawing

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for selecting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

planes_pick(planes, exclude=None)

Experimental API . Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for selecting objects in a frustum.

class Structure(session, *, name='structure', c_pointer=None, restore_data=None, auto_style=True, log_info=True)

Bases: Model, StructureData

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

any_part_selected()

Experimental API . Is any part of this Drawing or its children selected.

bounds(positions=True)

Experimental API . The bounds of drawing and displayed children and displayed positions in the parent model coordinate system.

clear_selection()

Experimental API . Unselect this drawing and child drawings in if include_children is True.

copy(name=None)

Experimental API . 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()

Experimental API . Delete this structure.

deleted

Experimental API . Has the C++ side been deleted?

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for selecting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

set_color(color)

Experimental API . Set color of atoms, bonds, and residues

set_state_from_snapshot(session, data)

Experimental API . Restore from session info

surfaces()

Experimental API . List of MolecularSurface objects for this structure.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

all_atomic_structures(session)

Experimental API . List of all AtomicStructure objects.

all_atoms(session, atomic_only=False)

Experimental API . All atoms in all structures as an Atoms collection.

all_structures(session)

Experimental API . List of all Structure objects.

selected_atoms(session)

Experimental API . All selected atoms in all structures as an Atoms collection.

selected_bonds(session)

Experimental API . All selected bonds in all structures as an Bonds collection.

structure_atoms(structures)

Experimental API . Return all atoms in specified atomic structures as an Atoms collection.

structure_residues(structures)

Experimental API . Return all residues in specified atomic structures as an Atoms collection.

class Atom

Bases: CyAtom, State

An atom in a (chemical) structure

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class Bond(bond_pointer)

Bases: State

Bond connecting two atoms.

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

atoms

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

clear_hide_bits(bit_mask)

Experimental API . Clear Atom’s hide bits in bit mask

color

Supported API . Color RGBA length 4 sequence/array. Values in range 0-255

cpp_pointer

Experimental API . Value that can be passed to C++ layer to be used as pointer (Python int)

delete()

Supported API . Delete this Bond from it’s Structure

deleted

Experimental API . Has the C++ side been deleted?

display

Supported API . Whether to display the bond if both atoms are shown. Can be overriden by the hide attribute.

ends_selected

Experimental API . Whether both bond end atoms are selected.

halfbond

Supported API . 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

Supported API . Whether bond is hidden (overrides display). Integer bitmask. Use Atom.HIDE_* constants for hide bits.

length

Supported API . Bond length. Read only.

other_atom(atom)

Supported API . ‘atom’ should be one of the atoms in the bond. Return the other atom.

radius

Experimental API . Displayed cylinder radius for the bond.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

rings(cross_residues=False, all_size_threshold=0)

Experimental API . Return Rings collection of rings this Bond is involved in.

If ‘cross_residues’ is False, then rings that cross residue boundaries are not included. If ‘all_size_threshold’ is zero, then return only minimal rings, of any size. If it is greater than zero, then return all rings not larger than the given value.

The returned rings are quite emphemeral, and shouldn’t be cached or otherwise retained for long term use. They may only live until the next call to rings() [from anywhere, including C++].

selected

Supported API . Whether the bond is selected.

session

Experimental API . Session that this Bond is in

set_hide_bits(bit_mask)

Experimental API . Set Atom’s hide bits in bit mask

shown

Supported API . Whether bond is visible and both atoms are shown and at least one is not Sphere style. Read only.

side_atoms(side_atom)

Experimental API . All the atoms on the same side of the bond as side_atom.

‘side_atom’ has to be one of the two bond atoms, and the returned atoms will include ‘side_atom’. Missing-structure pseudobonds are treated as connecting their atoms for the purpose of computing the side atoms. If bond is part of a ring or cycle then ValueError will be thrown.

smaller_side

Experimental API . Returns the bond atom on the side of the bond with fewer total atoms attached

string(style=None)

Supported API . Get text representation of Bond

structure

Supported API . AtomicStructure the bond belongs to.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

visible

Supported API . Whether bond is display and not hidden. Read only.

class Chain(sseq_pointer=None, *, chain_id=None, structure=None)

Bases: StructureSeq

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.

extend(chars)

Experimental API . Extend the sequence with the given string

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class ChangeTracker

Bases: object

Per-session singleton change tracker keeps track of all atomic data changes

cpp_pointer

Experimental API . Value that can be passed to C++ layer to be used as pointer (Python int)

deleted

Experimental API . Has the C++ side been deleted?

class CoordSet(cs_pointer)

Bases: State

The coordinates for one frame of a Structure

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

cpp_pointer

Experimental API . Value that can be passed to C++ layer to be used as pointer (Python int)

deleted

Experimental API . Has the C++ side been deleted?

id

Experimental API . ID number of coordset

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

session

Experimental API . Session that this CoordSet is in

structure

Experimental API . AtomicStructure the coordset belongs to

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class ExtrudeValue(vertices, normals, triangles, colors, front_band, back_band)

Bases: tuple

back_band

Experimental API . Alias for field number 5

colors

Experimental API . Alias for field number 3

front_band

Experimental API . Alias for field number 4

normals

Experimental API . Alias for field number 1

triangles

Experimental API . Alias for field number 2

vertices

Experimental API . Alias for field number 0

class Pseudobond(pbond_pointer)

Bases: State

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 AtomicStructures which is not possible with a Bond.

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

atoms

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

color

Supported API . Color RGBA length 4 sequence/array. Values in range 0-255

cpp_pointer

Experimental API . Value that can be passed to C++ layer to be used as pointer (Python int)

delete()

Supported API . Delete this pseudobond from it’s group

deleted

Experimental API . Has the C++ side been deleted?

display

Experimental API . Whether to display the bond if both atoms are shown. Can be overriden by the hide attribute.

group

Supported API . pbgroup.PseudobondGroup that this pseudobond belongs to

halfbond

Supported API . 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

Supported API . Distance between centers of two bond end point atoms.

other_atom(atom)

Supported API . ‘atom’ should be one of the atoms in the bond. Return the other atom.

radius

Experimental API . Displayed cylinder radius for the bond.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

selected

Supported API . Whether the pseudobond is selected.

session

Experimental API . Session that this Pseudobond is in

shown

Supported API . Whether bond is visible and both atoms are shown. Read only.

shown_when_atoms_hidden

Experimental API . Normally, whether a pseudbond is shown only depends on the endpoint atoms’ ‘display’ attribute and not on those atoms’ ‘hide’ attribute, on the theory that the hide bits are only set when the atoms are being depicted by some non-default representation (such as ribbons) and that therefore the pseudobonds should still display to “hidden” atoms. However, if ‘shown_when_atoms_hidden’ is False then the pseudobonds will never be displayed if either endpoint atom is hidden (regardless of the display attribute), but will honor the ‘display’ attribute when the atoms aren’t hidden. Defaults to True.

string(style=None)

Supported API . Get text representation of Bond

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class PseudobondGroupData(pbg_pointer)

Bases: object

A group of pseudobonds typically used for one purpose such as display of 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.

clear()

Supported API . Delete all pseudobonds in group

color

Supported API . Sets the color attribute of current pseudobonds and new pseudobonds

cpp_pointer

Experimental API . Value that can be passed to C++ layer to be used as pointer (Python int)

delete_pseudobond(pb)

Supported API . Delete a specific pseudobond from a group

deleted

Experimental API . Has the C++ side been deleted?

get_num_pseudobonds(cs_id)

Supported API . Get the number of pseudobonds for a particular coordinate set.

get_pseudobonds(cs_id)

Supported API . Get the pseudobonds for a particular coordinate set. Use the ‘pseudobonds’

group_type

Supported API . PseudobondGroup.GROUP_TYPE_NORMAL is a normal group,PseudobondGroup.GROUP_TYPE_COORD_SET is a per-coord-set pseudobond group

halfbond

Experimental API . Sets the halfbond attribute of current pseudobonds and new pseudobonds

new_pseudobond(atom1, atom2, cs_id=None)

Supported API . Create a new pseudobond between the specified Atom objects.

num_pseudobonds

Supported API . Number of pseudobonds in group. Read only.

pseudobonds

Supported API . Group pseudobonds as a Pseudobonds collection. Read only.

radius

Supported API . Sets the radius attribute of current pseudobonds and new pseudobonds

structure

Structure that pseudobond group is owned by. Supported API . Returns None if called on a group managed by the global pseudobond manager

class PseudobondManager(session)

Bases: StateManager

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

get_group(name, create=True)

Supported API . Get an existing PseudobondGroup

group_map

Experimental API . Returns a dict that maps from PseudobondGroup name to group

reset_state(session)

Experimental API . Reset state to data-less state

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Gather session info; return version number

class Residue

Bases: CyResidue, State

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.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class RibbonXSection(coords=None, coords2=None, normals=None, normals2=None, faceted=False, tess=None, xs_pointer=None)

Bases: object

A cross section that can extrude ribbons when given the required control points, tangents, normals and colors.

arrow(scales)

Experimental API . Return new arrow cross section scaled by 2x2-tuple scale.

blend(back_band, front_band)

Experimental API . Return the triangles blending front and back halves of ribbon.

cpp_pointer

Experimental API . Value that can be passed to C++ layer to be used as pointer (Python int)

deleted

Experimental API . Has the C++ side been deleted?

extrude(centers, tangents, normals, color, cap_front, cap_back, offset)

Experimental API . Return the points, normals and triangles for a ribbon.

scale(scale)

Experimental API . Return new cross section scaled by 2-tuple scale.

class Ring(ring_pointer)

Bases: object

A ring in the structure.

aromatic

Supported API . Whether the ring is aromatic. Boolean value.

atoms

Supported API . Atoms collection containing the atoms of the ring, in no particular order (see Ring.ordered_atoms()).

bonds

Supported API . Bonds collection containing the bonds of the ring, in no particular order (see Ring.ordered_bonds()).

cpp_pointer

Experimental API . Value that can be passed to C++ layer to be used as pointer (Python int)

deleted

Experimental API . Has the C++ side been deleted?

ordered_atoms

Experimental API . Atoms collection containing the atoms of the ring, in ring order.

ordered_bonds

Experimental API . Bonds collection containing the bonds of the ring, in ring order.

size

Supported API . Number of atoms (and bonds) in the ring. Read only.

class SeqMatchMap(session, align_seq, struct_seq)

Bases: State

Class to track the matching between an alignment sequence and a structure sequence

The match map can be indexed by either an integer (ungapped) sequence position, or by a Residue, which will return a Residue or a sequence position, respectively. The pos_to_res and res_to_pos attributes return dictionaries of the corresponding mapping.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Gather session info; return version number

class Sequence(seq_pointer=None, *, name='sequence', characters='')

Bases: State

A polymeric sequence. Offers string-like interface.

append(chars)

Experimental API . Extend the sequence with the given string

characters

Experimental API . A string representing the contents of the sequence

circular

Experimental API . Indicates the sequence involves a circular permutation; the sequence characters have been doubled, and residue correspondences of the first half implicitly exist in the second half as well. Typically used in alignments to line up with sequences that aren’t permuted.

cpp_pointer

Experimental API . Value that can be passed to C++ layer to be used as pointer (Python int)

deleted

Experimental API . Has the C++ side been deleted?

extend(chars)

Experimental API . Extend the sequence with the given string

name

Experimental API . The sequence name

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

ungapped()

Experimental API . String of sequence without gap characters

exception StructAssocError

Bases: ValueError

class StructureData(mol_pointer=None, *, logger=None)

Bases: object

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

RIBBON_MODE_ARC = 1

Experimental API . Ribbon mode showing secondary structure as an arc (tube or plank).

RIBBON_MODE_DEFAULT = 0

Experimental API . Default ribbon mode showing secondary structure with ribbons.

RIBBON_MODE_WRAP = 2

Experimental API . Ribbon mode showing helix as ribbon wrapped around tube.

RIBBON_ORIENT_ATOMS = 2

Experimental API . Ribbon orientation from interpolated atoms.

RIBBON_ORIENT_CURVATURE = 3

Experimental API . Ribbon orientation perpendicular to ribbon curvature.

RIBBON_ORIENT_GUIDES = 1

Experimental API . Ribbon orientation from guide atoms.

RIBBON_ORIENT_PEPTIDE = 4

Experimental API . Ribbon orientation perpendicular to peptide planes.

TETHER_CONE = 0

Experimental API . Tether is cone with point at ribbon.

TETHER_CYLINDER = 2

Experimental API . Tether is cylinder.

TETHER_REVERSE_CONE = 1

Experimental API . Tether is cone with point at atom.

active_coordset

Supported API . Currently active CoordSet. Read only.

active_coordset_change_notify

Experimental API . Whether notifications are issued when the active coordset is changed. Should only be set to true when temporarily changing the active coordset in a Python script. Boolean

active_coordset_id

Supported API . Index of the active coordinate set.

add_coordset(id, xyz)

Supported API . Add a coordinate set with the given id.

add_coordsets(xyzs, replace=True)

Experimental API . Add coordinate sets. If ‘replace’ is True, clear out existing coordinate sets first

alt_loc_change_notify

Experimental API . Whether notifications are issued when altlocs are changed. Should only be set to true when temporarily changing alt locs in a Python script. Boolean

atoms

Supported API . Atoms collection containing all atoms of the structure.

ball_scale

Experimental API . Scales sphere radius in ball-and-stick style.

bonds

Experimental API . Bonds collection containing all bonds of the structure.

chains

Supported API . Chains collection containing all chains of the structure.

connect_structure(chain_starters, chain_enders, conect_atoms, mod_res)

Experimental API . Generate connectivity. See connect_structure in connectivity.rst for more details.

chain_starters and chain_enders are lists of residues. conect_atoms is a list of atoms. mod_res is a list of residues (not MolResId’s).

coordset(cs_id)

Supported API . Return the CoordSet for the given coordset ID

coordset_ids

Supported API . Return array of ids of all coordinate sets.

coordset_size

Supported API . Return the size of the active coordinate set array.

cpp_pointer

Experimental API . Value that can be passed to C++ layer to be used as pointer (Python int)

delete()

Experimental API . Deletes the C++ data for this atomic structure.

delete_alt_locs()

Experimental API . Incorporate current alt locs as “regular” atoms and remove other alt locs

delete_atom(atom)

Supported API . Delete the specified Atom.

deleted

Experimental API . Has the C++ side been deleted?

lower_case_chains

Supported API . Structure has lower case chain ids. Boolean

metadata

Supported API . Dictionary with metadata. Read only.

molecules

Experimental API . Return a tuple of Atoms objects each containing atoms for one molecule. Missing-structure pseudobonds are consider to connect parts of a molecule.

new_atom(atom_name, element)

Supported API . Create a new Atom object. It must be added to a Residue object belonging to this structure before being used. ‘element’ can be a string (atomic symbol), an integer (atomic number), or an Element instance

new_bond(atom1, atom2)

Supported API . Create a new Bond joining two Atom objects.

new_coordset(index=None, size=None)
Supported API . Create a new empty coordset. In almost all circumstances one would
use the add_coordset(s) method instead (to add fully populated coordsets), but in some cases when building a Structure from scratch this method is needed.

‘index’ defaults to one more than highest existing index (or 1 if none existing); ‘size’ is for efficiency when creating the first coordinate set of a new Structure, and is otherwise unnecessary to specify

new_residue(residue_name, chain_id, pos, insert=' ')

Supported API . Create a new Residue.

num_atoms

Supported API . Number of atoms in structure. Read only.

num_atoms_visible

Experimental API . Number of visible atoms in structure. Read only.

num_bonds

Supported API . Number of bonds in structure. Read only.

num_bonds_visible

Experimental API . Number of visible bonds in structure. Read only.

num_chains

Supported API . Number of chains structure. Read only.

num_coordsets

Supported API . Number of coordinate sets in structure. Read only.

num_residues

Supported API . Number of residues structure. Read only.

pbg_map

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

pdb_version

Experimental API . If this structure came from a PDB file, the major PDB version number of that file (2 or 3). Read only.

polymers(missing_structure_treatment=0, consider_chains_ids=True)

Experimental API . Return a list of (Residues, Residue.polymer_type) tuples, one tuple per polymer. ‘missing_structure_treatment’ controls whether a single polymer can span any missing structure, no missing structure, or only missing structure that is part of a chain trace. ‘consider_chain_ids’, if true, will break polymers when chain IDs change, regardless of other considerations.

pseudobond_group(name, *, create_type='normal')

Supported API . Get or create a PseudobondGroup belonging to this structure.

remove_coordsets()

Experimental API . Remove all coordinate sets.

reorder_residues(new_order)

Experimental API . Reorder the residues. Obviously, ‘new_order’ has to have exactly the same residues as the structure currently has.

residues

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

ribbon_display_count

Experimental API . Return number of residues with ribbon display set. Integer.

ribbon_mode_helix

Experimental API . Ribbon mode for helices. Integer value.

ribbon_mode_strand

Experimental API . Ribbon mode for strands. Integer value.

ribbon_orientation

Experimental API . Ribbon orientation. Integer value.

ribbon_orients(residues=None)

Experimental API . Return array of orientation values for given residues.

ribbon_show_spine

Experimental API . Display ribbon spine. Boolean.

ribbon_tether_opacity

Experimental API . Ribbon tether opacity scale factor (relative to the atom).

ribbon_tether_scale

Experimental API . Ribbon tether thickness scale factor (1.0 = match displayed atom radius, 0=invisible).

ribbon_tether_shape

Experimental API . Ribbon tether shape. Integer value.

ribbon_tether_sides

Experimental API . Number of sides for ribbon tether. Integer value.

rings(cross_residues=False, all_size_threshold=0)

Experimental API . Return Rings collection of rings found in this Structure.

If ‘cross_residues’ is False, then rings that cross residue boundaries are not included. If ‘all_size_threshold’ is zero, then return only minimal rings, of any size. If it is greater than zero, then return all rings not larger than the given value.

The returned rings are quite emphemeral, and shouldn’t be cached or otherwise retained for long term use. They may only live until the next call to rings() [from anywhere, including C++].

save_state(session, flags)

Experimental API . Gather session info; return version number

session_atom_to_id(ptr)

Experimental API . Map Atom pointer to session ID

session_bond_to_id(ptr)

Experimental API . Map Bond pointer to session ID

session_chain_to_id(ptr)

Experimental API . Map Chain pointer to session ID

session_id_to_atom(i)

Experimental API . Map sessionID to Atom pointer

session_id_to_bond(i)

Experimental API . Map sessionID to Bond pointer

session_id_to_chain(i)

Experimental API . Map sessionID to Chain pointer

session_id_to_residue(i)

Experimental API . Map sessionID to Residue pointer

session_residue_to_id(ptr)

Experimental API . Map Residue pointer to session ID

set_color(rgba)

Experimental API . Set color of atoms, bonds, and residues

set_state_from_snapshot(session, data)

Experimental API . Restore from session info

ss_assigned

Experimental API . Has secondary structure been assigned, either by data in original structure file or by some algorithm (e.g. dssp command)

use_default_atom_radii()

Experimental API . If some atoms’ radii has previously been explicitly set, this call will revert to using the default radii

class StructureSeq(sseq_pointer=None, *, chain_id=None, structure=None)

Bases: Sequence

A sequence that has associated structure residues.

Unlike the Chain subclass, StructureSeq will not change in size once created, though associated residues may change to None if those residues are deleted/closed.

bulk_set(residues, characters)

Experimental API . Set all residues/characters of StructureSeq.

chain_id

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

characters

Experimental API . A string representing the contents of the sequence. Read only.

existing_residues

Experimental API . Residues collection containing the residues of this sequence with existing structure, in order. Read only.

from_seqres

Experimental API . Was the full sequence determined from SEQRES (or equivalent) records in the input file

num_existing_residues

Experimental API . Number of residues in this sequence with existing structure. Read only.

num_residues

Experimental API . Number of residues belonging to this sequence, including those without structure. Read only.

polymer_type

Experimental API . Polymer type of this sequence. Same values as Residue.polymer_type, except should not return PT_NONE.

res_map

Experimental API . Returns a dict that maps from Residue to an ungapped sequence position

residue_after(r)

Experimental API . Return the residue at index one more than the given residue, or None if no such residue exists.

residue_at(index)

Experimental API . Return the Residue/None at the (ungapped) position ‘index’.

residue_before(r)

Experimental API . Return the residue at index one less than the given residue, or None if no such residue exists.

residues

Experimental API . List containing the residues of this sequence in order. Residues with no structure will be None. Read only.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

session

Experimental API . Session that this StructureSeq is in

structure

Experimental API . AtomicStructure that this structure sequence comes from. Read only.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class_obj

alias of chimerax.atomic.Chain

estimate_assoc_params(sseq)

Experimental API . Estimate the parameters needed to associate a sequence with a Chain/StructureSeq

Returns a 3-tuple:
  • Estimated total ungapped length, accounting for missing structure
  • A list of continuous sequence segments
  • A list of the estimated size of the gaps between those segments
try_assoc(session, seq, sseq, assoc_params, *, max_errors=6)

Experimental API . Try to associate StructureSeq ‘sseq’ with Sequence ‘seq’.

A set of association parameters (‘assoc_params’) must be provided, typically obtained from the estimate_assoc_params() function. See that function’s documentation for details of assoc_param’s contents. The maximum number of errors allowed can optionally be specified (default: 6).

The return value is a 2-tuple, consisting of a SeqMatchMap instance describing the association, and the number of errors encountered.

An unsuccessful association throws StructAssocError.

class CyAtom

Bases: object

Base class for Atom, and is present only for performance reasons.

alt_loc

Supported API . Alternate location indicator

aniso_u

Supported API . Anisotropic temperature factors,

aniso_u6

Experimental API . Get anisotropic temperature factors as a 6 element float array

bfactor

Supported API . B-factor, floating point value.

bonds

Supported API . Bonds connected to this atom

clear_hide_bits()

Experimental API . Set the hide bits ‘off’ that are ‘on’ in “bitmask”

color

Supported API . Color RGBA length 4 sequence/array. Values in range 0-255

connects_to()

Supported API . Whether this atom is directly bonded to a specified atom.

coord

Supported API . Coordinates from the current coordinate set (or alt loc) as a

coord_index

Supported API . Coordinate index of atom in coordinate set.

default_radius

Supported API . Default atom radius. Read only.

delete()

Supported API . Delete this Atom from it’s Structure

deleted

Supported API . Has the C++ side been deleted?

display

Supported API . Whether to display the atom. Boolean value.

draw_mode

Supported API . Controls how the atom is depicted.

Possible values:

element

Supported API . Element corresponding to the atom’s chemical element

get_altloc_coord()

Supported API . Like the ‘coord’ property, but uses the given altloc

get_altloc_scene_coord()

Supported API . Like the ‘scene_coord’ property, but uses the given altloc

get_coordset_coord()

Supported API . Like the ‘coord’ property, but uses the given coordset ID

get_coordset_scene_coord()

Supported API . Like the ‘scene_coord’ property, but uses the given coordset ID

has_alt_loc()

Supported API . Does this Atom have an alt loc with the given letter?

hide

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

idatm_type

Supported API . Atom’s <a href=”help:user/atomtypes.html”>IDATM type</a>

is_backbone()

Supported API . Whether this Atom is considered backbone,

is_ribose

Experimental API . Whether this atom is part of an nucleic acid ribose moiety. Read only.

is_side_chain

Experimental API . Whether this atom is part of an amino/nucleic acid sidechain.

is_side_connector

Experimental API . Whether this atom is connects the side chain to the backbone, e.g. CA/ribose.

is_side_only

Experimental API . Whether this atom is part of an amino/nucleic acid sidechain.

name

Supported API . Atom name. Maximum length 4 characters.

neighbors

Supported API . Atoms connnected to this atom directly by one bond.

num_bonds

Supported API . Number of bonds connected to this atom. Read only.

num_explicit_bonds

Supported API . Number of bonds and missing-structure pseudobonds

occupancy

Supported API . Occupancy, floating point value.

radius

Supported API . Radius of atom.

residue

Supported API . Residue the atom belongs to. Read only.

rings()

Experimental API . Return Rings collection of rings this Atom participates in.

If ‘cross_residues’ is False, then rings that cross residue boundaries are not included. If ‘all_size_threshold’ is zero, then return only minimal rings, of any size. If it is greater than zero, then return all rings not larger than the given value.

The returned rings are quite emphemeral, and shouldn’t be cached or otherwise retained for long term use. They may only live until the next call to rings() [from anywhere, including C++].

scene_coord

Supported API . Atom center coordinates in the global scene coordinate system.

selected

Supported API . Whether the atom is selected.

serial_number

Supported API . Atom serial number from input file.

session

Experimental API . Session that this Atom is in

set_alt_loc()

Experimental API . Normally used to create alt locs.

set_hide_bits()

Experimental API . Set the hide bits ‘on’ that are ‘on’ in “bitmask”

string()

Supported API . Get text representation of Atom

structure

Supported API . AtomicStructure the atom belongs to

structure_category

Supported API . Whether atom is ligand, ion, etc. Read only.

use_default_radius()

Supported API . If an atom’s radius has previously been explicitly set,

visible

Supported API . Whether atom is displayed and not hidden.

class CyResidue

Bases: object

Base class for Residue, and is present only for performance reasons.

add_atom()

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

atoms

Supported API . Atoms collection containing all atoms of the residue.

bonds_between()

Supported API . Return the bonds between this residue and other_res as a Bonds collection.

center

Experimental API . Average of atom positions as a length 3 array, 64-bit float values.

chain

Supported API . Chain that this residue belongs to, if any. Read only.

chain_id

Supported API . PDB chain identifier. Limited to 4 characters. Read only string.

connects_to()

Supported API . Return True if this residue is connected by at least one bond

delete()

Supported API . Delete this Residue from it’s Structure

deleted

Supported API . Has the C++ side been deleted?

description

Experimental API . Description of residue (if available) from HETNAM/HETSYN records or equivalent

find_atom()

Supported API . Return the atom with the given name, or None if not found.

insertion_code

Supported API . PDB residue insertion code. 1 character or empty string.

is_helix

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

is_strand

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

mmcif_chain_id

Experimental API . mmCIF chain identifier. Limited to 4 characters. Read only string.

name

Supported API . Residue name. Maximum length 4 characters.

num_atoms

Supported API . Number of atoms belonging to the residue. Read only.

number

Supported API . Integer sequence position number from input data file. Read only.

polymer_type
Supported API . Polymer type of residue. Values are:
PT_NONE: not a polymeric residue PT_AMINO: amino acid PT_NUCLEIC: nucleotide

(Access as Residue.PT_XXX)

principal_atom

Experimental API . The ‘chain trace’ Atom, if any. Normally returns the C4’ from a nucleic acid since that is always present, but in the case of a P-only trace it returns the P.

ribbon_adjust

Experimental API . Smoothness adjustment factor (no adjustment = 0 <= factor <= 1 = idealized).

ribbon_color

Experimental API . Ribbon color RGBA length 4 sequence/array. Values in range 0-255

ribbon_display

Experimental API . Whether to display the residue as a ribbon/pipe/plank. Boolean value.

ribbon_hide_backbone

Experimental API . Whether a ribbon automatically hides the residue backbone atoms. Boolean value.

set_alt_loc()

Experimental API . Set the appropiate atoms in the residue to the given (existing) alt loc

ss_id

Experimental API . Secondary structure id number. Integer value.

ss_type

Supported API . Secondary structure type of residue. Integer value.

string()

Supported API . Get text representation of Residue

structure

Supported API . ‘AtomicStructure that this residue belongs to. Read only.

class Element

Bases: object

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

static bond_length()

Supported API . Standard single-bond length between two elements.

static bond_radius()

Supported API . Standard single-bond ‘radius’

static get_element()

Supported API . Given an atomic symbol or atomic number, return the

is_alkali_metal

Supported API . Is atom an alkali metal? Read only

is_halogen

Supported API . Is atom a halogen? Read only

is_metal

Supported API . Is atom a metal? Read only

is_noble_gas

Supported API . Is atom a noble gas? Read only

mass

Supported API . Atomic mass, taken from

name

Supported API . Atomic symbol. Read only

number

Supported API . Atomic number. Read only

valence

Supported API . Electronic valence number, for example 7 for chlorine. Read only

molarray: Collections of molecular objects

These classes Atoms, Bonds, Residues… provide access to collections of C++ molecular data objects. One typically gets these from an AtomicStructure object which is produced by reading a PDB file.

Data items in a collections are ordered and the same object may be repeated.

Collections have attributes such as Atoms.coords that return a numpy array of values for each object in the collection. This offers better performance than using a Python list of atoms since it directly accesses the C++ atomic data. When using a list of atoms, a Python Atom object is created for each atom which requires much more memory and is slower to use in computation. Working with lists is still often desirable when computations are not easily done using arrays of attributes. To get a list of atoms use list(x) where x is an Atoms collection. Collections behave as Python iterators so constructs such as a “for” loop over an Atoms collection is valid: “for a in atoms: …”.

There are collections Atoms, Bonds, Pseudobonds, Residues, Chains, AtomicStructures.

Some attributes return collections instead of numpy arrays. For example, atoms.residues returns a Residues collection that has one residue for each atom in the collection atoms. If only a collection unique residues are desired, use atoms.unique_residues.

Collections have base class Collection which provides many standard methods such as length, iteration, indexing with square brackets, index of an element, intersections, unions, subtraction, filtering….

Collections are mostly immutable. The only case in which their contents can be altered is if C++ objects they hold are deleted in which case those objects are automatically removed from the collection. Because they are mutable they cannot be used as keys in dictionary or added to sets.

class Collection(items, object_class, objects_class)

Bases: State

Base class of all molecular data collections that provides common methods such as length, iteration, indexing with square brackets, intersection, union, subtracting, and filtering. By design, a Collection is immutable.

hash()

Experimental API . Can be used for quickly determining if collections have the same elements in the same order. Objects are automatically deleted from the collection when the C++ object is deleted. So this hash value will not be valid if the collection changes. This is not the __hash__ special Python method and it is not supported to use collections as keys of dictionaries or elements of sets since they are mutable.

__len__()

Experimental API . Number of objects in collection.

__iter__()

Experimental API . Iterator over collection objects.

__getitem__(i)

Experimental API . Indexing of collection objects using square brackets, e.g. c[i].

index(object)

Experimental API . Find the position of the first occurence of an object in a collection.

indices(objects)

Experimental API . Return int32 array indicating for each element in objects its index of the first occurence in the collection, or -1 if it does not occur in the collection.

__or__(objects)

Experimental API . The or operator | takes the union of two collections removing duplicates.

__and__(objects)

Experimental API . The and operator & takes the intersection of two collections removing duplicates.

__sub__(objects)

Experimental API . The subtract operator “-” subtracts one collection from another as sets, eliminating all duplicates.

copy()

Experimental API . Shallow copy, since Collections are immutable.

intersect(objects)

Experimental API . Return a new collection that is the intersection with the objects Collection.

intersects(objects)

Experimental API . Whether this collection has any element in common with the objects Collection. Returns bool.

intersects_each(objects_list)

Experimental API . Check if each of serveral pointer arrays intersects this array. Return a boolean array of length equal to the length of objects_list.

filter(mask_or_indices)

Experimental API . Return a subset of the collection as a new collection.

Parameters:
mask_or_indices : numpy bool array (mask) or int array (indices)

Bool length must match the length of the collection and filters out items where the bool array is False.

mask(objects)

Experimental API . Return bool array indicating for each object in current set whether that object appears in the argument objects.

merge(objects)

Experimental API . Return a new collection combining this one with the objects Collection. All duplicates are removed.

subtract(objects)

Experimental API . Return a new collection subtracting the objects Collection from this one. All duplicates are removed. Currently does not preserve order

unique()

Experimental API . Return a new collection containing the unique elements from this one, preserving order.

instances(instantiate=True)

Experimental API . Returns a list of the Python instances. If ‘instantiate’ is False, then for those items that haven’t yet been instantiated, None will be returned.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

classmethod restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

concatenate(collections, object_class=None, remove_duplicates=False)

Experimental API . Concatenate any number of collections returning a new collection. All collections must have the same type.

Parameters:
collections : sequence of Collection objects
unique_ordered(a)

Experimental API . Return unique elements of numpy array a preserving order.

class StructureDatas(mol_pointers)

Bases: Collection

Collection of C++ atomic structure objects.

alt_loc_change_notifies

Experimental API . Whether notifications are issued when altlocs are changed. Should only be set to true when temporarily changing alt locs in a Python script. Numpy bool array.

active_coordsets

Experimental API . Returns a CoordSets of the active coordset of each structure. Read only.

atoms

Experimental API . A single Atoms containing atoms for all structures. Read only.

bonds

Experimental API . A single Bonds object containing bonds for all structures. Read only.

chains

Experimental API . A single Chains object containing chains for all structures. Read only.

lower_case_chains

Experimental API . A numpy bool array of lower_case_names of each structure.

num_atoms

Experimental API . Number of atoms in each structure. Read only.

num_bonds

Experimental API . Number of bonds in each structure. Read only.

num_chains

Experimental API . Number of chains in each structure. Read only.

num_residues

Experimental API . Number of residues in each structure. Read only.

residues

Experimental API . A single Residues object containing residues for all structures. Read only.

pbg_maps

Experimental API . Returns a list of dictionaries whose keys are pseudobond group categories (strings) and whose values are Pseudobonds. Read only.

ribbon_tether_scales

Experimental API . Returns an array of scale factors for ribbon tethers.

ribbon_tether_sides

Experimental API . Returns an array of numbers of sides for ribbon tethers.

ribbon_tether_shapes

Experimental API . Returns an array of shapes for ribbon tethers.

metadata

Experimental API . Return a list of dictionaries with metadata. Read only.

ribbon_tether_opacities

Experimental API . Returns an array of opacity scale factor for ribbon tethers.

ribbon_show_spines

Experimental API . Returns an array of booleans of whether to show ribbon spines.

ribbon_orientations

Experimental API . Returns an array of ribbon orientations.

ss_assigneds

Experimental API . Whether secondary structure has been assigned, either from data in the original structure file, or from an algorithm (e.g. dssp command)

class AtomicStructures(mol_pointers)

Bases: StructureDatas

Collection of Python atomic structure objects.

class Atoms(atom_pointers=None)

Bases: Collection

An ordered collection of atom objects. This offers better performance than using a list of atoms. It provides methods to access atom attributes such as coordinates as numpy arrays. Atoms directly accesses the C++ atomic data without creating Python Atom objects which require much more memory and are slower to use in computation.

by_chain

Experimental API . Return list of triples of structure, chain id, and Atoms for each chain.

by_structure

Experimental API . Return list of 2-tuples of (structure, Atoms for that structure).

colors

Experimental API . Returns a numpy Nx4 array of uint8 RGBA values. Can be set with such an array (or equivalent sequence), or with a single RGBA value.

coords

Experimental API . Returns a numpy Nx3 array of XYZ values. Can be set.

coord_indices

Experimental API . Coordinate index of atom in coordinate set.

displays

Experimental API . Controls whether the Atoms should be displayed. Returns a numpy array of boolean values. Can be set with such an array (or equivalent sequence), or with a single boolean value.

draw_modes

Experimental API . Controls how the Atoms should be depicted. The values are integers, SPHERE_STYLE, BALL_STYLE or STICK_STYLE as documented in the Atom class. Returns a numpy array of integers. Can be set with such an array (or equivalent sequence), or with a single integer value.

elements

Experimental API . Returns a Elements whose data items correspond in a 1-to-1 fashion with the items in the Atoms. Read only.

element_names

Experimental API . Returns a numpy array of chemical element names. Read only.

element_numbers

Experimental API . Returns a numpy array of atomic numbers (integers). Read only.

names

Experimental API . Returns a numpy array of atom names. Can be set with such an array (or equivalent sequence), or with a single string. Atom names are limited to 4 characters.

hides

Experimental API . Whether atom is hidden (overrides display). Returns a numpy array of int32 bitmask.

Possible values:

HIDE_RIBBON
Hide mask for backbone atoms in ribbon.

Can be set with such an array (or equivalent sequence), or with a single integer value.

set_hide_bits(bit_mask)

Experimental API . Set Atom’s hide bits in bit mask

clear_hide_bits(bit_mask)

Experimental API . Clear Atom’s hide bits in bit mask

idatm_types

Experimental API . Returns a numpy array of IDATM types. Can be set with such an array (or equivalent sequence), or with a single string.

in_chains

Experimental API . Whether each atom belong to a polymer. Returns numpy bool array. Read only.

is_riboses

Experimental API . Whether each atom is part of an nucleic acid ribose moiety. Returns numpy bool array. Read only.

is_side_chains

Experimental API . Whether each atom is part of an amino/nucleic acid sidechain. Includes atoms needed to connect to backbone (CA/ribose). Returns numpy bool array. Read only.

is_side_connectors

Experimental API . Whether each atom is needed to connect to backbone (CA/ribose). Returns numpy bool array. Read only.

is_side_onlys

Experimental API . Whether each atom is part of an amino/nucleic acid sidechain. Does not include atoms needed to connect to backbone (CA/ribose). Returns numpy bool array. Read only.

intra_bonds

Experimental API . Bonds object where both endpoint atoms are in this collection

radii

Experimental API . Returns a numpy array of radii. Can be set with such an array (or equivalent sequence), or with a single floating-point number.

default_radii

Experimental API . Returns a numpy array of default radii.

maximum_bond_radii(default_radius=0.2)

Experimental API . Return maximum bond radius for each atom. Used for stick style atom display.

residues

Experimental API . Returns a Residues whose data items correspond in a 1-to-1 fashion with the items in the Atoms. Read only.

scene_bounds

Experimental API . Return scene bounds of atoms including instances of all parent models.

scene_coords

Experimental API . Atoms’ coordinates in the global scene coordinate system. This accounts for the Drawing positions for the hierarchy of models each atom belongs to.

selected

Experimental API . numpy bool array whether each Atom is selected.

selecteds

Experimental API . numpy bool array whether each Atom is selected.

num_selected

Experimental API . Number of selected atoms.

has_selected_bonds

Experimental API . For each atom is any connected bond selected.

serial_numbers

Experimental API . Serial numbers of atoms

shown_atoms

Experimental API . Subset of Atoms including atoms that are displayed or have ribbon displayed and have displayed structure and displayed parent models.

structure_categories

Experimental API . Numpy array of whether atom is ligand, ion, etc.

structures

Experimental API . Returns an AtomicStructure for each atom. Read only.

unique_residues

Experimental API . The unique Residues for these atoms.

unique_chain_ids

Experimental API . The unique chain IDs as a numpy array of strings.

unique_structures

Experimental API . The unique structures as an AtomicStructures collection

full_residues

Experimental API . The Residues all of whose atoms are in this Atoms instance

full_structures

Experimental API . The Structures all of whose atoms are in this Atoms instance

single_structure

Experimental API . Do all atoms belong to a single Structure

visibles

Experimental API . Returns whether the Atom should be visible (displayed and not hidden). Returns a numpy array of boolean values. Read only.

alt_locs

Experimental API . Returns current alternate location indicators

delete()

Experimental API . Delete the C++ Atom objects

update_ribbon_visibility()

Experimental API . Update the ‘hide’ status for ribbon control point atoms, which are hidden unless any of its neighbors are visible.

has_aniso_u

Experimental API . Boolean array identifying which atoms have anisotropic temperature factors.

aniso_u

Experimental API . Anisotropic temperature factors, returns Nx3x3 array of numpy float32 or None if any of the atoms does not have temperature factors. Read only.

aniso_u6

Experimental API . Get anisotropic temperature factors as a Nx6 array of numpy float32 containing (u11,u22,u33,u12,u13,u23) for each atom or None if any of the atoms does not have temperature factors.

residue_sums(atom_values)

Experimental API . Compute per-residue sum of atom float values. Return unique residues and array of residue sums.

class Bonds(bond_pointers=None)

Bases: Collection

Collection of C++ bonds.

atoms

Experimental API . Returns a two-tuple of Atoms objects. For each bond, its endpoint atoms are in the matching position in the two Atoms collections. Read only.

colors

Experimental API . Returns a numpy Nx4 array of uint8 RGBA values. Can be set with such an array (or equivalent sequence), or with a single RGBA value.

displays

Experimental API . Controls whether the Bonds should be displayed. Returns a numpy array of bool. Can be set with such an array (or equivalent sequence), or with a single value. Bonds are shown only if display is true, hide is false, and both atoms are shown.

visibles

Experimental API . Returns whether the Bonds should be visible regardless of whether the atoms on either end is shown. Returns a numpy array of bool. Read only.

halfbonds

Experimental API . Controls whether the Bonds should be colored in “halfbond” mode, i.e. each half colored the same as its endpoint atom. Returns a numpy array of boolean values. Can be set with such an array (or equivalent sequence), or with a single boolean value.

radii

Experimental API . Returns a numpy array of bond radii (half thicknesses). Can be set with such an array (or equivalent sequence), or with a single floating-point number.

selected

Experimental API . numpy bool array whether each Bond is selected.

ends_selected

Experimental API . For each bond are both of its endpoint atoms selected.

showns

Experimental API . Whether each bond is displayed, visible and has both atoms shown, and at least one atom is not Sphere style.

structures

Experimental API . Returns an StructureDatas with the structure for each bond. Read only.

unique_structures

Experimental API . The unique structures as an AtomicStructures collection

by_structure

Experimental API . Return list of 2-tuples of (structure, Bonds for that structure).

delete()

Experimental API . Delete the C++ Bonds objects

num_shown

Experimental API . Number of bonds shown.

num_selected

Experimental API . Number of selected bonds.

half_colors

Experimental API . 2N x 4 RGBA uint8 numpy array of half bond colors.

halfbond_cylinder_placements(opengl_array=None)

Experimental API . Return Places for halfbond cylinders specified by 2N 4x4 float matrices.

class Elements(element_pointers)

Bases: Collection

Holds a collection of C++ Elements (chemical elements) and provides access to some of their attributes. Used for the same reasons as the Atoms class.

names

Experimental API . Returns a numpy array of chemical element names. Read only.

numbers

Experimental API . Returns a numpy array of atomic numbers (integers). Read only.

masses

Experimental API . Returns a numpy array of atomic masses, taken from http://en.wikipedia.org/wiki/List_of_elements_by_atomic_weight. Read only.

is_alkali_metal

Experimental API . Returns a numpy array of booleans, where True indicates the element is atom an alkali metal. Read only.

is_halogen

Experimental API . Returns a numpy array of booleans, where True indicates the element is atom a halogen. Read only.

is_metal

Experimental API . Returns a numpy array of booleans, where True indicates the element is atom a metal. Read only.

is_noble_gas

Experimental API . Returns a numpy array of booleans, where True indicates the element is atom a noble gas. Read only.

valences

Experimental API . Returns a numpy array of atomic valence numbers (integers). Read only.

class Pseudobonds(pbond_pointers=None)

Bases: Collection

Holds a collection of C++ PBonds (pseudobonds) and provides access to some of their attributes. It has the same attributes as the Bonds class and works in an analogous fashion.

atoms

Experimental API . Returns a two-tuple of Atoms objects. For each bond, its endpoint atoms are in the matching position in the two Atoms collections. Read only.

colors

Experimental API . Returns a numpy Nx4 array of uint8 RGBA values. Can be set with such an array (or equivalent sequence), or with a single RGBA value.

displays

Experimental API . Controls whether the pseudobonds should be displayed. Returns a numpy array of bool. Can be set with such an array (or equivalent sequence), or with a single value. Pseudobonds are shown only if display is true, hide is false, and both atoms are shown.

groups

Experimental API . Returns a PseudobondGroups collection of the pseudobond groups these pseudobonds belong to

halfbonds

Experimental API . Controls whether the pseudobonds should be colored in “halfbond” mode, i.e. each half colored the same as its endpoint atom. Returns a numpy array of boolean values. Can be set with such an array (or equivalent sequence), or with a single boolean value.

radii

Experimental API . Returns a numpy array of pseudobond radii (half thicknesses). Can be set with such an array (or equivalent sequence), or with a single floating-point number.

selected

Experimental API . numpy bool array whether each Pseudobond is selected.

showns

Experimental API . Whether each pseudobond is displayed, visible and has both atoms displayed.

shown_when_atoms_hiddens

Experimental API . Controls whether the pseudobond is shown when the endpoint atoms are not explictly displayed (atom.display == False) but are implicitly shown by a ribbon or somesuch (atom.hide != 0). Defaults to True.

delete()

Experimental API . Delete the C++ Pseudobond objects

lengths

Experimental API . Distances between pseudobond end points.

half_colors

Experimental API . 2N x 4 RGBA uint8 numpy array of half bond colors.

between_atoms(atoms)

Experimental API . Return mask of those pseudobonds which have both ends in the given set of atoms.

unique_structures

Experimental API . The unique structures as a StructureDatas collection

by_group

Experimental API . Return list of 2-tuples of (PseudobondGroup, Pseudobonds for that group).

num_selected

Experimental API . Number of selected pseudobonds.

class Residues(residue_pointers=None)

Bases: Collection

Collection of C++ residue objects.

atoms

Experimental API . Return Atoms belonging to each residue all as a single collection. Read only.

centers

Experimental API . Average of atom positions as a numpy length 3 array, 64-bit float values.

chains

Experimental API . Return Chains for residues. Residues with no chain are omitted. Read only.

chain_ids

Experimental API . Returns a numpy array of chain IDs. Read only.

mmcif_chain_ids

Experimental API . Returns a numpy array of chain IDs. Read only.

insertion_codes

Experimental API . Returns a numpy array of insertion codes. An empty string indicates no insertion code.

is_helix

Experimental API . Returns a numpy bool array whether each residue is in a protein helix

is_strand

Experimental API . Returns a numpy bool array whether each residue is in a protein sheet

names

Experimental API . Returns a numpy array of residue names.

num_atoms

Experimental API . Returns a numpy integer array of the number of atoms in each residue. Read only.

numbers

Experimental API . Returns a numpy array of residue sequence numbers, as provided by whatever data source the structure came from, so not necessarily consecutive, or starting from 1, etc. Read only.

polymer_types

Experimental API . Returns a numpy int array of residue types. Read only.

principal_atoms

Experimental API . List of the ‘chain trace’ Atoms or None (for residues without such an atom).

Normally returns the C4’ from a nucleic acid since that is always present, but in the case of a P-only trace it returns the P.

existing_principal_atoms

Experimental API . Like the principal_atoms property, but returns a Residues collection omitting Nones

ribbon_displays

Experimental API . A numpy bool array whether to display each residue in ribbon style.

ribbon_colors

Experimental API . A numpy Nx4 array of uint8 RGBA values. Can be set with such an array (or equivalent sequence), or with a single RGBA value.

ribbon_adjusts

Experimental API . A numpy float array of adjustment factors for the position of ribbon control points. Factors range from zero to one, with zero being using the actual atomic coordinates as control point, and one being using the idealized secondary structure position as control point. A negative value means to use the default of zero for turns and helices and 0.7 for strands.

ribbon_hide_backbones

Experimental API . A numpy array of booleans. Whether a ribbon automatically hides the residue backbone atoms.

secondary_structure_ids

Experimental API . A numpy array of integer secondary structure ids. Every helix, sheet, coil has a unique integer id. The ids depend on the collection of residues on the fly and are not persistent. Read only.

ss_ids

Experimental API . A numpy array of integer secondary structure IDs, determined by the input file. For a PDB file, for helices, the ID is the same as in the HELIX record; for strands, it starts as 1 for the strand nearest the N terminus, and increments for each strand out to the C terminus.

ss_types

Experimental API . Returns a numpy integer array of secondary structure types (one of: Residue.SS_COIL, Residue.SS_HELIX, Residue.SS_STRAND [or SS_SHEET])

structures

Experimental API . Returns StructureDatas collection containing structures for each residue.

delete()

Experimental API . Delete the C++ Residue objects

unique_structures

Experimental API . The unique structures as a StructureDatas collection

unique_names

Experimental API . The unique names as a numpy array of strings.

unique_chain_ids

Experimental API . The unique chain IDs as a numpy array of strings.

unique_chains

Experimental API . The unique chains as a Chains collection

by_chain

Experimental API . Return list of structure, chain id, and Residues for each chain.

by_structure

Experimental API . Return list of pairs of structure and Residues for that structure.

unique_ids

Experimental API . A numpy array of uintp (unsigned integral type large enough to hold a pointer). Multiple copies of the same residue in the collection will have the same integer value in the returned array. Read only.

unique_sequences

Experimental API . Return a list of sequence strings and a numpy array giving an integer index for each residue. Index 0 is for residues that are not part of a chain (empty string).

get_polymer_spline()

Experimental API . Return a tuple of spline center and guide coordinates for a polymer chain. Residues in the chain that do not have a center atom will have their display bit turned off. Center coordinates are returned as a numpy array. Guide coordinates are only returned if all spline atoms have matching guide atoms; otherwise, None is returned for guide coordinates.

ribbon_clear_hides()

Experimental API . Clear the hide bit for all atoms in given residues.

ribbon_num_selected

Experimental API . Number of selected residue ribbons.

ribbon_selected

Experimental API . numpy bool array whether each Residue ribbon is selected.

class Rings(ring_pointers=None, rings=None)

Bases: Collection

Collection of C++ ring objects.

aromatics

Experimental API . A numpy bool array whether corresponding ring is aromatic.

atoms

Experimental API . Return Atoms belonging to each ring all as a single collection. Read only.

bonds

Experimental API . Return Bonds belonging to each ring all as a single collection. Read only.

sizes

Experimental API . Returns a numpy integer array of the size of each ring. Read only.

class Chains(chain_pointers)

Bases: Collection

Collection of C++ chain objects.

chain_ids

Experimental API . A numpy array of string chain ids for each chain. Read only.

structures

Experimental API . A StructureDatas collection containing structures for each chain.

existing_residues

Experimental API . A Residues containing the existing residues of all chains. Read only.

num_existing_residues

Experimental API . A numpy integer array containing the number of existing residues in each chain.

num_residues

Experimental API . A numpy integer array containing the number of residues in each chain.

polymer_types

Experimental API . Returns a numpy int array of residue types. Same values as Residues.polymer_types except shouldn’t return PT_NONE.

class PseudobondGroupDatas(pbg_pointers)

Bases: Collection

Collection of C++ pseudobond group objects.

pseudobonds

Experimental API . A single Pseudobonds object containing pseudobonds for all groups. Read only.

names

Experimental API . A numpy string array of categories of each group.

num_pseudobonds

Experimental API . Number of pseudobonds in each group. Read only.

class PseudobondGroups(pbg_pointers)

Bases: PseudobondGroupDatas

Collection of Python pseudobond group objects.

class CoordSets(cs_pointers=None)

Bases: Collection

Collection of C++ coordsets.

ids

Experimental API . ID numbers of coordsets

structures

Experimental API . Returns an AtomicStructure for each coordset. Read only.

unique_structures

Experimental API . The unique structures as a AtomicStructures collection

class PseudobondGroup(pbg_pointer, *, session=None)

Bases: PseudobondGroupData, Model

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.

any_part_selected()

Experimental API . Is any part of this Drawing or its children selected.

clear_selection()

Experimental API . Unselect this drawing and child drawings in if include_children is True.

dashes

Experimental API . How many dashes pseudobonds will be drawn with

delete()

Experimental API . Delete drawing and all child drawings.

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for selecting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

name

Supported API . The name of the group.

planes_pick(planes, exclude=None)

Experimental API . Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for selecting objects in a frustum.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

selected_pseudobonds(session)

Experimental API . All selected bonds in all structures as an Bonds collection.

molsurf: Compute molecular surfaces

class MolecularSurface(session, enclose_atoms, show_atoms, probe_radius, grid_spacing, resolution, level, name, color, visible_patches, sharp_boundaries)

Bases: Surface

A molecular surface computed from a set of atoms. This can be a solvent excluded surface which is the boundary of the region where a sphere of radius probe_radius cannot reach. Or it can be a contour surface of a density map created by placing Gaussian shapes at the center of each atom position where the resolution parameter controls the width of the Gaussian. Part of a surface can be undisplayed, leaving only the patch associated with show_atoms Atoms.

Parameters:
session : Session

The session the surface model will belong to

enclose_atoms : Atoms

Surface bounds these atoms.

show_atoms : Atoms

Show only the portion of the surface near these atoms.

probe_radius : float

The probe sphere radius for a solvent excluded surface.

grid_spacing : float

Spacing of 3-dimensional grid used in surface calculations. Typical value os 0.5 Angstroms. Finer values give smoother surfaces but take more memory and longer computation times.

resolution : float

Used only for Gaussian surfaces, specifies a nominal density map resolution. See the molmap() for details.

level : float or None

Threshold level for Gaussian surfaces. The density map used to compute these surface uses Gaussian heights equal to atomic number so the level is in atomic number units. If None is specified then the level chosen is the minimum density at the atom positions.

name : string

Surface name.

color : numpy uint8 length 4 array

RGBA color for surface.

visible_patches : int or None

Number of connected surface components to show. Only the largest area N components will be shown. For value None all components are shown.

sharp_boundaries : bool

Whether to subdivide triangles composing the surface so that triangle edges lie exactly between atoms. This creates less jagged edges when showing or coloring patches of surfaces for a subset of atoms.

atom_count

Experimental API . Number of atoms for calculating the surface. Read only.

calculate_surface_geometry()

Experimental API . Recalculate the surface if parameters have been changed.

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for selecting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

hide(atoms)

Experimental API . Hide the surface patch near these Atoms.

new_parameters(show_atoms, probe_radius=None, grid_spacing=None, resolution=None, level=None, visible_patches=None, sharp_boundaries=None, color=None, transparency=None)

Experimental API . Change the surface parameters. Parameter definitions are the same as for the contructor.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

show(atoms, only=False)

Experimental API . Show the surface patch near these Atoms in addition to any already shown surface patch.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

vertex_to_atom_map(vertices=None)

Experimental API . Returns a numpy array of integer values with length equal to the number of surface vertices and value is the atom index for the atom closest to each vertex. Can return None if atoms are not associated with vertices. Supplying vertices argument computes new vertex to atom map.

remove_solvent_ligands_ions(atoms, keep=None)

Experimental API . Remove solvent, ligands and ions unless that removes all atoms in which case don’t remove any.