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, representation=None)¶

Change the color of atoms.

This method is a thin wrapper around the PyMOL color() or set("xxx_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.
representation{“sphere”, “surface”, “mesh”, “dot”, “cartoon”, “ribbon”}, optional: Colors only the given representation by internally calling set("xxx_color"). By default, all representations are affected, i.e. color() is called internally.

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.

Navigation

Related Topics

PyMOLObject API¶