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.

property active_coordset

Supported API. Currently active CoordSet. Read only.

property active_coordset_change_notify

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

property active_coordset_id

Supported API. Index of the active coordinate set.

add(self, models)

Experimental API . Add child models to this model.

add_coordset(self, id, xyz)

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

add_coordsets(self, xyzs, replace=True)

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

add_drawing(self, d)

Experimental API . Add a child drawing.

all_drawings(self, displayed_only=False)

Experimental API . Return all drawings including self and children at all levels.

all_models(self)

Experimental API . Return all models including self and children at all levels.

property alt_loc_change_notify

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

any_part_highlighted(self)

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

property atoms

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

property atomspec

Return the atom specifier string for this structure.

property ball_scale

Scales sphere radius in ball-and-stick style.

property bonds

Bonds collection containing all bonds of the structure.

bounds(self)

Experimental API . The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

bounds_intercept_copies(self, bounds, mxyz1, mxyz2)

Experimental API . Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

chain_trace_atoms(self)

Experimental API . Find pairs of atoms that should be connected in a chain trace. Returns None or a 2-tuple of two Atoms instances where corresponding atoms should be connected. A chain trace connects two adjacent CA atoms if both atoms are shown but the intervening C and N atoms are not shown, and no ribbon depiction connects the residues. Adjacent means that there is a bond between the two residues. So for instance CA-only structures has no bond between the residues and those do not show a chain trace connection, instead they show a “missing structure” connection. For nucleic acid chains adjacent displayed P atoms with undisplayed intervening O3’ and O5’ atoms are part of a chain trace.

property chains

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

property change_tracker

The ChangeTracker currently in use by this structure. Read only.

child_drawings(self)

Experimental API . Return the list of surface pieces.

child_models(self)

Experimental API . Return child models.

clear_highlight(self, include_children=True)

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

combine_sym_atoms(self)

Experimental API . Combine “symmetry” atoms, which for this purpose is atoms with the same element type on the exact same 3D position

connect_structure(self, *, bond_length_tolerance=0.4, metal_coordination_distance=3.6)

Experimental API . Generate bonds and relevant pseudobonds (missing structure; metal coordination) for structure. Typically used for structures where only the atom positions and not the connectivity is known.

‘bond_length_tolerance’ is how much longer the inter-atom distance can exceed the ideal bond length and still have a bond created between the atoms.

‘metal_coordination_distance’ is the maximum distance between a metal and a possibly coordinating atom that will generate a metal-coordination pseudobond.

coordset(self, cs_id)

Supported API . Return the CoordSet for the given coordset ID

property coordset_ids

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

property coordset_size

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

copy(self, 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.

property cpp_pointer

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

custom_x3d(self, stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

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

delete(self)

Experimental API . Delete this structure.

delete_alt_locs(self)

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

delete_atom(self, atom)

Supported API . Delete the specified Atom.

delete_bond(self, bond)

Supported API . Delete the specified Bond.

property deleted

Has the C++ side been deleted?

draw(self, renderer, draw_pass)

Experimental API . Draw this drawing using the given draw pass. Does not draw child drawings

draw_self(self, renderer, draw_pass)

Experimental API . Draw this drawing without children using the given draw pass.

property drawing_lineage

Return a sequence of drawings from the root down to the current drawing.

empty_drawing(self)

Experimental API . Does this drawing have no geometry? Does not consider child drawings.

first_intercept(self, 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 highlighting 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.

first_intercept_children(self, child_drawings, mxyz1, mxyz2, exclude=None)

Experimental API . Like first_intercept() but check for intercepts with just the specified children.

geometry_bounds(self)

Experimental API . Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

get_selected(self, include_children=False, fully=False)

Experimental API . Is this model selected? If fully is true then are all parts of this model selected?

has_formatted_metadata(self, session)

Experimental API . Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property id_string

Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

Returns:

A string. If the model has not been assigned an identifier, an empty string is returned.

property lower_case_chains

Supported API. Structure has lower case chain ids. Boolean

property metadata

Supported API. Dictionary with metadata. Read only.

property molecules

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(self, 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. It is advisible to add the atom to its residue as soon as possible since errors that occur in between can crash ChimeraX. Also, there are functions in chimerax.atomic.struct_edit for adding atoms that are considerably less tedious and error-prone than using new_atom() and related calls.

new_bond(self, atom1, atom2)

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

new_coordset(self, 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_drawing(self, name, *, subclass=None)

Experimental API . Create a new empty child drawing.

new_residue(self, residue_name, chain_id, pos, insert=None, *, precedes=None)

Supported API . Create a new Residue. If ‘precedes’ is None, new residue will be appended to residue list, otherwise the new residue will be inserted before the ‘precedes’ resdidue.

property nonstandard_residue_names

“ligand-y” residue names in this structure

property normals

Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

property num_atoms

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

property num_atoms_visible

Number of visible atoms in structure. Read only.

property num_bonds

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

property num_bonds_visible

Number of visible bonds in structure. Read only.

property num_chains

Supported API. Number of chains structure. Read only.

property num_coordsets

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

property num_residues

Supported API. Number of residues structure. Read only.

number_of_positions(self, displayed_only=False)

Experimental API . Number of positions the Drawing is placed at.

number_of_triangles(self, displayed_only=False)

Experimental API . Return the number of triangles including all child drawings and all positions.

property pbg_map

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

property pdb_version

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

planes_pick(self, 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 highlighting objects in a frustum.

polymers(self, 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(self, name, *, create_type='normal')

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

redraw_needed(self, **kw)

Experimental API . Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

remove_all_drawings(self, delete=True)

Experimental API . Remove all child drawings.

remove_coordsets(self)

Experimental API . Remove all coordinate sets.

remove_drawing(self, d, delete=True)

Experimental API . Remove a specified child drawing.

remove_drawings(self, drawings, delete=True)

Experimental API . Remove specified child drawings.

reorder_residues(self, new_order)

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

property residues

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

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

property ribbon_display_count

Return number of residues with ribbon display set. Integer.

property ribbon_mode_helix

Ribbon mode for helices. Integer value.

property ribbon_mode_strand

Ribbon mode for strands. Integer value.

property ribbon_orientation

Ribbon orientation. Integer value.

ribbon_orients(self, residues=None)

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

property ribbon_show_spine

Display ribbon spine. Boolean.

property ribbon_tether_opacity

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

property ribbon_tether_scale

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

property ribbon_tether_shape

Ribbon tether shape. Integer value.

property ribbon_tether_sides

Number of sides for ribbon tether. Integer value.

property ring_display_count

Return number of residues with ring display set. Integer.

rings(self, 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(self, session, flags)

Experimental API . Gather session info; return version number

session_atom_to_id(self, ptr)

Experimental API . Map Atom pointer to session ID

session_bond_to_id(self, ptr)

Experimental API . Map Bond pointer to session ID

session_chain_to_id(self, ptr)

Experimental API . Map Chain pointer to session ID

session_id_to_atom(self, i)

Experimental API . Map sessionID to Atom pointer

session_id_to_bond(self, i)

Experimental API . Map sessionID to Bond pointer

session_id_to_chain(self, i)

Experimental API . Map sessionID to Chain pointer

session_id_to_residue(self, i)

Experimental API . Map sessionID to Residue pointer

session_residue_to_id(self, ptr)

Experimental API . Map Residue pointer to session ID

set_color(self, color)

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

set_geometry(self, vertices, normals, triangles)

Experimental API . Set vertices, normals and triangles defining the shape to be drawn.

set_state_from_snapshot(self, session, data)

Experimental API . Restore from session info

set_transparency(self, alpha)

Experimental API . Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

show_metadata(self, session, *, verbose=False, log=None, **kw)

Experimental API . called by ‘log metadata’ command.

showing_transparent(self)

Experimental API . Are any transparent objects being displayed. Includes all children.

property ss_assigned

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

string(self, style=None)

Experimental API . Return a human-readable string for this structure.

surfaces(self)

Experimental API . List of MolecularSurface objects for this structure.

take_snapshot(self, 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.

property triangles

Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

use_default_atom_radii(self)

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

property vertices

Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

class AtomsDrawing(name)

Bases: Drawing

add_drawing(self, d)

Experimental API . Add a child drawing.

all_drawings(self, displayed_only=False)

Experimental API . Return all drawings including self and children at all levels.

any_part_highlighted(self)

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

bounds(self)

Experimental API . The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

bounds_intercept_copies(self, bounds, mxyz1, mxyz2)

Experimental API . Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

child_drawings(self)

Experimental API . Return the list of surface pieces.

clear_highlight(self, include_children=True)

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

custom_x3d(self, stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

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

delete(self)

Experimental API . Delete drawing and all child drawings.

draw(self, renderer, draw_pass)

Experimental API . Draw this drawing using the given draw pass. Does not draw child drawings

draw_self(self, renderer, draw_pass)

Experimental API . Draw this drawing without children using the given draw pass.

property drawing_lineage

Return a sequence of drawings from the root down to the current drawing.

empty_drawing(self)

Experimental API . Does this drawing have no geometry? Does not consider child drawings.

first_intercept(self, 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 highlighting 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.

first_intercept_children(self, child_drawings, mxyz1, mxyz2, exclude=None)

Experimental API . Like first_intercept() but check for intercepts with just the specified children.

geometry_bounds(self)

Experimental API . Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

new_drawing(self, name, *, subclass=None)

Experimental API . Create a new empty child drawing.

property normals

Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

number_of_positions(self, displayed_only=False)

Experimental API . Number of positions the Drawing is placed at.

number_of_triangles(self, displayed_only=False)

Experimental API . Return the number of triangles including all child drawings and all positions.

planes_pick(self, 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 highlighting objects in a frustum.

redraw_needed(self, **kw)

Experimental API . Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

remove_all_drawings(self, delete=True)

Experimental API . Remove all child drawings.

remove_drawing(self, d, delete=True)

Experimental API . Remove a specified child drawing.

remove_drawings(self, drawings, delete=True)

Experimental API . Remove specified child drawings.

set_geometry(self, vertices, normals, triangles)

Experimental API . Set vertices, normals and triangles defining the shape to be drawn.

set_transparency(self, alpha)

Experimental API . Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

showing_transparent(self)

Experimental API . Are any transparent objects being displayed. Includes all children.

property triangles

Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

property vertices

Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

class BondsDrawing(name, pick_class, picks_class)

Bases: Drawing

add_drawing(self, d)

Experimental API . Add a child drawing.

all_drawings(self, displayed_only=False)

Experimental API . Return all drawings including self and children at all levels.

any_part_highlighted(self)

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

bounds(self)

Experimental API . The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

bounds_intercept_copies(self, bounds, mxyz1, mxyz2)

Experimental API . Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

child_drawings(self)

Experimental API . Return the list of surface pieces.

clear_highlight(self, include_children=True)

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

custom_x3d(self, stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

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

delete(self)

Experimental API . Delete drawing and all child drawings.

draw(self, renderer, draw_pass)

Experimental API . Draw this drawing using the given draw pass. Does not draw child drawings

draw_self(self, renderer, draw_pass)

Experimental API . Draw this drawing without children using the given draw pass.

property drawing_lineage

Return a sequence of drawings from the root down to the current drawing.

empty_drawing(self)

Experimental API . Does this drawing have no geometry? Does not consider child drawings.

first_intercept(self, 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 highlighting 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.

first_intercept_children(self, child_drawings, mxyz1, mxyz2, exclude=None)

Experimental API . Like first_intercept() but check for intercepts with just the specified children.

geometry_bounds(self)

Experimental API . Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

new_drawing(self, name, *, subclass=None)

Experimental API . Create a new empty child drawing.

property normals

Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

number_of_positions(self, displayed_only=False)

Experimental API . Number of positions the Drawing is placed at.

number_of_triangles(self, displayed_only=False)

Experimental API . Return the number of triangles including all child drawings and all positions.

planes_pick(self, 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 highlighting objects in a frustum.

redraw_needed(self, **kw)

Experimental API . Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

remove_all_drawings(self, delete=True)

Experimental API . Remove all child drawings.

remove_drawing(self, d, delete=True)

Experimental API . Remove a specified child drawing.

remove_drawings(self, drawings, delete=True)

Experimental API . Remove specified child drawings.

set_geometry(self, vertices, normals, triangles)

Experimental API . Set vertices, normals and triangles defining the shape to be drawn.

set_transparency(self, alpha)

Experimental API . Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

showing_transparent(self)

Experimental API . Are any transparent objects being displayed. Includes all children.

property triangles

Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

property vertices

Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

class LevelOfDetail(restore_data=None)

Bases: State

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(self, 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(self)

Experimental API . Text description of the picked object.

select(self, mode='add')

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

specifier(self)

Experimental API . Command specifier for the picked object.

class PickedAtoms(atoms)

Bases: Pick

description(self)

Experimental API . Text description of the picked object.

select(self, mode='add')

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

specifier(self)

Experimental API . Command specifier for the picked object.

class PickedBond(bond, distance)

Bases: Pick

description(self)

Experimental API . Text description of the picked object.

select(self, mode='add')

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

specifier(self)

Experimental API . Command specifier for the picked object.

class PickedBonds(bonds)

Bases: Pick

description(self)

Experimental API . Text description of the picked object.

select(self, mode='add')

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

specifier(self)

Experimental API . Command specifier for the picked object.

class PickedPseudobond(pbond, distance)

Bases: Pick

description(self)

Experimental API . Text description of the picked object.

select(self, mode='add')

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

specifier(self)

Experimental API . Command specifier for the picked object.

class PickedPseudobonds(pbonds)

Bases: Pick

description(self)

Experimental API . Text description of the picked object.

select(self, mode='add')

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

specifier(self)

Experimental API . Command specifier for the picked object.

class PickedResidue(residue, distance)

Bases: Pick

description(self)

Experimental API . Text description of the picked object.

select(self, mode='add')

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

specifier(self)

Experimental API . Command specifier for the picked object.

class PickedResidues(residues)

Bases: Pick

description(self)

Experimental API . Text description of the picked object.

select(self, mode='add')

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

specifier(self)

Experimental API . Command specifier for the picked object.

class RibbonDrawing(name)

Bases: Drawing

add_drawing(self, d)

Experimental API . Add a child drawing.

all_drawings(self, displayed_only=False)

Experimental API . Return all drawings including self and children at all levels.

any_part_highlighted(self)

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

bounds(self)

Experimental API . The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

bounds_intercept_copies(self, bounds, mxyz1, mxyz2)

Experimental API . Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

child_drawings(self)

Experimental API . Return the list of surface pieces.

clear_highlight(self, include_children=True)

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

custom_x3d(self, stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

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

delete(self)

Experimental API . Delete drawing and all child drawings.

draw(self, renderer, draw_pass)

Experimental API . Draw this drawing using the given draw pass. Does not draw child drawings

draw_self(self, renderer, draw_pass)

Experimental API . Draw this drawing without children using the given draw pass.

property drawing_lineage

Return a sequence of drawings from the root down to the current drawing.

empty_drawing(self)

Experimental API . Does this drawing have no geometry? Does not consider child drawings.

first_intercept(self, 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 highlighting 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.

first_intercept_children(self, child_drawings, mxyz1, mxyz2, exclude=None)

Experimental API . Like first_intercept() but check for intercepts with just the specified children.

geometry_bounds(self)

Experimental API . Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

new_drawing(self, name, *, subclass=None)

Experimental API . Create a new empty child drawing.

property normals

Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

number_of_positions(self, displayed_only=False)

Experimental API . Number of positions the Drawing is placed at.

number_of_triangles(self, displayed_only=False)

Experimental API . Return the number of triangles including all child drawings and all positions.

planes_pick(self, 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 highlighting objects in a frustum.

redraw_needed(self, **kw)

Experimental API . Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

remove_all_drawings(self, delete=True)

Experimental API . Remove all child drawings.

remove_drawing(self, d, delete=True)

Experimental API . Remove a specified child drawing.

remove_drawings(self, drawings, delete=True)

Experimental API . Remove specified child drawings.

set_geometry(self, vertices, normals, triangles)

Experimental API . Set vertices, normals and triangles defining the shape to be drawn.

set_transparency(self, alpha)

Experimental API . Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

showing_transparent(self)

Experimental API . Are any transparent objects being displayed. Includes all children.

property triangles

Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

property vertices

Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

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.

property active_coordset

Supported API. Currently active CoordSet. Read only.

property active_coordset_change_notify

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

property active_coordset_id

Supported API. Index of the active coordinate set.

add(self, models)

Experimental API . Add child models to this model.

add_coordset(self, id, xyz)

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

add_coordsets(self, xyzs, replace=True)

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

add_drawing(self, d)

Experimental API . Add a child drawing.

all_drawings(self, displayed_only=False)

Experimental API . Return all drawings including self and children at all levels.

all_models(self)

Experimental API . Return all models including self and children at all levels.

property alt_loc_change_notify

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

any_part_highlighted(self)

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

property atoms

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

property atomspec

Return the atom specifier string for this structure.

property autochain

Whether chain trace between principal residue atoms is shown when only those atoms are displayed.

property ball_scale

Scales sphere radius in ball-and-stick style.

property bonds

Bonds collection containing all bonds of the structure.

bounds(self)

Experimental API . The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

bounds_intercept_copies(self, bounds, mxyz1, mxyz2)

Experimental API . Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

chain_trace_atoms(self)

Experimental API . Find pairs of atoms that should be connected in a chain trace. Returns None or a 2-tuple of two Atoms instances where corresponding atoms should be connected. A chain trace connects two adjacent CA atoms if both atoms are shown but the intervening C and N atoms are not shown, and no ribbon depiction connects the residues. Adjacent means that there is a bond between the two residues. So for instance CA-only structures has no bond between the residues and those do not show a chain trace connection, instead they show a “missing structure” connection. For nucleic acid chains adjacent displayed P atoms with undisplayed intervening O3’ and O5’ atoms are part of a chain trace.

property chains

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

property change_tracker

The ChangeTracker currently in use by this structure. Read only.

child_drawings(self)

Experimental API . Return the list of surface pieces.

child_models(self)

Experimental API . Return child models.

clear_highlight(self, include_children=True)

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

combine_sym_atoms(self)

Experimental API . Combine “symmetry” atoms, which for this purpose is atoms with the same element type on the exact same 3D position

connect_structure(self, *, bond_length_tolerance=0.4, metal_coordination_distance=3.6)

Experimental API . Generate bonds and relevant pseudobonds (missing structure; metal coordination) for structure. Typically used for structures where only the atom positions and not the connectivity is known.

‘bond_length_tolerance’ is how much longer the inter-atom distance can exceed the ideal bond length and still have a bond created between the atoms.

‘metal_coordination_distance’ is the maximum distance between a metal and a possibly coordinating atom that will generate a metal-coordination pseudobond.

coordset(self, cs_id)

Supported API . Return the CoordSet for the given coordset ID

property coordset_ids

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

property coordset_size

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

copy(self, 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.

property cpp_pointer

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

custom_x3d(self, stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

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

delete(self)

Experimental API . Delete this structure.

delete_alt_locs(self)

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

delete_atom(self, atom)

Supported API . Delete the specified Atom.

delete_bond(self, bond)

Supported API . Delete the specified Bond.

property deleted

Has the C++ side been deleted?

draw(self, renderer, draw_pass)

Experimental API . Draw this drawing using the given draw pass. Does not draw child drawings

draw_self(self, renderer, draw_pass)

Experimental API . Draw this drawing without children using the given draw pass.

property drawing_lineage

Return a sequence of drawings from the root down to the current drawing.

empty_drawing(self)

Experimental API . Does this drawing have no geometry? Does not consider child drawings.

first_intercept(self, 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 highlighting 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.

first_intercept_children(self, child_drawings, mxyz1, mxyz2, exclude=None)

Experimental API . Like first_intercept() but check for intercepts with just the specified children.

geometry_bounds(self)

Experimental API . Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

get_selected(self, include_children=False, fully=False)

Experimental API . Is this model selected? If fully is true then are all parts of this model selected?

has_formatted_metadata(self, session)

Experimental API . Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property id_string

Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

Returns:

A string. If the model has not been assigned an identifier, an empty string is returned.

property lower_case_chains

Supported API. Structure has lower case chain ids. Boolean

property metadata

Supported API. Dictionary with metadata. Read only.

property molecules

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(self, 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. It is advisible to add the atom to its residue as soon as possible since errors that occur in between can crash ChimeraX. Also, there are functions in chimerax.atomic.struct_edit for adding atoms that are considerably less tedious and error-prone than using new_atom() and related calls.

new_bond(self, atom1, atom2)

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

new_coordset(self, 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_drawing(self, name, *, subclass=None)

Experimental API . Create a new empty child drawing.

new_residue(self, residue_name, chain_id, pos, insert=None, *, precedes=None)

Supported API . Create a new Residue. If ‘precedes’ is None, new residue will be appended to residue list, otherwise the new residue will be inserted before the ‘precedes’ resdidue.

property nonstandard_residue_names

“ligand-y” residue names in this structure

property normals

Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

property num_atoms

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

property num_atoms_visible

Number of visible atoms in structure. Read only.

property num_bonds

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

property num_bonds_visible

Number of visible bonds in structure. Read only.

property num_chains

Supported API. Number of chains structure. Read only.

property num_coordsets

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

property num_residues

Supported API. Number of residues structure. Read only.

number_of_positions(self, displayed_only=False)

Experimental API . Number of positions the Drawing is placed at.

number_of_triangles(self, displayed_only=False)

Experimental API . Return the number of triangles including all child drawings and all positions.

property pbg_map

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

property pdb_version

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

planes_pick(self, 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 highlighting objects in a frustum.

polymers(self, 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(self, name, *, create_type='normal')

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

redraw_needed(self, **kw)

Experimental API . Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

remove_all_drawings(self, delete=True)

Experimental API . Remove all child drawings.

remove_coordsets(self)

Experimental API . Remove all coordinate sets.

remove_drawing(self, d, delete=True)

Experimental API . Remove a specified child drawing.

remove_drawings(self, drawings, delete=True)

Experimental API . Remove specified child drawings.

reorder_residues(self, new_order)

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

property residues

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

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

property ribbon_display_count

Return number of residues with ribbon display set. Integer.

property ribbon_mode_helix

Ribbon mode for helices. Integer value.

property ribbon_mode_strand

Ribbon mode for strands. Integer value.

property ribbon_orientation

Ribbon orientation. Integer value.

ribbon_orients(self, residues=None)

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

property ribbon_show_spine

Display ribbon spine. Boolean.

property ribbon_tether_opacity

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

property ribbon_tether_scale

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

property ribbon_tether_shape

Ribbon tether shape. Integer value.

property ribbon_tether_sides

Number of sides for ribbon tether. Integer value.

property ring_display_count

Return number of residues with ring display set. Integer.

rings(self, 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(self, session, flags)

Experimental API . Gather session info; return version number

session_atom_to_id(self, ptr)

Experimental API . Map Atom pointer to session ID

session_bond_to_id(self, ptr)

Experimental API . Map Bond pointer to session ID

session_chain_to_id(self, ptr)

Experimental API . Map Chain pointer to session ID

session_id_to_atom(self, i)

Experimental API . Map sessionID to Atom pointer

session_id_to_bond(self, i)

Experimental API . Map sessionID to Bond pointer

session_id_to_chain(self, i)

Experimental API . Map sessionID to Chain pointer

session_id_to_residue(self, i)

Experimental API . Map sessionID to Residue pointer

session_residue_to_id(self, ptr)

Experimental API . Map Residue pointer to session ID

set_color(self, color)

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

set_geometry(self, vertices, normals, triangles)

Experimental API . Set vertices, normals and triangles defining the shape to be drawn.

set_state_from_snapshot(self, session, data)

Experimental API . Restore from session info

set_transparency(self, alpha)

Experimental API . Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

show_metadata(self, session, *, verbose=False, log=None, **kw)

Experimental API . called by ‘log metadata’ command.

showing_transparent(self)

Experimental API . Are any transparent objects being displayed. Includes all children.

property ss_assigned

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

string(self, style=None)

Experimental API . Return a human-readable string for this structure.

surfaces(self)

Experimental API . List of MolecularSurface objects for this structure.

take_snapshot(self, 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.

property triangles

Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

use_default_atom_radii(self)

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

property vertices

Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

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.

assembly_html_table(mol)

Experimental API . HTML table listing assemblies using info from metadata instead of reparsing mmCIF file.

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.

selected_residues(session)

Experimental API . All selected residues in all structures as an Residues 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(self, 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.

property atoms

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

clear_hide_bits(self, bit_mask)

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

property color

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

property cpp_pointer

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

delete(self)

Supported API . Delete this Bond from it’s Structure

property deleted

Has the C++ side been deleted?

property display

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

property ends_selected

Whether both bond end atoms are selected.

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

property hide

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

property length

Supported API. Bond length. Read only.

other_atom(self, atom)

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

property radius

Displayed cylinder radius for the bond.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

rings(self, 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++].

property selected

Supported API. Whether the bond is selected.

property session

Session that this Bond is in

set_hide_bits(self, bit_mask)

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

property shown

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

side_atoms(self, 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.

property smaller_side

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

string(self, style=None)

Supported API . Get text representation of Bond

property structure

Supported API. AtomicStructure the bond belongs to.

take_snapshot(self, 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.

property visible

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

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

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(self, chars)

Experimental API . Extend the sequence with the given string

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(self, 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(ct_pointer=None)

Bases: object

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

property cpp_pointer

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

property deleted

Has the C++ side been deleted?

class CoordSet(cs_pointer)

Bases: State

The coordinates for one frame of a Structure

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

property cpp_pointer

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

property deleted

Has the C++ side been deleted?

property id

ID number of coordset

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

property session

Session that this CoordSet is in

property structure

AtomicStructure the coordset belongs to

take_snapshot(self, 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.

property xyzs

Numpy array of coordinates

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

Bases: tuple

property back_band

Alias for field number 5

property colors

Alias for field number 3

property front_band

Alias for field number 4

property normals

Alias for field number 1

property triangles

Alias for field number 2

property vertices

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.

property atoms

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

property color

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

property cpp_pointer

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

delete(self)

Supported API . Delete this pseudobond from it’s group

property deleted

Has the C++ side been deleted?

property display

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

property group

Supported API. pbgroup.PseudobondGroup that this pseudobond belongs to

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

property length

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

other_atom(self, atom)

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

property radius

Displayed cylinder radius for the bond.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

property selected

Supported API. Whether the pseudobond is selected.

property session

Session that this Pseudobond is in

property shown

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

property shown_when_atoms_hidden

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(self, style=None)

Supported API . Get text representation of Bond

take_snapshot(self, 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.

property change_tracker

The ChangeTracker currently in use by this pseudobond group. Read only.

clear(self)

Supported API . Delete all pseudobonds in group

property color

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

property cpp_pointer

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

delete_pseudobond(self, pb)

Supported API . Delete a specific pseudobond from a group

property deleted

Has the C++ side been deleted?

get_num_pseudobonds(self, cs_id)

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

get_pseudobonds(self, cs_id)

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

property group_type

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

property halfbond

Sets the halfbond attribute of current pseudobonds and new pseudobonds

new_pseudobond(self, atom1, atom2, cs_id=None)

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

new_pseudobonds(self, atoms1, atoms2)

Experimental API . Create new pseudobonds between the specified Atoms atoms.

property num_pseudobonds

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

property pseudobonds

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

property radius

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

property 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(self, name, create=True)

Supported API . Get an existing PseudobondGroup

property group_map

Returns a dict that maps from PseudobondGroup name to group

reset_state(self, session)

Experimental API . Reset state to data-less state

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(self, 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.

ideal_chirality(self, atom_name)

Experimental API . Return the ideal chirality (N = none; R = right-handed (rectus); S = left-handed (sinister) for the given atom name in this residue. The chirality is only known if the mmCIF chemical component for this residue has been read.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(self, 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(self, scales)

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

blend(self, back_band, front_band)

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

property cpp_pointer

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

property deleted

Has the C++ side been deleted?

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

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

scale(self, scale)

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

class Ring(ring_pointer)

Bases: object

A ring in the structure.

property aromatic

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

property atoms

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

property bonds

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

property cpp_pointer

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

property deleted

Has the C++ side been deleted?

property ordered_atoms

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

property ordered_bonds

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

property size

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

class SeqMatchMap(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(self, 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(self, chars)

Experimental API . Extend the sequence with the given string

property characters

Supported API. A string representing the contents of the sequence

property circular

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.

property cpp_pointer

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

property deleted

Has the C++ side been deleted?

extend(self, chars)

Experimental API . Extend the sequence with the given string

gapped_to_ungapped(self, index)

Supported API . Given an index into the sequence, returns the corresponding index into the sequence as if gaps had been removed.

property name

Supported API. The sequence name

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

search(self, pattern, case_sensitive=False)

Experimental API . Search sequence for an egrep-style pattern. Return a list of (index, length) tuples. The search ignores gap characters but returns values for the full sequence, including gaps.

take_snapshot(self, 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(self)

Supported API . String of sequence without gap characters

ungapped_to_gapped(self, index)

Supported API . Given an index into the sequence with gaps removed, returns the corresponding index into the full sequence.

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.

property active_coordset

Supported API. Currently active CoordSet. Read only.

property active_coordset_change_notify

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

property active_coordset_id

Supported API. Index of the active coordinate set.

add_coordset(self, id, xyz)

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

add_coordsets(self, xyzs, replace=True)

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

property alt_loc_change_notify

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

property atoms

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

property ball_scale

Scales sphere radius in ball-and-stick style.

property bonds

Bonds collection containing all bonds of the structure.

chain_trace_atoms(self)

Experimental API . Find pairs of atoms that should be connected in a chain trace. Returns None or a 2-tuple of two Atoms instances where corresponding atoms should be connected. A chain trace connects two adjacent CA atoms if both atoms are shown but the intervening C and N atoms are not shown, and no ribbon depiction connects the residues. Adjacent means that there is a bond between the two residues. So for instance CA-only structures has no bond between the residues and those do not show a chain trace connection, instead they show a “missing structure” connection. For nucleic acid chains adjacent displayed P atoms with undisplayed intervening O3’ and O5’ atoms are part of a chain trace.

property chains

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

property change_tracker

The ChangeTracker currently in use by this structure. Read only.

combine_sym_atoms(self)

Experimental API . Combine “symmetry” atoms, which for this purpose is atoms with the same element type on the exact same 3D position

connect_structure(self, *, bond_length_tolerance=0.4, metal_coordination_distance=3.6)

Experimental API . Generate bonds and relevant pseudobonds (missing structure; metal coordination) for structure. Typically used for structures where only the atom positions and not the connectivity is known.

‘bond_length_tolerance’ is how much longer the inter-atom distance can exceed the ideal bond length and still have a bond created between the atoms.

‘metal_coordination_distance’ is the maximum distance between a metal and a possibly coordinating atom that will generate a metal-coordination pseudobond.

coordset(self, cs_id)

Supported API . Return the CoordSet for the given coordset ID

property coordset_ids

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

property coordset_size

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

property cpp_pointer

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

delete(self)

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

delete_alt_locs(self)

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

delete_atom(self, atom)

Supported API . Delete the specified Atom.

delete_bond(self, bond)

Supported API . Delete the specified Bond.

property deleted

Has the C++ side been deleted?

property lower_case_chains

Supported API. Structure has lower case chain ids. Boolean

property metadata

Supported API. Dictionary with metadata. Read only.

property molecules

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(self, 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. It is advisible to add the atom to its residue as soon as possible since errors that occur in between can crash ChimeraX. Also, there are functions in chimerax.atomic.struct_edit for adding atoms that are considerably less tedious and error-prone than using new_atom() and related calls.

new_bond(self, atom1, atom2)

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

new_coordset(self, 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(self, residue_name, chain_id, pos, insert=None, *, precedes=None)

Supported API . Create a new Residue. If ‘precedes’ is None, new residue will be appended to residue list, otherwise the new residue will be inserted before the ‘precedes’ resdidue.

property nonstandard_residue_names

“ligand-y” residue names in this structure

property num_atoms

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

property num_atoms_visible

Number of visible atoms in structure. Read only.

property num_bonds

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

property num_bonds_visible

Number of visible bonds in structure. Read only.

property num_chains

Supported API. Number of chains structure. Read only.

property num_coordsets

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

property num_residues

Supported API. Number of residues structure. Read only.

property pbg_map

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

property pdb_version

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

polymers(self, 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(self, name, *, create_type='normal')

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

remove_coordsets(self)

Experimental API . Remove all coordinate sets.

reorder_residues(self, new_order)

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

property residues

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

property ribbon_display_count

Return number of residues with ribbon display set. Integer.

property ribbon_mode_helix

Ribbon mode for helices. Integer value.

property ribbon_mode_strand

Ribbon mode for strands. Integer value.

property ribbon_orientation

Ribbon orientation. Integer value.

ribbon_orients(self, residues=None)

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

property ribbon_show_spine

Display ribbon spine. Boolean.

property ribbon_tether_opacity

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

property ribbon_tether_scale

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

property ribbon_tether_shape

Ribbon tether shape. Integer value.

property ribbon_tether_sides

Number of sides for ribbon tether. Integer value.

property ring_display_count

Return number of residues with ring display set. Integer.

rings(self, 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(self, session, flags)

Experimental API . Gather session info; return version number

session_atom_to_id(self, ptr)

Experimental API . Map Atom pointer to session ID

session_bond_to_id(self, ptr)

Experimental API . Map Bond pointer to session ID

session_chain_to_id(self, ptr)

Experimental API . Map Chain pointer to session ID

session_id_to_atom(self, i)

Experimental API . Map sessionID to Atom pointer

session_id_to_bond(self, i)

Experimental API . Map sessionID to Bond pointer

session_id_to_chain(self, i)

Experimental API . Map sessionID to Chain pointer

session_id_to_residue(self, i)

Experimental API . Map sessionID to Residue pointer

session_residue_to_id(self, ptr)

Experimental API . Map Residue pointer to session ID

set_color(self, rgba)

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

set_state_from_snapshot(self, session, data)

Experimental API . Restore from session info

property ss_assigned

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

use_default_atom_radii(self)

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, polymer_type=0)

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(self, residues, characters)

Experimental API . Set all residues/characters of StructureSeq.

property chain_id

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

property characters

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

property existing_residues

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

property from_seqres

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

property num_existing_residues

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

property num_residues

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

property polymer_type

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

property res_map

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

residue_after(self, r)

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

residue_at(self, index)

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

residue_before(self, r)

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

property residues

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

property session

Supported API. Session that this StructureSeq is in

property structure

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

take_snapshot(self, 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(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.

contextmanager(func)

Experimental API . @contextmanager decorator.

Typical usage:

@contextmanager def some_generator(<arguments>):

<setup> try:

yield <value>

finally:

<cleanup>

This makes this:

with some_generator(<arguments>) as <variable>:

<body>

equivalent to this:

<setup> try:

<variable> = <value> <body>

finally:

<cleanup>

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 connected to this atom directly by one bond.

num_alt_locs

Experimental API . Number of alternate locations for this atom. Read only.

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.

pb_coord

Experimental API . Pseudobond coordinates. If atom is not visible and is part of a residue

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.

suppress_alt_loc_change_notifications(*args, **kwds)

Experimental API . Suppress alt loc change notifications while the code body runs. Restore the original alt loc of this atom when done.

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.

static get_standard_aa_name()

Experimental API . If ‘res_name’ is a standard amino acid or modified amino acid 3-letter name, return the 3-letter name of the corresponding standard amino acid. Otherwise return None. The ability to determine the standard name of a modified amino acid may depend on the presence of MODRES records or their equivalent in the original input.

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.

neighbors

Supported API . Residues directly bonded to this residue. Read only.

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.

omega

Supported API . Get/set omega angle. If not an amino acid (or missing needed backbone atoms), setting is a no-op and getting returns None.

phi

Supported API . Get/set phi angle. If not an amino acid (or missing needed backbone atoms), setting is a no-op and getting returns None.

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.

psi

Supported API . Get/set psi angle. If not an amino acid (or missing needed backbone atoms), setting is a no-op and getting returns None.

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.

ring_color

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

ring_display

Experimental API . Whether to display the residue’s rings as filled. Boolean value.

set_alt_loc()

Experimental API . Set the appropriate 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.

standard_aa_name

Experimental API . If this is a standard amino acid or modified amino acid, return the 3-letter name of the corresponding standard amino acid. Otherwise return None. The ability to determine the standard name of a modified amino acid may depend on the presence of MODRES records or their equivalent in the original input.

string()

Supported API . Get text representation of Residue

structure

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

thin_rings

Experimental API . Whether to display the residue’s rings as filled. Boolean value.

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 except that deleted items are automatically removed.

hash(self)

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 (deletions automatically remove items).

__len__(self)

Experimental API . Number of objects in collection.

__iter__(self)

Experimental API . Iterator over collection objects.

__getitem__(self, i)

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

index(self, object)

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

indices(self, 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__(self, objects)

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

__and__(self, objects)

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

__sub__(self, objects)

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

copy(self)

Experimental API . Shallow copy, since Collections are immutable.

intersect(self, objects)

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

intersects(self, objects)

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

intersects_each(self, 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(self, mask_or_indices)

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

Parameters
mask_or_indicesnumpy 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(self, objects)

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

merge(self, objects)

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

subtract(self, objects)

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

unique(self)

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

instances(self, 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(self, 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
collectionssequence 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.

property alt_loc_change_notifies

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.

property active_coordsets

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

property atoms

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

property bonds

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

property chains

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

property lower_case_chains

A numpy bool array of lower_case_names of each structure.

property num_atoms

Number of atoms in each structure. Read only.

property num_bonds

Number of bonds in each structure. Read only.

property num_chains

Number of chains in each structure. Read only.

property num_residues

Number of residues in each structure. Read only.

property residues

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

property pbg_maps

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

property ribbon_tether_scales

Returns an array of scale factors for ribbon tethers.

property ribbon_tether_sides

Returns an array of numbers of sides for ribbon tethers.

property ribbon_tether_shapes

Returns an array of shapes for ribbon tethers.

property metadata

Return a list of dictionaries with metadata. Read only.

property ribbon_tether_opacities

Returns an array of opacity scale factor for ribbon tethers.

property ribbon_show_spines

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

property ribbon_orientations

Returns an array of ribbon orientations.

property ss_assigneds

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.

property bonds

Bonds object where either endpoint atom is in this collection. If any of the atoms in this collection are bonded to each other, then there will be duplicate bonds in the result, so call .unique() on that if duplicates are problematic.

property by_chain

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

property by_structure

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

property colors

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.

property coords

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

property coord_indices

Coordinate index of atom in coordinate set.

property displays

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.

property draw_modes

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.

property elements

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

property element_names

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

property element_numbers

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

property hides

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(self, bit_mask)

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

clear_hide_bits(self, bit_mask)

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

property idatm_types

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

property in_chains

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

property is_riboses

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

property is_side_chains

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.

property is_side_connectors

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

property is_side_onlys

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.

property names

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.

property neighbors

Atoms object where each atom is bonded to an atom is in this collection. If any of the atoms in this collection are bonded to each other, then there will be duplicate atoms in the result, so call .unique() on that if duplicates are problematic.

property num_alt_locs

Number of alt locs in each atom. Zero for atoms without alt locs. Read only.

property num_bonds

Number of bonds in each atom. Read only.

property intra_bonds

Bonds object where both endpoint atoms are in this collection

property radii

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

property default_radii

Returns a numpy array of default radii.

maximum_bond_radii(self, default_radius=0.2)

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

property residues

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

property scene_bounds

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

property scene_coords

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

property selected

numpy bool array whether each Atom is selected.

property selecteds

numpy bool array whether each Atom is selected.

property num_selected

Number of selected atoms.

property has_selected_bonds

For each atom is any connected bond selected.

property serial_numbers

Serial numbers of atoms

property shown_atoms

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

property structure_categories

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

property structures

Returns an AtomicStructure for each atom. Read only.

property unique_residues

The unique Residues for these atoms.

property unique_chain_ids

The unique chain IDs as a numpy array of strings.

property unique_structures

The unique structures as an AtomicStructures collection

property full_residues

The Residues all of whose atoms are in this Atoms instance

property full_structures

The Structures all of whose atoms are in this Atoms instance

property single_structure

Do all atoms belong to a single Structure

property visibles

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

property alt_locs

Returns current alternate location indicators

delete(self)

Experimental API . Delete the C++ Atom objects

update_ribbon_visibility(self)

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

property has_aniso_u

Boolean array identifying which atoms have anisotropic temperature factors.

property aniso_u

Anisotropic temperature factors, returns Nx3x3 array of numpy float32. If any of the atoms does not have temperature factors it raises a ValueError exception. Read only.

property aniso_u6

Get anisotropic temperature factors as a Nx6 array of numpy float32 containing (u11,u22,u33,u12,u13,u23) for each atom. If any of the atoms does not have temperature factors raise a ValueError exception.

residue_sums(self, 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.

property atoms

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.

property colors

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.

property displays

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.

property visibles

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.

property halfbonds

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.

property radii

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.

property selected

numpy bool array whether each Bond is selected.

property ends_selected

For each bond are both of its endpoint atoms selected.

property showns

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

property structures

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

property unique_structures

The unique structures as an AtomicStructures collection

property by_structure

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

delete(self)

Experimental API . Delete the C++ Bonds objects

property num_shown

Number of bonds shown.

property num_selected

Number of selected bonds.

property half_colors

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

halfbond_cylinder_placements(self, 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.

property names

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

property numbers

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

property masses

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

property is_alkali_metal

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

property is_halogen

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

property is_metal

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

property is_noble_gas

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

property valences

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.

property atoms

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.

property colors

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.

property displays

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.

property groups

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

property halfbonds

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.

property radii

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.

property selected

numpy bool array whether each Pseudobond is selected.

property showns

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

property shown_when_atoms_hiddens

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(self)

Experimental API . Delete the C++ Pseudobond objects

property lengths

Distances between pseudobond end points.

property half_colors

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

between_atoms(self, atoms)

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

property unique_structures

The unique structures as a StructureDatas collection

property by_group

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

property num_selected

Number of selected pseudobonds.

class Residues(residue_pointers=None)

Bases: Collection

Collection of C++ residue objects.

property atoms

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

property centers

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

property chains

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

property chain_ids

Returns a numpy array of chain IDs. Read only.

property mmcif_chain_ids

Returns a numpy array of chain IDs. Read only.

property insertion_codes

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

property is_helix

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

property is_helices

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

property is_strand

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

property is_strands

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

property names

Returns a numpy array of residue names.

property num_atoms

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

property numbers

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.

property polymer_types

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

property principal_atoms

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.

property existing_principal_atoms

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

property ribbon_displays

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

property ribbon_colors

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

property ribbon_adjusts

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.

property ribbon_hide_backbones

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

property ring_displays

A numpy bool array whether to fill rings in each residue.

property ring_colors

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

property thin_rings

A numpy bool array whether to filled rings are thin in each residue.

property secondary_structure_ids

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.

property ss_ids

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.

property ss_types

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

property structures

Returns StructureDatas collection containing structures for each residue.

delete(self)

Experimental API . Delete the C++ Residue objects

property unique_structures

The unique structures as a StructureDatas collection

property unique_names

The unique names as a numpy array of strings.

property unique_chain_ids

The unique chain IDs as a numpy array of strings.

property unique_chains

The unique chains as a Chains collection

property by_chain

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

property by_structure

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

property unique_ids

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.

property unique_sequences

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(self)

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(self)

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

property ribbon_num_selected

Number of selected residue ribbons.

property ribbon_selected

numpy bool array whether each Residue ribbon is selected.

class Rings(ring_pointers=None, rings=None)

Bases: Collection

Collection of C++ ring objects.

property aromatics

A numpy bool array whether corresponding ring is aromatic.

property atoms

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

property bonds

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

property sizes

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

class Chains(chain_pointers)

Bases: Collection

Collection of C++ chain objects.

property chain_ids

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

property structures

A StructureDatas collection containing structures for each chain.

property existing_residues

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

property num_existing_residues

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

property num_residues

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

property polymer_types

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.

property pseudobonds

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

property names

A numpy string array of categories of each group.

property num_pseudobonds

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.

property ids

ID numbers of coordsets

property structures

Returns an AtomicStructure for each coordset. Read only.

property unique_structures

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.

property dashes

How many dashes pseudobonds will be drawn with

delete(self)

Experimental API . Delete this model.

first_intercept(self, 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 highlighting 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.

get_selected(self, include_children=False, fully=False)

Experimental API . Is this model selected? If fully is true then are all parts of this model selected?

property name

Supported API. The name of the group.

planes_pick(self, 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 highlighting objects in a frustum.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(self, 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, update=True)

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
sessionSession

The session the surface model will belong to

enclose_atomsAtoms

Surface bounds these atoms.

show_atomsAtoms

Show only the portion of the surface near these atoms.

probe_radiusfloat

The probe sphere radius for a solvent excluded surface.

grid_spacingfloat

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.

resolutionfloat

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

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

namestring

Surface name.

colornumpy uint8 length 4 array

RGBA color for surface.

visible_patchesint 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_boundariesbool

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.

updatebool

Whether the surface automically updates its shape when atom coordinates change. Default true.

property atom_count

Number of atoms for calculating the surface. Read only.

calculate_surface_geometry(self)

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

first_intercept(self, 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 highlighting 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(self, atoms)

Experimental API . Hide the surface patch near these Atoms.

new_parameters(self, 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.

property selected

Is this model selected? If fully is true then are all parts of this model selected?

show(self, atoms, only=False)

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

take_snapshot(self, 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(self, 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.