luna.wrappers.pymol module

class PymolSessionManager(show_cartoon=False, bg_color='white', add_directional_arrows=True, show_res_labels=True, inter_color=<luna.util.ColorPallete object>, pse_export_version='1.8')[source]

Bases: object

Class to start, manage, and save Pymol sessions. This class provides useful built-in functions to load PDB/Mol files and show interactions.

Note

This class is not intended to be used directly because set_view() is not implemented by default. Instead, you should use a class that inherits from PymolSessionManager and implements set_view(). An example is the class InteractionViewer that implements a custom set_view() to show interactions. Therefore, you should define your own logic beyond set_view() to save a Pymol session that meets your goals.

Parameters

  • show_cartoon (bool) – If True, show the protein structure as cartoons.

  • bg_color (str) – The background color. The default value is “white”. Check Pymol to discover which colors are available.

  • add_directional_arrows (bool) – If True, show arrows for directional interactions (e.g., hydrogen bonds and multipolar interactions).

  • show_res_labels (bool) – If True (the default), show residue labels.

  • inter_color (ColorPallete) – A Pymol-compatible color scheme for interactions. The default value is PYMOL_INTERACTION_COLOR.

  • pse_export_version (str) – Define a legacy format for saving Pymol sessions (PSE files). The default value os ‘1.8’.

finish_session()[source]

Clear all objects and resets all parameters to default.

load_pdb(pdb_file, pdb_obj, mol_block=None, is_ftmap_output=False)[source]

Load molecules from PDB files to the current Pymol session.

Optionally, ligands can also be loaded from a separate molecular string block. This is especially useful when working with docked molecules in which the protein structure is in a PDB file and ligands are in a separate molecular file.

Parameters

  • pdb_file (str) – The pathname of the PDB file to be loaded.

  • pdb_obj (str) – Pymol object to store the loaded structure.

  • mol_block (str, optional) – A molecular string block to load together with the PDB file.

  • is_ftmap_output (bool) – If the PDB file is an FTMap output. If so, an additional processing step is performed to standardize the loaded Pymol objects.

new_session(data, output_file)[source]

Start a new session, which includes the following steps:

  • Start a new Pymol session (start_session());

  • Set the view (set_view());

  • Save the Pymol session to output_file;

  • Finish the Pymol session.

Parameters

  • data (iterable) – Data to be processed by set_view().

  • output_file (str) – The pathname to where the Pymol session will be saved.

save_session(output_file)[source]

Save the Pymol session as a PSE file of name output_file.

set_interactions_view(interactions, main_grp, secondary_grp=None)[source]

Display molecular interactions.

Parameters

  • interactions (iterable of InteractionType) – A sequence of interactions to show.

  • main_grp (str) – Main Pymol object to store atom groups.

  • secondary_grp (str, optional) – Secondary Pymol object to store interactions. If not provided, main_grp will be used instead.

set_last_details_to_view()[source]

This method can be called to apply final modifications to the Pymol session. In its default version, the following modifications are applied:

  • Dash radius for interactions is set to 0.08;

  • Labels are set to bold and their size is set to 20;

  • Atomic spheres’ scale is set to 0.3;

  • Hydrogen atoms are hidden;

  • The view is centered within the visible objects.

set_view(data)[source]

Set the session view. However, this method is not implemented by default. Instead, you should use a class that inherits from PymolSessionManager and implements set_view(). An example is the class InteractionViewer that implements a custom set_view() to show interactions. Therefore, you should define your own logic beyond set_view() to save a Pymol session that meets your goals.

Parameters

data (iterable) – The data that will be used to set the Pymol view.

start_session()[source]

Start a new session and set Pymol settings, including the background color and the PSE export version.

class PymolWrapper[source]

Bases: object

This class provides functions to provide easy access to common functions from Pymol.

add_pseudoatom(name, opts=None)[source]

Create a molecular object with a pseudoatom or add a pseudoatom to a molecular object if the specified object already exists.

Parameters

  • name (str) – The object name to create or modify.

  • opts (dict) – A set of options to create the pseudoatom. Check Pymol to discover which options are available.

align(mobile, target, opts=None)[source]

Align the structure mobile to the target structure.

Parameters

  • mobile (str) – The structure to be aligned given by an atomic selection.

  • target (str) – The target structure given by an atomic selection.

  • opts (dict) – Alignment options. Check Pymol to discover which options are available.

alter(selection, expression)[source]

Modify atomic properties.

Parameters

  • selection (str) – The expression to select atoms.

  • expression (str) – Expression in Python language to define which properties should be modified. This can be used, for instance, to rename an atom or chain.

Examples

Alter the name of a ligand carbon from ‘C1’ to ‘CA’.

>>> pw_obj.alter("hetatm and name C1", "name='CA'")

Alter the chain A name to ‘Z’.

>>> pw_obj.alter("chain A", "chain='Z'")
arrow(name, atm_sel1, atm_sel2, opts=None)[source]

Draw an arrow object between two atoms given by their selection-expressions.

Parameters

  • name (str) – Name of the arrow object to create.

  • sel1 (str) – The expression to select the first atom.

  • sel2 (str) – The expression to select the second atom.

  • opts (dict) – A set of options to create the arrow. Check Pymol to discover which options are available.

center(selection)[source]

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

color(tuples)[source]

Color objects and atoms.

Parameters

tuples (iterable of tuple) – Each tuple should contain a color (e.g., ‘red’) and a selection (e.g., ‘hetatm’).

color_by_element(selections, c_color='green')[source]

Color atoms by their default element color (e.g., oxygen in red).

Parameters

  • selections (iterable of str) – A sequence of selections to define which atoms will be colored by element.

  • c_color ({‘green’, ‘cyan’, ‘light magenta’, ‘yellow’, ‘salmon’, ‘white’, ‘slate’, ‘bright orange’, ‘purple’, ‘pink’}) – The carbon color. The default value is ‘green’.

create(name, selection)[source]

Create a new molecular object from a selection.

Note that the selected atoms won’t be extracted from the original object. Instead, a copy of them will be created in the new object.

Parameters

  • name (str) – The object name to be created.

  • selection (str) – The expression to select atoms.

delete(selections)[source]

Delete the provided selections.

Parameters

selections (iterable of str) – A sequence of selections to be deleted. Wildcards can be used to define object or selection names.

distance(name, sel1, sel2)[source]

Create a new distance object between two atoms given by their selection-expressions.

Parameters

  • name (str) – Name of the distance object to create.

  • sel1 (str) – The expression to select the first atom.

  • sel2 (str) – The expression to select the second atom.

extract(tuples)[source]

Perform multiple extractions, i.e., extract atoms from an object to another object.

Parameters

tuples (iterable of tuple) – Each tuple should contain the object name to where atoms will be added and the selection itself that defines which atoms will be extracted (e.g., ‘hetatm’).

get_cmd()[source]

Expose the Pymol cmd object, so that one can call Pymol functions directly.

get_coords(selection)[source]

Get atomic coordinates for a given atom selection.

Parameters

selection (str) – The expression to select atoms.

Returns

Atomic coordinates (x, y, z) of each atom selected.

Return type

array_like of float (size 3)

get_names(obj_type)[source]

Get names of objects, grouped objects, or selections.

Parameters

obj_type ({‘objects’, ‘selections’, ‘all’, ‘public_objects’, ‘public_selections’, ‘public_nongroup_objects’, ‘public_group_objects’, ‘nongroup_objects’, ‘group_objects’}) – The target object type.

Return type

list of str

group(name, members, action=None)[source]

Create or update a group object.

Parameters

  • name (str) – The group name to create or update.

  • members (iterable of str) – The objects to include in the group.

  • action ({‘add’, ‘remove’, ‘open’, ‘close’, ‘toggle’, ‘auto’, ‘empty’, ‘purge’, ‘excise’}, optional) – An action to take. If not provided, the default value ‘auto’ will be used instead. The description of the actions are described below (source: Pymol documentation):

    • add: add members to group.

    • remove: remove members from group (members will be ungrouped).

    • empty: remove all members from group.

    • purge: remove all members from group and delete them.

    • excise: remove all members from group and delete group.

    • open: expand group display in object menu panel.

    • close: collapse group display in object menu panel.

    • toggle: toggle group display in object menu panel.

    • auto: add or toggle.

group_exists(name)[source]

Check if a group of objects exists given by its name name.

hide(tuples)[source]

Hide atom and bond representations for certain selections.

Parameters

tuples (iterable of tuple) – Each tuple should contain a Pymol representation (e.g., ‘sticks’) and a selection (e.g., ‘hetatm’).

hide_all()[source]

Hide all representations.

label(tuples)[source]

Draw text labels for PyMOL objects.

Parameters

tuples (iterable of tuple) – Each tuple should contain a selection (e.g., ‘hetatm’) and some string to label the given selection.

load(input_file, obj_name=None)[source]

Load a molecular file (e.g., PDB files).

Parameters

  • input_file (str) – The pathname of the molecular file to be loaded.

  • obj_name (str, optional) – Pymol object to store the loaded structure. If not provided, the filename will be used instead.

load_mol_from_pdb_block(pdb_block, obj_name)[source]

Load a molecular file from a PDB block string.

Parameters

  • pdb_block (str) – The PDB block string.

  • obj_name (str) – Pymol object to store the loaded structure.

obj_exists(name)[source]

Check if an object exists given by its name name.

quit()[source]

Terminate Pymol.

reinitialize()[source]

Clear all objects and resets all parameters to default.

remove(selections)[source]

Remove a selection of atoms from models.

Parameters

selections (iterable of str) – A sequence of selections to define which atoms will be removed.

run(func_name, opts)[source]

Run a Pymol command func_name with parameters opts.

Parameters

  • func_name (str) – The Pymol command name.

  • opts (dict) – Parameters to pass to the command.

run_cmds(commands)[source]

Run a set of Pymol commands.

Parameters

commands (iterable of tuple) – Each tuple should contain a Pymol command and its parameters. See run() to more details.

save_png(output_file, width=1200, height=1200, dpi=100, ray=1)[source]

Save the current Pymol session as a PNG format image file.

Parameters

  • output_file (str) – The output image pathname.

  • width (int) – The width in pixels. The default value is 1,200.

  • height (int or str) – The height in pixels. The default value is 1,200.

  • dpi (float) – Dots-per-inch. The default value is 100.

  • ray ({0, 1}) – If 1 (the default), run ray first to make high-resolution photos.

save_session(output_file)[source]

Save the current PyMOL state to a PSE format file to later use.

Parameters

output_file (str) – The output pathname.

sel_exists(name)[source]

Check if a selection exists given by its name name.

select(selection, name='sele', enable=0)[source]

Create a named selection from an atom selection.

Parameters

  • selection (str) – The expression to select atoms.

  • name (str) – The selection name, which by default is ‘sele’.

  • enable ({0, 1}) – If 1, activate the selection, i.e., show selection indicators. The default value is 0, which implies the selection indicators won’t be shown.

set(name, value, opts=None)[source]

Modify global, object, object-state, or per-atom settings.

Parameters

  • name (str) – The setting name to modify.

  • value (str) – The new setting value.

  • opts (dict) – A set of options. Check Pymol to discover which options are available.

show(tuples)[source]

Display atom and bond representations for certain selections.

Parameters

tuples (iterable of tuple) – Each tuple should contain a Pymol representation (e.g., ‘sticks’) and a selection (e.g., ‘hetatm’).

mybio_to_pymol_selection(entity)[source]

Transform an Entity instance into a Pymol selection-expression, which can then be used to select atoms in a Pymol session.

Parameters

entity (Entity) – An entity to be transformed into a Pymol selection-expression.

Returns

The Pymol selection-expression.

Return type

str

Examples

First, let’s parse a PDB file to work with.

>>> from luna.util.default_values import LUNA_PATH
>>> from luna.MyBio.PDB.PDBParser import PDBParser
>>> pdb_parser = PDBParser(PERMISSIVE=True, QUIET=True)
>>> structure = pdb_parser.get_structure("Protein", f"{LUNA_PATH}/tutorial/inputs/3QQK.pdb")

Now, let’s get the Pymol selection-expression for the chain A.

>>> from luna.wrappers.pymol import mybio_to_pymol_selection
>>> print(mybio_to_pymol_selection(structure[0]['A']))
chain A

Finally, we can get the Pymol selection-expression for the ligand X02.

>>> from luna.wrappers.pymol import mybio_to_pymol_selection
>>> print(mybio_to_pymol_selection(structure[0]["A"][('H_X02', 497, ' ')]))
resn X02 AND res 497 AND chain A