PyMOLObject API

class ammolite.PyMOLObject(name, pymol_instance=None, delete=True)

A wrapper around a PyMOL object (PyMOL model), usually created by the static from_structure() method.

This class is primarily used to create PyMOL selection strings from boolean masks of an corresponding AtomArray or AtomArrayStack via the where(). Additionally, objects of this class provide wrapper methods for common PyMOL commands (e.g. show() or color()), that directly support boolean masks for the selection parameter.

Instances of this class become invalid, when atoms are added to or are deleted from the underlying PyMOL object. Calling methods of such an an invalidated object raises an ModifiedObjectError. Likewise, calling methods of an object, of which the underlying PyMOL object does not exist anymore, raises an NonexistentObjectError.

Parameters
namestr

The name of the PyMOL object.

pymol_instancemodule or SingletonPyMOL or PyMOL, optional

If PyMOL is used in library mode, the PyMOL or SingletonPyMOL object is given here. If otherwise PyMOL is used in GUI mode, the pymol module is given. By default the currently used PyMOL instance (ammolite.pymol) is used. If no PyMOL instance is currently running, PyMOL is started in library mode.

deletePyMOL, optional

If set to true, the underlying PyMOL object will be removed from the PyMOL session, when this object is garbage collected.

Attributes
namestr

The name of the PyMOL object.

static from_structure(atoms, name=None, pymol_instance=None, delete=True)

Create a PyMOLObject from an AtomArray or AtomArrayStack and add it to the PyMOL session.

Parameters
atomsAtomArray or AtomArrayStack

The structure to be converted.

namestr, optional

The name of the newly created PyMOL object. If omitted, a unique name is generated.

pymol_instancemodule or SingletonPyMOL or PyMOL, optional

If PyMOL is used in library mode, the PyMOL or SingletonPyMOL object is given here. If otherwise PyMOL is used in GUI mode, the pymol module is given. By default the currently used PyMOL instance (ammolite.pymol) is used. If no PyMOL instance is currently running,

*PyMOL* is started in library mode.
deletePyMOL, optional

If set to true, the underlying PyMOL object will be removed from the PyMOL session, when this object is garbage collected.

to_structure(state=None, altloc='first', extra_fields=None, include_bonds=False)

Convert this object into an AtomArray or AtomArrayStack.

The returned AtomArray contains the optional annotation categories b_factor, occupancy and charge.

Parameters
stateint, optional

If this parameter is given, the function will return an AtomArray corresponding to the given state of the PyMOL object. If this parameter is omitted, an AtomArrayStack containing all states will be returned, even if the PyMOL object contains only one state.

altloc{‘first’, ‘occupancy’, ‘all’}

This parameter defines how altloc IDs are handled:

  • 'first' - Use atoms that have the first altloc ID appearing in a residue.

  • 'occupancy' - Use atoms that have the altloc ID with the highest occupancy for a residue.

  • 'all' - Use all atoms. Note that this leads to duplicate atoms. When this option is chosen, the altloc_id annotation array is added to the returned structure.

include_bondsbool, optional

If set to true, an associated BondList will be created for the returned structure.

Returns
structureAtomArray or AtomArrayStack

The converted structure. Whether an AtomArray or AtomArrayStack is returned depends on the state parameter.


exists()

Check whether the underlying PyMOL object still exists.

Returns
bool

True if the PyMOL session contains an object with the name of this PyMOLObject, false otherwise.


where(index)

Convert a Biotite-compatible atom selection index (integer, slice, boolean mask, index array) into a PyMOL selection expression.

Parameters
indexint or slice or ndarray, dtype=bool or ndarray, dtype=int

The boolean mask to be converted into a selection string.

Returns
expressionstr

A PyMOL compatible selection expression.


alter(selection, expression)

Change atomic properties using an expression evaluated within a temporary namespace for each atom.

This method is a thin wrapper around the PyMOL alter() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on.

expressionstr

The properties of the selected atoms are changed based on this expression.

cartoon(type, selection=None)

Change the default cartoon representation for a selection of atoms.

This method is a thin wrapper around the PyMOL cartoon() command.

Parameters
typestr

One of

  • 'automatic',

  • 'skip',

  • 'loop',

  • 'rectangle',

  • 'oval',

  • 'tube',

  • 'arrow' or

  • 'dumbbell'.

selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

center(selection=None, state=None, origin=True)

Translate the window, the clipping slab, and the origin to a point centered within the atom selection.

This method is a thin wrapper around the PyMOL center() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

stateint, optional

The state to apply the command on. By default, the command is applied on all states of this PyMOL object.

originbool, optional

If set to false, the origin is left unchanged.

clip(mode, distance, selection=None, state=None)

Alter the positions of the near and far clipping planes.

This method is a thin wrapper around the PyMOL clip() command.

Parameters
mode{‘near’, ‘far’, ‘move’, ‘slab’, ‘atoms’}
  • near - Move the near plane

  • far - Move the far plane

  • move - Move slab

  • slab - Set slab thickness

  • atoms - clip selected atoms with the given buffer

distancefloat

The meaning of this parameter depends on mode.

selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

stateint, optional

The state to apply the command on. By default, the command is applied on all states of this PyMOL object.

color(color, selection=None)

Change the color of atoms.

This method is a thin wrapper around the PyMOL color() command.

Parameters
colorstr or tuple(float, float, float)

Either a PyMOL color name or a tuple containing an RGB value (0.0 to 1.0).

selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

Notes

If an RGB color is given, the color is registered as a unique named color via the set_color() command.

desaturate(selection=None, a=0.5)

Desaturate the colors of the selected atoms.

This method is a thin wrapper around the PyMOL desaturate() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

afloat

A desaturation factor between 0.0 and 1.0.

disable(selection=None)

Turn off display of the selected atoms.

This method is a thin wrapper around the PyMOL disable() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

distance(name, selection1, selection2, cutoff=None, mode=None, show_label=True, width=None, length=None, gap=None)

Create a new distance object between two atom selections.

This method is a thin wrapper around the PyMOL distance() command.

Parameters
namestr

Name of the distance object to create.

selection1, selection2str or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on.

cutofffloat, optional

The longest distance to show.

mode: {0, 1, 2, 3, 4}, optional
  • 0 - All interatomic distances

  • 1 - Only bond distances

  • 2 - Only polar contact distances

  • 3 - All interatomic distances, use distance_exclusion setting

  • 4 - Distance between centroids

show_labelbool, optional

Whether to show the distance as label.

width, length, gapfloat optional

The width and length of each dash and the gap length between the dashes.

dss(selection=None, state=None)

Determine the secondary structure of the selected atoms.

This method is a thin wrapper around the PyMOL dss() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

stateint, optional

The state to apply the command on. By default, the command is applied on all states of this PyMOL object.

enable(selection=None)

Turn on display of the selected atoms.

This method is a thin wrapper around the PyMOL enable() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

hide(representation, selection=None)

Turn off an atom representation (e.g. sticks, spheres, etc.).

This method is a thin wrapper around the PyMOL hide() command.

Parameters
representationstr

One of

  • 'lines',

  • 'spheres',

  • 'mesh',

  • 'ribbon',

  • 'cartoon',

  • 'sticks',

  • 'dots',

  • 'surface',

  • 'label',

  • 'extent',

  • 'nonbonded',

  • 'nb_spheres',

  • 'slice' or

  • 'cell'.

selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

indicate(selection=None)

Show a visual representation of the selected atoms.

This method is a thin wrapper around the PyMOL indicate() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

label(selection, text)

Label the selected atoms.

This method is a thin wrapper around the PyMOL label() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on.

textstr

The label text.

orient(selection=None, state=None)

Align the principal components of the selected atoms with the xyz axes.

This method is a thin wrapper around the PyMOL orient() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

stateint, optional

The state to apply the command on. By default, the command is applied on all states of this PyMOL object.

origin(selection=None, state=None)

Set the center of rotation about the selected atoms.

This method is a thin wrapper around the PyMOL origin() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

stateint, optional

The state to apply the command on. By default, the command is applied on all states of this PyMOL object.

select(name, selection=None)

Create a named selection object from the selected atoms.

This method is a thin wrapper around the PyMOL select() command.

Parameters
namestr

Name of the selection object to create.

selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

set(name, value, selection=None, state=None)

Change per-atom settings.

This method is a thin wrapper around the PyMOL set() command.

Parameters
namestr

The name of the setting to be changed. One of

  • 'sphere_color',

  • 'surface_color',

  • 'mesh_color',

  • 'label_color',

  • 'dot_color',

  • 'cartoon_color',

  • 'ribbon_color',

  • 'transparency' (for surfaces) or

  • 'sphere_transparency'.

valueobject

The new value for the given setting name.

selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

stateint, optional

The state to apply the command on. By default, the command is applied on all states of this PyMOL object.

set_bond(name, value, selection1=None, selection2=None, state=None)

Change per-bond settings for all bonds which exist between two atom selections.

This method is a thin wrapper around the PyMOL set_bond() command.

Parameters
namestr

The name of the setting to be changed. One of

  • 'valence',

  • 'line_width',

  • 'line_color',

  • 'stick_radius',

  • 'stick_color' or

  • 'stick_transparency'.

valueobject

The new value for the given setting name.

selection1, selection2str or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, selection1 applies to all atoms of this PyMOL object and selection2 applies to the same atoms as selection1.

stateint, optional

The state to apply the command on. By default, the command is applied on all states of this PyMOL object.

show(representation, selection=None)

Turn on an atom representation (e.g. sticks, spheres, etc.).

This method is a thin wrapper around the PyMOL show() command.

Parameters
representationstr

One of

  • 'lines',

  • 'spheres',

  • 'mesh',

  • 'ribbon',

  • 'cartoon',

  • 'sticks',

  • 'dots',

  • 'surface',

  • 'label',

  • 'extent',

  • 'nonbonded',

  • 'nb_spheres',

  • 'slice' or

  • 'cell'.

selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

show_as(representation, selection=None)

Turn on a representation (e.g. sticks, spheres, etc.) and hide all other representations.

This method is a thin wrapper around the PyMOL show_as() command.

Parameters
representationstr

One of

  • 'lines',

  • 'spheres',

  • 'mesh',

  • 'ribbon',

  • 'cartoon',

  • 'sticks',

  • 'dots',

  • 'surface',

  • 'label',

  • 'extent',

  • 'nonbonded',

  • 'nb_spheres',

  • 'slice' or

  • 'cell'.

selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

smooth(selection=None, passes=1, window=5, first=1, last=0, ends=False)

Perform a moving average over the coordinate states.

This method is a thin wrapper around the PyMOL smooth() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

passesint, optional

The number of smoothing passes.

windowsint, optional

The size of the moving window.

first, lastint, optional

The interval of states to smooth.

endsbool, optional

If set to true, the end states are also smoothed using a weighted asymmetric window.

unset(name, selection=None, state=None)

Clear per-atom settings.

This method is a thin wrapper around the PyMOL set() command.

Parameters
namestr

The name of the setting to be cleared. One of

  • 'sphere_color',

  • 'surface_color',

  • 'mesh_color',

  • 'label_color',

  • 'dot_color',

  • 'cartoon_color',

  • 'ribbon_color',

  • 'transparency' (for surfaces) or

  • 'sphere_transparency'.

selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

stateint, optional

The state to apply the command on. By default, the command is applied on all states of this PyMOL object.

unset_bond(name, selection1=None, selection2=None, state=None)

Clear per-bond settings for all bonds which exist between two atom selections.

This method is a thin wrapper around the PyMOL unset_bond() command.

Parameters
namestr

The name of the setting to be cleared. One of

  • 'valence',

  • 'line_width',

  • 'line_color',

  • 'stick_radius',

  • 'stick_color' or

  • 'stick_transparency'.

selection1, selection2str or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, selection1 applies to all atoms of this PyMOL object and selection2 applies to the same atoms as selection1.

stateint, optional

The state to apply the command on. By default, the command is applied on all states of this PyMOL object.

zoom(selection=None, buffer=0.0, state=None, complete=False)

Scale and translate the window and the origin to cover the selected atoms.

This method is a thin wrapper around the PyMOL zoom() command.

Parameters
selectionstr or int or slice or ndarray, dtype=bool or ndarray, dtype=int, optional

A Biotite compatible atom selection index, e.g. a boolean mask, or a PyMOL selection expression that selects the atoms of this PyMOL object to apply the command on. By default, the command is applied on all atoms of this PyMOL object.

bufferfloat, optional

An additional distance to the calculated camera position.

stateint, optional

The state to apply the command on. By default, the command is applied on all states of this PyMOL object.

completebool, optional

If set to true, it is insured that no atoms centers are clipped.


class ammolite.NonexistentObjectError

Indicates that a PyMOL object with a given name does not exist.


class ammolite.ModifiedObjectError

Indicates that a atoms were added to or removed from the PyMOL object after the corresponding PyMOLObject was created.