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:

• AtomicStructure

• Atom

• Bond

• Residue

• Chain, which is based on StructureSeq which is in turn based on Sequence

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

• Pseudobond

• PseudobondGroup

• PseudobondManager

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.

ALL_EDGES_DISPLAY_MASK = 7

Experimental API . Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Experimental API . Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Experimental API . Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

Experimental API . state flag

LAST_DRAW_PASS = 'last'

Experimental API . Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Experimental API . Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Experimental API . Draw pass to render only opaque drawings.

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.

SCENE = 1

Experimental API . state flag

SESSION = 2

Experimental API . state flag

Solid = 'solid'

Experimental API . Display style showing filled triangles.

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.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Experimental API . Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Experimental API . Draw pass to render only transparent drawings.

accept_multishadow

Experimental API . False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

Experimental API . False means not to show shadow on this Drawing even if global shadow is on.

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

Experimental API . Add child models to this model.

Return type:

None

add_coordset(id, xyz)

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

add_coordsets(xyzs, replace=True)

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

add_drawing(d)

Experimental API . Add a child drawing.

all_drawings(displayed_only=False)

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

all_models()

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

allow_clipping

Experimental API . False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

Experimental API . False means not show depth cue on this Drawing even if global depth cueing is on.

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

ambient_texture

Experimental API . A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Experimental API . Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

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

property ball_scale

Scales sphere radius in ball-and-stick style.

bonded_groups(*, consider_missing_structure=True)

Experimental API . Find bonded groups of atoms. Returns a list of Atoms collections

property bonds

Bonds collection containing all bonds of the structure.

bounds()

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. The bounds are in the scene coordinate system.

bounds_intercept_copies(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.

casts_shadows = True

Experimental API . Whether this drawing creates shadows when shadows are enabled.

chain_trace_atoms()

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.

change_chain_ids(chains, chain_ids, *, non_polymeric=True)

Experimental API . Change the chain IDs of the given chains to the corresponding chain ID. The final ID must not conflict with other unchanged chains of the structure. If ‘non_polymeric’ is True, then non-polymeric residues with the same chain ID as any of the given change will also have their chain ID changed in the same way.

property change_tracker

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

child_drawings()

Experimental API . Return the list of surface pieces.

child_models()

Experimental API . Return child models.

clear_highlight(include_children=True)

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

property color

colormap

Experimental API . Maps 2D and 3D texture values to colors.

colormap_range

Experimental API . Data value range corresponding to ends of colormap.

property colors

combine(s, chain_id_mapping, ref_xform)

Experimental API . Combine structure ‘s’ into this structure. ‘chain_id_mapping’ is a chain ID -> chain ID dictionary describing how to change chain IDs of ‘s’ when in conflict with this structure. ‘ref_xform’ is the scene_position of the reference model.

combine_sym_atoms()

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

connect_structure(*, 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.

contextmanager()

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>

coordset(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 coordsets

Supported API. CoordSets collection containing all coordsets of the structure.

copy(name=None)

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

cpp_del_model()

Experimental API . Called by the C++ layer to request that the model be deleted

property cpp_pointer

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

custom_x3d(stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

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

delete()

Experimental API . Delete this structure.

delete_alt_locs()

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

delete_atom(atom)

Supported API . Delete the specified Atom.

delete_bond(bond)

Supported API . Delete the specified Bond.

delete_residue(residue)

Supported API . Delete the specified Residue. Rarely needed, since deleting atoms will delete empty residues automatically. Can be needed when moving atoms from one residue to another, leaving an empty residue that needs deletion.

property deleted

Return whether this model has already been deleted.

Returns:

Returns boolean value. True if model has been deleted; False otherwise.

property display

Don’t call this directly. Use Model’s ‘display’ attribute instead. Only exposed so that Model’s ‘display’ attribute can call it so that ‘display changed’ shows up in triggers.

property display_positions

property display_style

draw(renderer, draw_pass)

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

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

property edge_mask

empty_drawing()

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

find_residue(chain_id, pos, insert=' ')

Supported API . Find a residue in the structure. Returns None if none match.

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . So that generic models can be properly picked. Most model classes override this.

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

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

geometry_bounds()

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

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

property highlighted

property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions

property highlighted_triangles_mask

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 idatm_failed

Supported API. Whether the IDATM computation failed for this structure. Boolean

property idatm_valid

Supported API. Whether atoms have valid IDATM types set. Boolean

inherit_graphics_exemptions

Experimental API . Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

interpolate_scene(scene1_data, scene2_data, fraction, *, switchover=False)

Experimental API . Restore model to state interpolated as a fraction between the two scene datas. For parts of the model that aren’t interpolable, change to the second state when ‘switchover’ is True. If no parts of the model are interpolable then you needn’t implement this method (restore_scene() is sufficient).

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.

multitexture

Experimental API . List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Experimental API . Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name

new_atom(atom_name, element)

Supported API . Create a new Atom object. It must be added to a Residue object belonging to this structure before being used. ‘element’ can be a string (atomic symbol), an integer (atomic number), or an Element instance. 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(atom1, atom2)

Supported API . Create a new Bond joining two Atom objects. In most cases one should use chimerax.atomic.struct_edit.add_bond() instead, which does a lot of maintenance of data structures that new_bond() alone does not.

new_coordset(index=None, size=None)

Supported API . Create a new empty coordset. In almost all circumstances one would

use the add_coordset(s) method instead (to add fully populated coordsets), but in some cases when building a Structure from scratch this method is needed.

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

new_drawing(name, *, subclass=None)

Experimental API . Create a new empty child drawing.

new_residue(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 in structure. Read only.

property num_coordsets

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

property num_residues

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

property num_ribbon_residues

Supported API. Number of residues in structure shown as ribbon. Read only.

number_of_positions(displayed_only=False)

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

number_of_triangles(displayed_only=False)

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

on_top

Experimental API . Whether to draw on top of everything else. Used for text labels.

opaque_texture

Experimental API . Whether the texture for surface coloring is opaque or transparent.

property overall_color

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.

pickable = True

Experimental API . Whether this drawing can be picked by View.picked_object().

planes_pick(planes, exclude=None)

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

polymers(missing_structure_treatment=0, consider_chains_ids=True)

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

property position

property positions

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

Supported API . Get or create a PseudobondGroup belonging to this structure. The ‘create_type’ parameter controls if and how the pseudobond is created, as per:

0 (also: None)

If no such group exists, none is created and None is returned

1 (also: “normal”)

A “normal” pseudobond group will be created if necessary, one where the pseudobonds apply to all coordinate sets

2 (also: “per coordset”)

A “per coordset” pseudobond group will be created if necessary, one where different coordsets can have different pseudobonds

redraw_needed(**kw)

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

remove_all_drawings(delete=True)

Experimental API . Remove all child drawings.

remove_coordsets()

Experimental API . Remove all coordinate sets.

remove_drawing(d, delete=True)

Experimental API . Remove a specified child drawing.

remove_drawings(drawings, delete=True)

Experimental API . Remove specified child drawings.

renumber_residues(renumbered, start)

Experimental API . Renumber the given residues (‘renumbered’), starting from the integer ‘start’. Residues must be in the same chain and the resulting numbering must not conflict with other residues in the same chain (unless those residues have non-blank insertion codes). The renumbering will set insertion codes to blanks. The renumbering does NOT reorder the residues (which determines sequence order). Use reorder_residues() for that.

reorder_residues(new_order)

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

property res_numbering

Numbering scheme for residues. One of Residue.RN_AUTHOR/RN_CANONICAL/RN_UNIPROT

res_numbering_valid(res_numbering)

Experimental API . Is a particular residue-numbering scheme (author, UniProt) valid for this structure?

property residues

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

restore_geometry(session, data)

Experimental API . Restore model and drawing state saved with save_geometry().

restore_scene(scene_data)

Experimental API . Restore model to state from scene_data (obtained from take_snapshot() with State.SCENE flag)

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(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(cross_residue=False, all_size_threshold=0)

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

If ‘cross_residue’ 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_geometry(session, flags)

Experimental API . Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

save_state(session, flags)

Experimental API . Gather session info; return version number

property scene_position

property selected

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

session_atom_to_id(ptr)

Experimental API . Map Atom pointer to session ID

session_bond_to_id(ptr)

Experimental API . Map Bond pointer to session ID

session_chain_to_id(ptr)

Experimental API . Map Chain pointer to session ID

session_id_to_atom(i)

Experimental API . Map sessionID to Atom pointer

session_id_to_bond(i)

Experimental API . Map sessionID to Bond pointer

session_id_to_chain(i)

Experimental API . Map sessionID to Chain pointer

session_id_to_residue(i)

Experimental API . Map sessionID to Residue pointer

session_residue_to_id(ptr)

Experimental API . Map Residue pointer to session ID

set_color(color)

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

set_geometry(vertices, normals, triangles, edge_mask=None, triangle_mask=None)

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

set_metadata_entry(key, values)

Experimental API . Set metadata dictionary entry

set_res_numbering_valid(res_numbering, valid=True)

Experimental API . Indicate whether a particular residue-numbering scheme (author, UniProt) is valid for this structure

set_state_from_snapshot(session, data)

Experimental API . Restore from session info

set_transparency(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.

property shape_changed

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

Experimental API . called by ‘log metadata’ command.

showing_transparent(include_children=True)

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

skip_bounds = False

Experimental API . Whether this drawing is included in calculation by bounds().

property ss_assigned

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

property ss_change_notify

Whether notifications are issued when secondardy structure is changed. Should only be set to false when temporarily changing secondary structure in a Python script. Boolean

string(style=None)

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

suppress_ss_change_notifications()

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

surfaces()

Experimental API . List of MolecularSurface objects for this structure.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

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

texture

Experimental API . Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Experimental API . Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask

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

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

use_lighting

Experimental API . Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors

property vertices

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

was_deleted

Experimental API . Indicates whether this Drawing has been deleted.

property worm_ribbon

Show ribbon as a ‘worm’. Boolean.

class AtomsDrawing(name)

Bases: Drawing

ALL_EDGES_DISPLAY_MASK = 7

Experimental API . Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Experimental API . Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Experimental API . Draw pass to render only the highlighted parts of drawings.

LAST_DRAW_PASS = 'last'

Experimental API . Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Experimental API . Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Experimental API . Draw pass to render only opaque drawings.

Solid = 'solid'

Experimental API . Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Experimental API . Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Experimental API . Draw pass to render only transparent drawings.

accept_multishadow

Experimental API . False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

Experimental API . False means not to show shadow on this Drawing even if global shadow is on.

add_drawing(d)

Experimental API . Add a child drawing.

all_drawings(displayed_only=False)

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

allow_clipping

Experimental API . False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

Experimental API . False means not show depth cue on this Drawing even if global depth cueing is on.

ambient_texture

Experimental API . A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Experimental API . Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

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

bounds()

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. The bounds are in the scene coordinate system.

bounds_intercept_copies(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.

casts_shadows = True

Experimental API . Whether this drawing creates shadows when shadows are enabled.

child_drawings()

Experimental API . Return the list of surface pieces.

clear_highlight(include_children=True)

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

property color

colormap

Experimental API . Maps 2D and 3D texture values to colors.

colormap_range

Experimental API . Data value range corresponding to ends of colormap.

property colors

custom_x3d(stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

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

delete()

Experimental API . Delete drawing and all child drawings.

property display

property display_positions

property display_style

draw(renderer, draw_pass)

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

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

property edge_mask

empty_drawing()

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

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing should be excluded, ‘all’ if this drawing and its children should be excluded, or false to include this drawing and chidren. Returns 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(child_drawings, mxyz1, mxyz2, exclude=None)

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

geometry_bounds()

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

property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions

property highlighted_triangles_mask

inherit_graphics_exemptions

Experimental API . Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

multitexture

Experimental API . List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Experimental API . Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

name

Experimental API . Name of this drawing.

new_drawing(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(displayed_only=False)

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

number_of_triangles(displayed_only=False)

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

on_top

Experimental API . Whether to draw on top of everything else. Used for text labels.

opaque_texture

Experimental API . Whether the texture for surface coloring is opaque or transparent.

pickable = True

Experimental API . Whether this drawing can be picked by View.picked_object().

planes_pick(planes, exclude=None)

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

property position

property positions

redraw_needed(**kw)

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

remove_all_drawings(delete=True)

Experimental API . Remove all child drawings.

remove_drawing(d, delete=True)

Experimental API . Remove a specified child drawing.

remove_drawings(drawings, delete=True)

Experimental API . Remove specified child drawings.

property scene_position

set_geometry(vertices, normals, triangles, edge_mask=None, triangle_mask=None)

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

set_transparency(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.

property shape_changed

showing_transparent(include_children=True)

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

skip_bounds = False

Experimental API . Whether this drawing is included in calculation by bounds().

texture

Experimental API . Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Experimental API . Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask

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_lighting

Experimental API . Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors

property vertices

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

was_deleted

Experimental API . Indicates whether this Drawing has been deleted.

class BondsDrawing(name, pick_class, picks_class)

Bases: Drawing

ALL_EDGES_DISPLAY_MASK = 7

Experimental API . Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Experimental API . Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Experimental API . Draw pass to render only the highlighted parts of drawings.

LAST_DRAW_PASS = 'last'

Experimental API . Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Experimental API . Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Experimental API . Draw pass to render only opaque drawings.

Solid = 'solid'

Experimental API . Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Experimental API . Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Experimental API . Draw pass to render only transparent drawings.

accept_multishadow

Experimental API . False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

Experimental API . False means not to show shadow on this Drawing even if global shadow is on.

add_drawing(d)

Experimental API . Add a child drawing.

all_drawings(displayed_only=False)

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

allow_clipping

Experimental API . False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

Experimental API . False means not show depth cue on this Drawing even if global depth cueing is on.

ambient_texture

Experimental API . A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Experimental API . Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

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

bounds()

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. The bounds are in the scene coordinate system.

bounds_intercept_copies(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.

casts_shadows = True

Experimental API . Whether this drawing creates shadows when shadows are enabled.

child_drawings()

Experimental API . Return the list of surface pieces.

clear_highlight(include_children=True)

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

property color

colormap

Experimental API . Maps 2D and 3D texture values to colors.

colormap_range

Experimental API . Data value range corresponding to ends of colormap.

property colors

custom_x3d(stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

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

delete()

Experimental API . Delete drawing and all child drawings.

property display

property display_positions

property display_style

draw(renderer, draw_pass)

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

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

property edge_mask

empty_drawing()

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

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing should be excluded, ‘all’ if this drawing and its children should be excluded, or false to include this drawing and chidren. Returns 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(child_drawings, mxyz1, mxyz2, exclude=None)

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

geometry_bounds()

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

property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions

property highlighted_triangles_mask

inherit_graphics_exemptions

Experimental API . Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

multitexture

Experimental API . List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Experimental API . Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

name

Experimental API . Name of this drawing.

new_drawing(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(displayed_only=False)

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

number_of_triangles(displayed_only=False)

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

on_top

Experimental API . Whether to draw on top of everything else. Used for text labels.

opaque_texture

Experimental API . Whether the texture for surface coloring is opaque or transparent.

pickable = True

Experimental API . Whether this drawing can be picked by View.picked_object().

planes_pick(planes, exclude=None)

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

property position

property positions

redraw_needed(**kw)

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

remove_all_drawings(delete=True)

Experimental API . Remove all child drawings.

remove_drawing(d, delete=True)

Experimental API . Remove a specified child drawing.

remove_drawings(drawings, delete=True)

Experimental API . Remove specified child drawings.

property scene_position

set_geometry(vertices, normals, triangles, edge_mask=None, triangle_mask=None)

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

set_transparency(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.

property shape_changed

showing_transparent(include_children=True)

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

skip_bounds = True

Experimental API . Whether this drawing is included in calculation by bounds().

texture

Experimental API . Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Experimental API . Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask

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_lighting

Experimental API . Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors

property vertices

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

was_deleted

Experimental API . Indicates whether this Drawing has been deleted.

class LevelOfDetail(restore_data=None)

Bases: State

INCLUDE_MAPS = 4

Experimental API . state flag

SCENE = 1

Experimental API . state flag

SESSION = 2

Experimental API . state flag

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

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

class PickedAtom(atom, distance)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

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

specifier()

Experimental API . Command specifier for the picked object.

class PickedAtoms(atoms)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

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

specifier()

Experimental API . Command specifier for the picked object.

class PickedBond(bond, distance)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

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

specifier()

Experimental API . Command specifier for the picked object.

class PickedBonds(bonds)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

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

specifier()

Experimental API . Command specifier for the picked object.

class PickedPseudobond(pbond, distance)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

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

specifier()

Experimental API . Command specifier for the picked object.

class PickedPseudobonds(pbonds)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

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

specifier()

Experimental API . Command specifier for the picked object.

class PickedResidue(residue, distance)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

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

specifier()

Experimental API . Command specifier for the picked object.

class PickedResidues(residues)

Bases: Pick

description()

Experimental API . Text description of the picked object.

select(mode='add')

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

specifier()

Experimental API . Command specifier for the picked object.

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.

ALL_EDGES_DISPLAY_MASK = 7

Experimental API . Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Experimental API . Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Experimental API . Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

Experimental API . state flag

LAST_DRAW_PASS = 'last'

Experimental API . Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Experimental API . Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Experimental API . Draw pass to render only opaque drawings.

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.

SCENE = 1

Experimental API . state flag

SESSION = 2

Experimental API . state flag

Solid = 'solid'

Experimental API . Display style showing filled triangles.

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.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Experimental API . Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Experimental API . Draw pass to render only transparent drawings.

accept_multishadow

Experimental API . False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

Experimental API . False means not to show shadow on this Drawing even if global shadow is on.

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

Experimental API . Add child models to this model.

Return type:

None

add_coordset(id, xyz)

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

add_coordsets(xyzs, replace=True)

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

add_drawing(d)

Experimental API . Add a child drawing.

all_drawings(displayed_only=False)

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

all_models()

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

allow_clipping

Experimental API . False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

Experimental API . False means not show depth cue on this Drawing even if global depth cueing is on.

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

ambient_texture

Experimental API . A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Experimental API . Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

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.

bonded_groups(*, consider_missing_structure=True)

Experimental API . Find bonded groups of atoms. Returns a list of Atoms collections

property bonds

Bonds collection containing all bonds of the structure.

bounds()

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. The bounds are in the scene coordinate system.

bounds_intercept_copies(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.

casts_shadows = True

Experimental API . Whether this drawing creates shadows when shadows are enabled.

chain_trace_atoms()

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.

change_chain_ids(chains, chain_ids, *, non_polymeric=True)

Experimental API . Change the chain IDs of the given chains to the corresponding chain ID. The final ID must not conflict with other unchanged chains of the structure. If ‘non_polymeric’ is True, then non-polymeric residues with the same chain ID as any of the given change will also have their chain ID changed in the same way.

property change_tracker

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

child_drawings()

Experimental API . Return the list of surface pieces.

child_models()

Experimental API . Return child models.

clear_highlight(include_children=True)

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

property color

colormap

Experimental API . Maps 2D and 3D texture values to colors.

colormap_range

Experimental API . Data value range corresponding to ends of colormap.

property colors

combine(s, chain_id_mapping, ref_xform)

Experimental API . Combine structure ‘s’ into this structure. ‘chain_id_mapping’ is a chain ID -> chain ID dictionary describing how to change chain IDs of ‘s’ when in conflict with this structure. ‘ref_xform’ is the scene_position of the reference model.

combine_sym_atoms()

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

connect_structure(*, 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.

contextmanager()

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>

coordset(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 coordsets

Supported API. CoordSets collection containing all coordsets of the structure.

copy(name=None)

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

cpp_del_model()

Experimental API . Called by the C++ layer to request that the model be deleted

property cpp_pointer

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

custom_x3d(stream, x3d_scene, indent, place)

Experimental API . Override this function for custom X3D

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

delete()

Experimental API . Delete this structure.

delete_alt_locs()

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

delete_atom(atom)

Supported API . Delete the specified Atom.

delete_bond(bond)

Supported API . Delete the specified Bond.

delete_residue(residue)

Supported API . Delete the specified Residue. Rarely needed, since deleting atoms will delete empty residues automatically. Can be needed when moving atoms from one residue to another, leaving an empty residue that needs deletion.

property deleted

Return whether this model has already been deleted.

Returns:

Returns boolean value. True if model has been deleted; False otherwise.

property display

Don’t call this directly. Use Model’s ‘display’ attribute instead. Only exposed so that Model’s ‘display’ attribute can call it so that ‘display changed’ shows up in triggers.

property display_positions

property display_style

draw(renderer, draw_pass)

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

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

property edge_mask

empty_drawing()

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

find_residue(chain_id, pos, insert=' ')

Supported API . Find a residue in the structure. Returns None if none match.

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . So that generic models can be properly picked. Most model classes override this.

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

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

geometry_bounds()

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

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

property highlighted

property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions

property highlighted_triangles_mask

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 idatm_failed

Supported API. Whether the IDATM computation failed for this structure. Boolean

property idatm_valid

Supported API. Whether atoms have valid IDATM types set. Boolean

inherit_graphics_exemptions

Experimental API . Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

interpolate_scene(scene1_data, scene2_data, fraction, *, switchover=False)

Experimental API . Restore model to state interpolated as a fraction between the two scene datas. For parts of the model that aren’t interpolable, change to the second state when ‘switchover’ is True. If no parts of the model are interpolable then you needn’t implement this method (restore_scene() is sufficient).

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.

multitexture

Experimental API . List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Experimental API . Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name

new_atom(atom_name, element)

Supported API . Create a new Atom object. It must be added to a Residue object belonging to this structure before being used. ‘element’ can be a string (atomic symbol), an integer (atomic number), or an Element instance. 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(atom1, atom2)

Supported API . Create a new Bond joining two Atom objects. In most cases one should use chimerax.atomic.struct_edit.add_bond() instead, which does a lot of maintenance of data structures that new_bond() alone does not.

new_coordset(index=None, size=None)

Supported API . Create a new empty coordset. In almost all circumstances one would

use the add_coordset(s) method instead (to add fully populated coordsets), but in some cases when building a Structure from scratch this method is needed.

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

new_drawing(name, *, subclass=None)

Experimental API . Create a new empty child drawing.

new_residue(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 in structure. Read only.

property num_coordsets

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

property num_residues

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

property num_ribbon_residues

Supported API. Number of residues in structure shown as ribbon. Read only.

number_of_positions(displayed_only=False)

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

number_of_triangles(displayed_only=False)

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

on_top

Experimental API . Whether to draw on top of everything else. Used for text labels.

opaque_texture

Experimental API . Whether the texture for surface coloring is opaque or transparent.

property overall_color

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.

pickable = True

Experimental API . Whether this drawing can be picked by View.picked_object().

planes_pick(planes, exclude=None)

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

polymers(missing_structure_treatment=0, consider_chains_ids=True)

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

property position

property positions

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

Supported API . Get or create a PseudobondGroup belonging to this structure. The ‘create_type’ parameter controls if and how the pseudobond is created, as per:

0 (also: None)

If no such group exists, none is created and None is returned

1 (also: “normal”)

A “normal” pseudobond group will be created if necessary, one where the pseudobonds apply to all coordinate sets

2 (also: “per coordset”)

A “per coordset” pseudobond group will be created if necessary, one where different coordsets can have different pseudobonds

redraw_needed(**kw)

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

remove_all_drawings(delete=True)

Experimental API . Remove all child drawings.

remove_coordsets()

Experimental API . Remove all coordinate sets.

remove_drawing(d, delete=True)

Experimental API . Remove a specified child drawing.

remove_drawings(drawings, delete=True)

Experimental API . Remove specified child drawings.

renumber_residues(renumbered, start)

Experimental API . Renumber the given residues (‘renumbered’), starting from the integer ‘start’. Residues must be in the same chain and the resulting numbering must not conflict with other residues in the same chain (unless those residues have non-blank insertion codes). The renumbering will set insertion codes to blanks. The renumbering does NOT reorder the residues (which determines sequence order). Use reorder_residues() for that.

reorder_residues(new_order)

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

property res_numbering

Numbering scheme for residues. One of Residue.RN_AUTHOR/RN_CANONICAL/RN_UNIPROT

res_numbering_valid(res_numbering)

Experimental API . Is a particular residue-numbering scheme (author, UniProt) valid for this structure?

property residues

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

restore_geometry(session, data)

Experimental API . Restore model and drawing state saved with save_geometry().

restore_scene(scene_data)

Experimental API . Restore model to state from scene_data (obtained from take_snapshot() with State.SCENE flag)

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(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(cross_residue=False, all_size_threshold=0)

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

If ‘cross_residue’ 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_geometry(session, flags)

Experimental API . Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

save_state(session, flags)

Experimental API . Gather session info; return version number

property scene_position

property selected

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

session_atom_to_id(ptr)

Experimental API . Map Atom pointer to session ID

session_bond_to_id(ptr)

Experimental API . Map Bond pointer to session ID

session_chain_to_id(ptr)

Experimental API . Map Chain pointer to session ID

session_id_to_atom(i)

Experimental API . Map sessionID to Atom pointer

session_id_to_bond(i)

Experimental API . Map sessionID to Bond pointer

session_id_to_chain(i)

Experimental API . Map sessionID to Chain pointer

session_id_to_residue(i)

Experimental API . Map sessionID to Residue pointer

session_residue_to_id(ptr)

Experimental API . Map Residue pointer to session ID

set_color(color)

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

set_geometry(vertices, normals, triangles, edge_mask=None, triangle_mask=None)

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

set_metadata_entry(key, values)

Experimental API . Set metadata dictionary entry

set_res_numbering_valid(res_numbering, valid=True)

Experimental API . Indicate whether a particular residue-numbering scheme (author, UniProt) is valid for this structure

set_state_from_snapshot(session, data)

Experimental API . Restore from session info

set_transparency(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.

property shape_changed

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

Experimental API . called by ‘log metadata’ command.

showing_transparent(include_children=True)

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

skip_bounds = False

Experimental API . Whether this drawing is included in calculation by bounds().

property ss_assigned

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

property ss_change_notify

Whether notifications are issued when secondardy structure is changed. Should only be set to false when temporarily changing secondary structure in a Python script. Boolean

string(style=None)

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

suppress_ss_change_notifications()

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

surfaces()

Experimental API . List of MolecularSurface objects for this structure.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

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

texture

Experimental API . Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Experimental API . Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask

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

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

use_lighting

Experimental API . Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors

property vertices

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

was_deleted

Experimental API . Indicates whether this Drawing has been deleted.

property worm_ribbon

Show ribbon as a ‘worm’. Boolean.

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_bonds(session, atomic_only=False)

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

all_residues(session, atomic_only=False)

Experimental API . All residues in all structures as a Residues collection.

all_structures(session, atomic_only=False)

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.

is_informative_name(name)

Experimental API . Does the string ‘name’ seem like it would actually be an informative name for the structure

selected_atoms(session)

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

selected_bonds(session, *, intra_residue=True, inter_residue=True)

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

selected_chains(session)

Experimental API . All selected chains in all structures as an Chains 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 Residues collection.

class Atom

Bases: CyAtom, State

An atom in a (chemical) structure

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

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

class Bond(bond_pointer)

Bases: State

Bond connecting two atoms.

To create a Bond use chimerax.atomic.struct_edit.add_bond()

property atoms

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

clear_hide_bits(bit_mask)

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

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

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 in_cycle

Supported API. Is the bond in a cycles of bonds? Boolean value.

property length

Supported API. Bond length. Read only.

other_atom(atom)

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

property radius

Displayed cylinder radius for the bond.

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

rings(cross_residue=False, all_size_threshold=0)

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

If ‘cross_residue’ 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(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(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(*, style=None, minimal=False, reversed=False)

Supported API . Get text representation of Bond (also used by __str__ for printing)

property structure

Supported API. AtomicStructure the bond belongs to.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

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

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

Experimental API . Extend the sequence with the given string

property identity

‘Fake’ attribute to allow for //identity=”/A” tests

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

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

class ChangeTracker(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(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 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()

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(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(*, style=None, minimal=False, reversed=False)

Supported API . Get text representation of Bond (also used by __str__ for printing)

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

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

class PseudobondGroupData(pbg_pointer)

Bases: object

A group of pseudobonds typically used for one purpose such as display of distances or missing segments.

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

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

property change_tracker

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

clear()

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

Supported API . Delete a specific pseudobond from a group

property deleted

Has the C++ side been deleted?

get_num_pseudobonds(cs_id)

Supported API . Get the number of pseudobonds for a particular coordinate set. Use the ‘num_pseudobonds’ property to get the number of pseudobonds for the current coordinate set.

get_pseudobonds(cs_id)

Supported API . Get the pseudobonds for a particular coordinate set. Use the ‘pseudobonds’ property to get the pseudobonds for the current coordinate set.

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(atom1, atom2, cs_id=None)

Supported API . Create a new pseudobond between the specified Atom objects. If the pseudobond group supports per-coordset pseudobonds, you may specify a coordinate set ID (defaults to the current coordinate set).

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

Supported API . Get an existing PseudobondGroup or create a new one with the given name.

property group_map

Returns a dict that maps from PseudobondGroup name to group

include_state()

Experimental API . Return if state manager’s state should be included in session

reset_state(session)

Experimental API . Reset state to data-less state

static restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

take_snapshot(session, flags)

Experimental API . Gather session info; return version number

class Residue

Bases: CyResidue, State

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

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

clear_hide_bits(bit_mask, atoms_only=False)

Experimental API . Clear Residue’s atoms’ and bonds’ hide bits in bit mask

ideal_chirality(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(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 Ring(ring_pointer)

Bases: object

A ring in the structure.

property aromatic

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

property atoms

Supported API. Atoms collection containing the atoms of the ring, in no particular order

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

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

Experimental API . Gather session info; return version number

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

Bases: State

A polymeric sequence. Offers string-like interface.

append(chars)

Experimental API . Extend the sequence with the given string

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

Experimental API . Extend the sequence with the given string

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

Supported API . String of sequence without gap characters

ungapped_to_gapped(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(id, xyz)

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

add_coordsets(xyzs, replace=True)

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

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.

bonded_groups(*, consider_missing_structure=True)

Experimental API . Find bonded groups of atoms. Returns a list of Atoms collections

property bonds

Bonds collection containing all bonds of the structure.

chain_trace_atoms()

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.

change_chain_ids(chains, chain_ids, *, non_polymeric=True)

Experimental API . Change the chain IDs of the given chains to the corresponding chain ID. The final ID must not conflict with other unchanged chains of the structure. If ‘non_polymeric’ is True, then non-polymeric residues with the same chain ID as any of the given change will also have their chain ID changed in the same way.

property change_tracker

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

combine_sym_atoms()

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

connect_structure(*, 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.

contextmanager()

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>

coordset(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 coordsets

Supported API. CoordSets collection containing all coordsets of the structure.

property cpp_pointer

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

delete()

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

delete_alt_locs()

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

delete_atom(atom)

Supported API . Delete the specified Atom.

delete_bond(bond)

Supported API . Delete the specified Bond.

delete_residue(residue)

Supported API . Delete the specified Residue. Rarely needed, since deleting atoms will delete empty residues automatically. Can be needed when moving atoms from one residue to another, leaving an empty residue that needs deletion.

property deleted

Has the C++ side been deleted?

property display

Don’t call this directly. Use Model’s ‘display’ attribute instead. Only exposed so that Model’s ‘display’ attribute can call it so that ‘display changed’ shows up in triggers.

find_residue(chain_id, pos, insert=' ')

Supported API . Find a residue in the structure. Returns None if none match.

property idatm_failed

Supported API. Whether the IDATM computation failed for this structure. Boolean

property idatm_valid

Supported API. Whether atoms have valid IDATM types set. Boolean

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(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(atom1, atom2)

Supported API . Create a new Bond joining two Atom objects. In most cases one should use chimerax.atomic.struct_edit.add_bond() instead, which does a lot of maintenance of data structures that new_bond() alone does not.

new_coordset(index=None, size=None)

Supported API . Create a new empty coordset. In almost all circumstances one would

use the add_coordset(s) method instead (to add fully populated coordsets), but in some cases when building a Structure from scratch this method is needed.

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

new_residue(residue_name, chain_id, pos, insert=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 in structure. Read only.

property num_coordsets

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

property num_residues

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

property num_ribbon_residues

Supported API. Number of residues in structure shown as ribbon. 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(missing_structure_treatment=0, consider_chains_ids=True)

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

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

Supported API . Get or create a PseudobondGroup belonging to this structure. The ‘create_type’ parameter controls if and how the pseudobond is created, as per:

0 (also: None)

If no such group exists, none is created and None is returned

1 (also: “normal”)

A “normal” pseudobond group will be created if necessary, one where the pseudobonds apply to all coordinate sets

2 (also: “per coordset”)

A “per coordset” pseudobond group will be created if necessary, one where different coordsets can have different pseudobonds

remove_coordsets()

Experimental API . Remove all coordinate sets.

renumber_residues(renumbered, start)

Experimental API . Renumber the given residues (‘renumbered’), starting from the integer ‘start’. Residues must be in the same chain and the resulting numbering must not conflict with other residues in the same chain (unless those residues have non-blank insertion codes). The renumbering will set insertion codes to blanks. The renumbering does NOT reorder the residues (which determines sequence order). Use reorder_residues() for that.

reorder_residues(new_order)

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

property res_numbering

Numbering scheme for residues. One of Residue.RN_AUTHOR/RN_CANONICAL/RN_UNIPROT

res_numbering_valid(res_numbering)

Experimental API . Is a particular residue-numbering scheme (author, UniProt) valid for this structure?

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(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(cross_residue=False, all_size_threshold=0)

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

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

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

save_state(session, flags)

Experimental API . Gather session info; return version number

session_atom_to_id(ptr)

Experimental API . Map Atom pointer to session ID

session_bond_to_id(ptr)

Experimental API . Map Bond pointer to session ID

session_chain_to_id(ptr)

Experimental API . Map Chain pointer to session ID

session_id_to_atom(i)

Experimental API . Map sessionID to Atom pointer

session_id_to_bond(i)

Experimental API . Map sessionID to Bond pointer

session_id_to_chain(i)

Experimental API . Map sessionID to Chain pointer

session_id_to_residue(i)

Experimental API . Map sessionID to Residue pointer

session_residue_to_id(ptr)

Experimental API . Map Residue pointer to session ID

set_color(rgba)

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

set_metadata_entry(key, values)

Experimental API . Set metadata dictionary entry

set_res_numbering_valid(res_numbering, valid=True)

Experimental API . Indicate whether a particular residue-numbering scheme (author, UniProt) is valid for this structure

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

property ss_change_notify

Whether notifications are issued when secondardy structure is changed. Should only be set to false when temporarily changing secondary structure in a Python script. Boolean

suppress_ss_change_notifications()

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

use_default_atom_radii()

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

property worm_ribbon

Show ribbon as a ‘worm’. Boolean.

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(residues, characters, *, fire_triggers=True)

Experimental API . Set all residues/characters of StructureSeq. “characters” is a string or a list of characters.

property chain_id

Chain identifier. Read only string.

property characters

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

property description

description derived from PDB/mmCIF info and set by AtomicStructure constructor

property existing_residues

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

property from_seqres

“from_seqres” deprecated; use “full_sequence_known” instead.

property full_sequence_known

Is the full polymer sequence known (even if the structure is incomplete).

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

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

residue_at(index)

Supported API . Return the Residue/None at the (ungapped) position ‘index’. More efficient than self.residues[index] since the entire residues list isn’t built/destroyed.

residue_before(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(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 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, returns 3x3 array of float or None. Read only.

aniso_u6

Experimental API . Get anisotropic temperature factors as a 6 element float array containing (u11, u22, u33, u12, u13, u23) [i.e. PDB/mmCIF order] or None.

bfactor

Supported API . B-factor, floating point value.

bonds

Supported API . Bonds connected to this atom as a list of Bond objects. Read only.

clear_hide_bits(bit_mask)

Experimental API . Set the hide bits ‘off’ that are ‘on’ in “bitmask” and leave others unchanged. Opposite of set_hide_bits()

color

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

connects_to(atom)

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

coord

Supported API . Coordinates from the current coordinate set (or alt loc) as a length 3 sequence/array, float values. See get_coord method for other coordsets / alt locs. See scene_coord for coordinates after rotations and translations.

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

delete_alt_loc(loc)

Experimental API . ‘Raw’ editing routine with very little consistency checking. Using Residue.delete_alt_loc() is recommended in most cases.

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:

SPHERE_STYLE

Use full atom radius

BALL_STYLE

Use reduced atom radius, but larger than bond radius

STICK_STYLE

Match bond radius

effective_coord

Experimental API . Return the atom’s ribbon_coord if the residue is displayed as a ribbon and it has a ribbon coordinate, otherwise return the current coordinate.

element

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

get_alt_loc_coord(loc)

Supported API . Like the ‘coord’ property, but uses the given alt loc (character) rather than the current alt loc. Space character gets the non-alt-loc coord.”

get_alt_loc_scene_coord(loc)

Supported API . Like the ‘scene_coord’ property, but uses the given alt loc (character) rather than the current alt loc. Space character gets the non-alt-loc scene coord.

get_coordset_coord(cs_id)

Supported API . Like the ‘coord’ property, but uses the given coordset ID (integer) rather than the current coordset.

get_coordset_scene_coord(cs_id)

Supported API . Like the ‘scene_coord’ property, but uses the given coordset ID (integer) rather than the current coordset.

has_alt_loc(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.

Possible values:

HIDE_RIBBON

Hide mask for backbone atoms in ribbon.

HIDE_ISOLDE

Hide mask for backbone atoms for ISOLDE.

HIDE_NUCLEOTIDE

Hide mask for sidechain atoms in nucleotides.

idatm_type

user/atomtypes.html”>IDATM type</a>

Type:

Supported API . Atom’s <a href=”help

is_backbone(bb_extent=2)

Supported API . Whether this Atom is considered backbone, given the ‘extent’ criteria.n

Possible ‘extent’ values are:

BBE_MIN

Only the atoms needed to connect the residue chain (and their hydrogens)

BBE_MAX

All non-sidechain atoms

BBE_RIBBON

The backbone atoms that a ribbon depiction hides

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. Includes atoms needed to connect to backbone (CA/ribose). is_side_only property excludes those. Read only.

is_side_connector

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

is_side_only

Experimental API . Whether this atom is part of an amino/nucleic acid sidechain. Does not include atoms needed to connect to backbone (CA/ribose). is_side_chain property includes those. Read only.

name

Supported API . Atom name. Maximum length 4 characters.

neighbors

Supported API . Atoms connected to this atom directly by one bond. Read only.

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 connected to this atom. Read only.

occupancy

Supported API . Occupancy, floating point value.

pb_coord

Experimental API . Pseudobond coordinates. If atom is not visible and is part of a residue displayed as a cartoon, return coordinates on the cartoon. Otherwise, return the actual atomic coordinates.

radius

Supported API . Radius of atom.

residue

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

ribbon_coord

Experimental API . Atom ribbon coordinate in the structure coordinate system for displaying pseudobonds or tethers to the ribbon when the atom is hidden. Value is None for non-backbone atoms.

rings(cross_residues=False, all_size_threshold=0)

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. This accounts for the Drawing positions for the hierarchy of models this atom belongs to.

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(loc, create)

Experimental API . Normally used to create alt locs. The ‘alt_loc’ property is used to switch between existing alt locs.

set_hide_bits(bit_mask)

Experimental API . Set the hide bits ‘on’ that are ‘on’ in “bitmask” and leave others unchanged. Opposite of clear_hide_bits()

side_atoms(skip_atom=None, cycle_atom=None)

Experimental API . All the atoms connected to this atom on this side of ‘skip_atom’ (if given). Missing-structure pseudobonds are treated as connecting their atoms for the purpose of computing the connected atoms. Connectivity will never trace through skip_atom, but if ‘cycle_atom’ (which can be the same as skip_atom) is reached then a cycle/ring is assumed to exist and ValueError is thrown.

string(*, atom_only=False, style=None, relative_to=None, omit_structure=None, minimal=False)

Supported API . Get text representation of Atom (also used by __str__ for printing); if omit_structure is None, the the structure will be omitted if only one structure is open

structure

Supported API . AtomicStructure the atom belongs to

structure_category

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

use_default_radius()

Supported API . If an atom’s radius has previously been explicitly set, this call will revert it to using the default radius

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

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.

clean_alt_locs()

Experimental API . Change the current alt locs in this residue to ‘regular’ locations and delete all alt locs

connects_to(other_res)

Supported API . Return True if this residue is connected by at least one bond (not pseudobond) to other_res

delete()

Supported API . Delete this Residue from it’s Structure

delete_alt_loc(loc)

Experimental API . Deletes the specified alt loc in this residue and possibly other residues if their alt locs are ‘connected’. If deleting this residue’s current alt loc, the best remaining one will become current. For simply deleting all alt locs in the structure except the current ones (and changing those to non-alt locs) use Structure.delete_alt_locs().

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

Supported API . Return the atom with the given name, or None if not found. If multiple atoms in the residue have that name, an arbitrary one that matches will be returned.

get_one_letter_code(*, non_polymeric_returns=None)

Experimental API . In this context, ‘non_polymeric’ means residues that are incapable of being in a polymer and therefore a singleton amino or nucleic acid is not ‘non_polymeric’ despite not being in an actual polymer.

static get_standard_aa_name(res_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.

label_one_letter_code

Experimental API . The code that Actions->Label->Residues uses, which can actually be just the residue name (i.e. more that one letter) for non-polymers

label_specifier

Experimental API . The specifier that Actions->Label->Residues uses, which never includes the model ID

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.

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.

remove_atom(atom)

Supported API . Remove the atom from this residue.

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.

selected

Supported API . Whether any atom in the residue is selected.

set_alt_loc(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. One of Residue.SS_COIL, Residue.SS_HELIX, Residue.SS_SHEET (a.k.a. SS_STRAND)

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(*, residue_only=False, omit_structure=None, style=None, minimal=False, omit_chain=None)

Supported API . Get text representation of Residue If ‘omit_structure’ is None, the structure will be omitted only if exactly one structure is open

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.

worm_radius

Experimental API . Radius of ‘worm’ ribbon depiction.

class Element

Bases: object

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

static bond_length(e1, e2)

Supported API . Standard single-bond length between two elements. Arguments can be element instances, atomic numbers, or element names

static bond_radius(e)

Supported API . Standard single-bond ‘radius’ (the amount this element would contribute to bond length). Argument can be an element instance, atomic number, or element name

static get_element(ident)

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

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 https://en.wikipedia.org/wiki/List_of_elements_by_atomic_weight. Read only.

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)

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

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

Experimental API . Number of objects in collection.

__iter__()

Experimental API . Iterator over collection objects.

__getitem__(i)

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

index(object)

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

indices(objects)

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

__or__(objects)

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

__and__(objects)

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

__sub__(objects)

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

copy()

Experimental API . Shallow copy, since Collections are immutable.

intersect(objects)

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

intersects(objects)

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

intersects_each(objects_list)

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

filter(mask_or_indices)

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

Parameters:

mask_or_indices (numpy bool array (mask) or int array (indices)) – Bool length must match the length of the collection and filters out items where the bool array is False.

mask(objects)

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

merge(objects)

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

subtract(objects)

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

unique()

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

instances(instantiate=True)

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

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

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

classmethod restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

class LookupTable(collection)

Bases: object

C++ set of pointers for fast lookup.

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

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

Parameters:

collections (sequence of Collection objects)

unique_ordered(a)

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

class StructureDatas(mol_pointers)

Bases: Collection

Collection of C++ atomic structure objects.

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 ss_change_notifies

Whether notifications are issued when secondary structure is changed. Should only be set to true when temporarily changing secondary structure 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.

set_metadata_entry(key, values)

Experimental API . Set metadata dictionary entry

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)

property worm_ribbons

Whether cartoons will be depicted as worms

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 average_ribbon_color

Average ribbon color as length 4 unit8 RGBA values.

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

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

clear_hide_bits(bit_mask)

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

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 num_residues

Total number of residues for atoms.

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

Returns a numpy Nx3 array of XYZ values. Raises error if any atom does nt have a ribbon coordinate. Can be set.

property effective_coords

Returns a numpy Nx3 array of XYZ values. Return the atom’s ribbon_coord if the residue is displayed as a ribbon and has a ribbon coordinate, otherwise return the current coordinate.

property pb_coords

Returns a numpy Nx3 array of XYZ values. Return the atom’s ribbon_coord if the residue is displayed as a ribbon and has a ribbon coordinate, otherwise return the current coordinate.

property effective_scene_coords

Returns a numpy Nx3 array of XYZ values. Return the atom’s ribbon_coord if the residue is displayed as a ribbon and has a ribbon coordinate, otherwise return the current coordinate in scene coordinate system.

property pb_scene_coords

Returns a numpy Nx3 array of XYZ values. Return the atom’s ribbon_coord if the residue is displayed as a ribbon and has a ribbon coordinate, otherwise return the current coordinate in scene coordinate system.

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 and those that are hidden because the ribbon is 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()

Experimental API . Delete the C++ Atom objects

update_ribbon_backbone_atom_visibility()

Experimental API . Update the ‘hide’ status for ribbon backbone 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(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 lengths

Returns a numpy array of bond lengths. Read only.

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

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(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 https://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()

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

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_missing_heavy_template_atoms

Returns a numpy bool array whether each residue is missing heavy atoms relative to its template. If no template, returns False.

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

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 selected

numpy bool array whether any Atom in each Residue is selected. 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

Residue.SS_COIL, Residue.SS_HELIX, Residue.SS_STRAND [or SS_SHEET])

Type:

Returns a numpy integer array of secondary structure types (one of

property structures

Returns StructureDatas collection containing structures for each residue.

delete()

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

clear_hide_bits(mask, atoms_only=False)

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

find_atoms(atom_name)

Experimental API . Return a list containing an Atom or None for each residue.

find_existing_atoms(atom_name)

Experimental API . Return Atoms collection that includes at most one atom per residue with the given name.

class Rings(ring_pointers=None, rings=None)

Bases: Collection

Collection of C++ ring objects.

class Chains(chain_pointers)

Bases: Collection

Collection of C++ chain objects.

property chain_ids

A numpy array of string chain ids for each chain.

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

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.

class PseudobondGroups(pbg_pointers)

Bases: PseudobondGroupDatas

Collection of Python pseudobond group objects.

property names

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 Structures(mol_pointers)

Bases: StructureDatas

Collection of Python structure objects.

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

Supported API . Delete this model.

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . So that generic models can be properly picked. Most model classes override this.

get_selected(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.

property overall_color

planes_pick(planes, exclude=None)

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

property position

property positions

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?

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

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

all_pseudobonds(session)

Experimental API . All pseudobonds in a Pseudobonds collection.

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:

• session (Session) – The session the surface model will belong to

• enclose_atoms (Atoms) – Surface bounds these atoms.

• show_atoms (Atoms) – Show only the portion of the surface near these atoms.

• probe_radius (float) – The probe sphere radius for a solvent excluded surface.

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

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

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

• name (string) – Surface name.

• color (numpy uint8 length 4 array) – RGBA color for surface.

• visible_patches (int or None) – Number of connected surface components to show. Only the largest area N components will be shown. For value None all components are shown.

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

• update (bool) – 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()

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

color_atom_patches(atoms=None, color=None, per_atom_colors=None, vertex_colors=None, opacity=None)

Experimental API . Set surface patch colors for specified atoms. The atoms collection may include atoms that are not included in the surface. If atoms is None then all atom patches are colored. Colors can be specified in one of four ways. A single color can be specified. Or an array of colors for the specified atoms per_atom_colors can be given. Or an array of whole surface vertex colors can be given. If none of those color arguments are given, then the colors of the atoms are used. Transparency is set if opacity is given, otherwise transparency remains the same as the current surface transparency. Return value is True if atom patches were colored but can be False if no coloring was done because this surface has no atom to vertex mapping and coloring was requested for only a subset of atoms.

delete()

Supported API . Delete this model.

first_intercept(mxyz1, mxyz2, exclude=None)

Experimental API . So that generic models can be properly picked. Most model classes override this.

hide(atoms)

Experimental API . Hide the surface patch near these Atoms.

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

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

property overall_color

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(atoms, only=False)

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

take_snapshot(session, flags)

Experimental API . Return snapshot of current state of instance.

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

vertex_to_atom_map(vertices=None)

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

remove_solvent_ligands_ions(atoms, keep=None)

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

class AtomArg(name=None, url=None, html_name=None)

Bases: AtomsArg

Parse command specifier for an atom

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class AtomicStructureArg(name=None, url=None, html_name=None)

Bases: AtomSpecArg

Parse command atomic structure specifier

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class AtomicStructuresArg(name=None, url=None, html_name=None)

Bases: AtomSpecArg

Parse command atomic structures specifier

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class AtomsArg(name=None, url=None, html_name=None)

Bases: AtomSpecArg

Parse command atoms specifier

classmethod parse(text, session, ordered=False)

Experimental API . Parse text and return an atomspec parse tree

class BondArg(name=None, url=None, html_name=None)

Bases: BondsArg

Parse command specifier for a bond

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class BondsArg(name=None, url=None, html_name=None)

Bases: ObjectsArg

Parse command specifier for bonds

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class ChainArg(name=None, url=None, html_name=None)

Bases: UniqueChainsArg

Parse command chains specifier

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class ElementArg(name=None, url=None, html_name=None)

Bases: StringArg

Parse command specifier for an atomic symbol

classmethod parse(text, session)

Supported API . Convert text to appropriate type.

Parameters:

• text – command line text to parse

• session – for session-dependent data types

Returns:

3-tuple with the converted value, consumed text (possibly altered with expanded abbreviations), and the remaining unconsumed text

Raises:

AnnotationError – if unable to convert text

The leading space in text must already be removed. It is up to the particular annotation to support abbreviations.

Empty text should raise a ValueError or AnnotationError exception (the exceptions being NoArg and EmptyArg).

class OrderedAtomsArg(name=None, url=None, html_name=None)

Bases: AtomsArg

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class PseudobondGroupsArg(name=None, url=None, html_name=None)

Bases: AtomSpecArg

Parse command atom specifier for pseudobond groups

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class PseudobondsArg(name=None, url=None, html_name=None)

Bases: ObjectsArg

Parse command specifier for pseudobonds

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class RawSequenceArg(name=None, url=None, html_name=None)

Bases: Annotation

classmethod parse(text, session)

Supported API . Convert text to appropriate type.

Parameters:

• text – command line text to parse

• session – for session-dependent data types

Returns:

3-tuple with the converted value, consumed text (possibly altered with expanded abbreviations), and the remaining unconsumed text

Raises:

AnnotationError – if unable to convert text

The leading space in text must already be removed. It is up to the particular annotation to support abbreviations.

Empty text should raise a ValueError or AnnotationError exception (the exceptions being NoArg and EmptyArg).

class ResiduesArg(name=None, url=None, html_name=None)

Bases: AtomSpecArg

Parse command residues specifier

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class SequenceArg(name=None, url=None, html_name=None)

Bases: Annotation

classmethod parse(text, session)

Supported API . Convert text to appropriate type.

Parameters:

• text – command line text to parse

• session – for session-dependent data types

Returns:

3-tuple with the converted value, consumed text (possibly altered with expanded abbreviations), and the remaining unconsumed text

Raises:

AnnotationError – if unable to convert text

The leading space in text must already be removed. It is up to the particular annotation to support abbreviations.

Empty text should raise a ValueError or AnnotationError exception (the exceptions being NoArg and EmptyArg).

class SequencesArg(name=None, url=None, html_name=None)

Bases: Annotation

Accept a chain atom spec (#1/A), a sequence viewer alignment id (myseqs.aln:2), a UniProt accession id (K9Z9J3, 6 or 10 characters, always has numbers), a UniProt name (MYOM1_HUMAN, always has underscore, X_Y where X and Y are at most 5 alphanumeric characters), or a sequence (MVLSPADKTN….). Returns a list of Sequence objects or or objects derived from Sequence such as Chain.

classmethod parse(text, session)

Supported API . Convert text to appropriate type.

Parameters:

• text – command line text to parse

• session – for session-dependent data types

Returns:

3-tuple with the converted value, consumed text (possibly altered with expanded abbreviations), and the remaining unconsumed text

Raises:

AnnotationError – if unable to convert text

The leading space in text must already be removed. It is up to the particular annotation to support abbreviations.

Empty text should raise a ValueError or AnnotationError exception (the exceptions being NoArg and EmptyArg).

class StructureArg(name=None, url=None, html_name=None)

Bases: ModelArg

Parse command structure specifier

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class StructuresArg(name=None, url=None, html_name=None)

Bases: AtomSpecArg

Parse command structures specifier

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

class SymmetryArg(name=None, url=None, html_name=None)

Bases: Annotation

Symmetry specification, e.g. C3 or D7

static parse(text, session)

Supported API . Convert text to appropriate type.

Parameters:

• text – command line text to parse

• session – for session-dependent data types

Returns:

3-tuple with the converted value, consumed text (possibly altered with expanded abbreviations), and the remaining unconsumed text

Raises:

AnnotationError – if unable to convert text

The leading space in text must already be removed. It is up to the particular annotation to support abbreviations.

Empty text should raise a ValueError or AnnotationError exception (the exceptions being NoArg and EmptyArg).

class UniProtIdArg(name=None, url=None, html_name=None)

Bases: Annotation

classmethod parse(text, session)

Supported API . Convert text to appropriate type.

Parameters:

• text – command line text to parse

• session – for session-dependent data types

Returns:

3-tuple with the converted value, consumed text (possibly altered with expanded abbreviations), and the remaining unconsumed text

Raises:

AnnotationError – if unable to convert text

The leading space in text must already be removed. It is up to the particular annotation to support abbreviations.

Empty text should raise a ValueError or AnnotationError exception (the exceptions being NoArg and EmptyArg).

class UniProtSequenceArg(name=None, url=None, html_name=None)

Bases: Annotation

classmethod parse(text, session)

Supported API . Convert text to appropriate type.

Parameters:

• text – command line text to parse

• session – for session-dependent data types

Returns:

3-tuple with the converted value, consumed text (possibly altered with expanded abbreviations), and the remaining unconsumed text

Raises:

AnnotationError – if unable to convert text

The leading space in text must already be removed. It is up to the particular annotation to support abbreviations.

Empty text should raise a ValueError or AnnotationError exception (the exceptions being NoArg and EmptyArg).

class UniqueChainsArg(name=None, url=None, html_name=None)

Bases: AtomSpecArg

Parse command chains specifier

classmethod parse(text, session)

Experimental API . Parse text and return an atomspec parse tree

struct_edit: molecular editing utilities

Utilities routines and constants useful for editing structures. Higher level than the basic methods offered by Structure, etc. and therefore less likely to result in catastrophic error. :-)

add_atom(name, element, residue, loc, serial_number=None, bonded_to=None, occupancy=None, info_from=None, alt_loc=None, bfactor=None)

Experimental API . Add an atom at the Point ‘loc’

‘element’ can be a string (atomic symbol), integer (atomic number), or an Element instance.

The atom is added to the given residue (and its molecule). ‘loc’ can be an array of xyzs if there are multiple coordinate sets.

If no ‘serial_number’ is given, then the atom will be given a serial number one greater than the largest serial number of the other atoms in the structure.

‘bonded_to’ is None or an Atom. If an Atom, then the new atom inherits various attributes [display, altloc, style, occupancy] from that atom and a bond to that Atom is created.

If ‘info_from’ is supplied then the information normally garnered from the ‘bonded_to’ atom will be obtained from the ‘info_from’ atom instead. Typically used when there is no ‘bonded_to’ atom.

If ‘occupancy’ is not None or the ‘bonded_to’ atom is not None, the new atom will be given the corresponding occupancy.

If ‘bfactor’ is not None or the ‘bonded_to’ atom is not None, the new atom will be given the corresponding bfactor.

If ‘alt_loc’ is specified (must be a single-character string), then the new atom will be given that alt loc, otherwise the alt loc will be ‘ ‘.

Returns the new atom.

add_dihedral_atom(name, element, n1, n2, n3, dist, angle, dihed, structure=None, residue=None, bonded=False, occupancy=None, info_from=None)

Experimental API . Add an atom given 3 Atoms/xyzs and angle/distance constraints

‘element’ can be a string (atomic symbol), integer (atomic number), or an Element instance.

The atom is added to the given structure. If no structure or residue is specified, then n1/n2/n3 must be Atoms and the new atom is added to n1’s structure and residue. If just residue is specified, the new atom is added to that residue and its structure.

‘n1’ marks the position from which ‘dist’ is measured, and in combination with ‘n2’ forms ‘angle’, and then with ‘n3’ forms ‘dihed’.

if ‘bonded’ is True then n1 must be an Atom and the new atom will be bonded to it.

If ‘occupancy’ is not None or the ‘bonded’ is True and n1 has an occupancy, the new atom will be given the corresponding occupancy.

if ‘info_from’ is supplied (needs to be an Atom), miscellaneous info (see add_atom() doc string) will be obtained from that atom.

Returns the new atom.

gen_atom_name(element, residue)

Experimental API . generate non-hydrogen atom name

Atomic-related UI widgets

class AtomicStructureListWidget(session, **kw)

Bases: ModelListWidget

class AtomicStructureMenuButton(session, **kw)

Bases: ModelMenuButton

class ChainListWidget(session, *, group_identical=False, **kw)

Bases: ItemListWidget

class ChainMenuButton(session, **kw)

Bases: ItemMenuButton

class ResidueListWidget(session, **kw)

Bases: ItemListWidget

class ResidueMenuButton(session, **kw)

Bases: ItemMenuButton

class StructureListWidget(session, **kw)

Bases: ModelListWidget

class StructureMenuButton(session, **kw)

Bases: ModelMenuButton

make_elements_menu(parent, *, _session=None, _parent_menus=None)

Experimental API . keyword args for internal use only (adding Elements menu under main Select menu)