`PyMOLObject`#

class biotite.interface.pymol.PyMOLObject(name, pymol_instance=None, delete=True)[source]#

Bases: object

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

This class conveniently provides thin wrappers around PyMOL commands that allows NumPy-style atom indices to select atoms instead of PyMOL selection expressions. The following PyMOL commands are supported:

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 active PyMOL instance 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.
object_typePyMOLObject.Type: The type of this PyMOL object.

class Type(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Defines what this PyMOLObject represents.

MOLECULE = 'object:molecule'#

MAP = 'object:map'#

MESH = 'object:mesh'#

SLICE = 'object:slice'#

SURFACE = 'object:surface'#

MEASUREMENT = 'object:measurement'#

CGO = 'object:cgo'#

GROUP = 'object:group'#

VOLUME = 'object:volume'#

SELECTION = 'selection'#

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

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.

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.

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

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 active PyMOL instance is used. If no PyMOL instance is currently running, PyMOL is started in library mode.
deletebool, optional: If set to true, the underlying PyMOL object will be removed from the PyMOL session, when this object is garbage collected.
delocalize_bondsbool, optional: If set to true, use PyMOL’s delocalized bond order for aromatic bonds. Otherwise, always use formal bond orders.

Returns:

pymol_objectPyMOLObject: The PyMOLObject representing the given structure.

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

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

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

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

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

surface_color(color, selection=None)#

Change the color of displayed surfaces.

This method is a thin wrapper around PyMOL set("surface_color").

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.

to_structure(state=None, altloc='first', 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.

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

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.

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.

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.