schrodinger.utils.pymol module

Utilities to load Maestro projects into PyMOL.

Example:

>>> cmd = PymolInstance(["/path/to/pymol"])
>>> pt = maestro.project_table_get()
>>> process_prj(cmd, pt)

Copyright Schrodinger LLC, All rights reserved.

Author: Thomas Holder

class schrodinger.utils.pymol.Mapping

Bases: object

Mappings from Maestro codes to PyMOL representations and settings

surface_cmd = {0: 'isosurface', 1: 'isomesh', 2: 'isodot'}
ramp_colors = {'rainbow': '[red, yellow, green, cyan, blue, magenta]', 'redwhiteblue': '[red, white, blue]', 'whiteblue': '[white, blue]', 'whitered': '[white, red]'}
stereomethods = {'anaglyph': 'anaglyph', 'chromadepth': 'off', 'crosseyed': 'crosseye', 'hardware': 'quadbuffer', 'interlaced': 'byrow', 'walleyed': 'walleye'}
class schrodinger.utils.pymol.PymolInstance(pymol_command=('pymol',))

Bases: object

Represents a remote PyMOL instance (controlled via a one-way pipe)

Acts like a proxy to the cmd module, without return values on function calls (which would actually be very usefull).

See also: PyMOL XMLRPC server (pymol -R)

__init__(pymol_command=('pymol',))
Parameters

pymol_command (list or tuple) – path to pymol executable

Replacement for cmd.get_legal_name

Parameters

name (str) – name candidate

Returns

legal PyMOL object name

Return type

str

get_unused_name(name, alwaysnumber=1)

Replacement for cmd.get_unused_name, does not talk back to PyMOL but maintains it’s own set of already used names.

This is only necessary because the the pipe cannot return values.

Parameters
  • name (str) – name candidate

  • alwaysnumber (bool) – if False, only append a number if name already exists

Returns

unused legal PyMOL object name

Return type

str

sendVersionCheck()

Print a warning on the PyMOL log window if PyMOL version is too old.

do(cmmd)

Send command to PyMOL

Parameters

cmmd (str) – PyMOL command

Returns

True on success and False on error

Return type

bool

close()

Quit PyMOL

class schrodinger.utils.pymol.PymolScriptInstance(pymol_command=('pymol',))

Bases: schrodinger.utils.pymol.PymolInstance

Represents a PyMOL script for deferred execution.

close(args=('-cqk',))

Close file handle and execute script in PyMOL

Parameters

args (list or tuple) – extra command line arguments for pymol

__init__(pymol_command=('pymol',))
Parameters

pymol_command (list or tuple) – path to pymol executable

do(cmmd)

Send command to PyMOL

Parameters

cmmd (str) – PyMOL command

Returns

True on success and False on error

Return type

bool

Replacement for cmd.get_legal_name

Parameters

name (str) – name candidate

Returns

legal PyMOL object name

Return type

str

get_unused_name(name, alwaysnumber=1)

Replacement for cmd.get_unused_name, does not talk back to PyMOL but maintains it’s own set of already used names.

This is only necessary because the the pipe cannot return values.

Parameters
  • name (str) – name candidate

  • alwaysnumber (bool) – if False, only append a number if name already exists

Returns

unused legal PyMOL object name

Return type

str

sendVersionCheck()

Print a warning on the PyMOL log window if PyMOL version is too old.

class schrodinger.utils.pymol.VisRecord(row, idx)

Bases: object

Represents a surface entry in a “vis_list” file

Variables
  • name_pymol (str) – PyMOL object name

  • visfile (str) – filename of vis file

__init__(row, idx)
Parameters
  • row (RowProxy) – project table row

  • idx (int) – zero-based index in “m_surface” table

class schrodinger.utils.pymol.VisRecordVol(row, idx)

Bases: schrodinger.utils.pymol.VisRecord

Represents a volume entry in a “vis_list” file

Volume gets auto-loaded when accessing name_pymol.

__init__(row, idx)
Parameters
  • row (RowProxy) – project table row

  • idx (int) – zero-based index in “m_surface” table

class schrodinger.utils.pymol.RowProxy(row, cmd)

Bases: schrodinger.project.project.ProjectRow

Proxy for project table row to attach additional data.

__init__(row, cmd)
Parameters
  • row (schrodinger.project.ProjectRow) – project table row

  • cmd (PymolInstance) – PyMOL API proxy

doGroup(name)

Put name in PyMOL group, if row is in a Maestro group.

Parameters

name (str) – PyMOL object name

property cms_file

Return associated CMS file or None if there is no associated file

property cms_structure_reader

Return StructureReader for associated CMS file or EmptyIterator if there is no associated file

property deletable

Whether the entry is deletable or not

delete()

Delete this row/entry from the project.

doc = 'Inclusion state of the entry (NOT_IN_WORKSPACE/IN_WORKSPACE/LOCKED_IN_WORKSPACE)\nWARNING: This property should NOT be treated as a boolean.'
property entry_id

Entry ID of the row

getStructure(props=True, copy=True, workspace_sync=True)
Returns

The entry’s structure

Return type

structure.Structure

Parameters
  • props (bool) – Whether the associated PT properties are included in the returned structure (default).

  • copy – Whether to return a copy of the PT structure (default). If set to False, returns the original CT for the entry. Such use should in general be avoided, except as an optimization. NOTE: With copy=False, when the returned CT is modified, the changes are instantly propagated to the PT, but not the Workspace, and changes to properties do not propagate. Unless it’s certain that properties didn’t change, and that the structure is not included in the Workspace, any changes to it should be followed up by a call to setStructure().

  • workspace_sync – If this entry is included in Workspace, sync the Workspace with Project Table before retreiving entry’s structure. As an optimization, when getStructure() is called in a loop, call maestro.project_table_synchronize(), then call getStructure() with workspace_sync=False for each entry.

WARNING: The current default (copy=True) is to make a duplicate of the entry’s structure. These will be marked for garbage collection once they go out of scope in the calling code, but if, for example, you are in a loop your memory usage will grow until the loop is exited (and it may even take a while for it to drop since garbage collection is not necessarily immediate). This can cause large memory usage if, for example, you are iterating over a large number entries. In some cases you may want to explicitly delete the returned Structure. For example, in a loop iterating over a large number of entries you may want to delete the Structure while still in the loop (after you’re done processing the Structure) to prevent memory bloat.

property group

EntryGroup for the row

inWorkspace()

Obsolete. Use ProjectRow.in_workspace property instead.

property in_workspace

Inclusion state of the entry (NOT_IN_WORKSPACE/IN_WORKSPACE/LOCKED_IN_WORKSPACE) WARNING: This property should NOT be treated as a boolean.

includeOnly(scroll_to_row=False)

Include this entry in the workspace and exclude all other entries.

Parameters

scroll_to_row (bool) – If True, scroll to the included row in case it’s out of view.

property index

Internal Project index of the row. This is different from Project Table row number or from entry ID.

property is_selected

Whether the entry is selected

moveToGroup(group_name)

Move this entry to group. If group does not exist it will be created.

Parameters

group_name (str) – Name of group to which to move this entry. If such group doesn’t exist, it will be created. Note, this is different from the user-visible group title.

newMolecularSurface(*args, **kwargs)

Create a new molecular surface for this row

Parameters
  • name (str) – The name of the surface. Note that project rows require all surfaces to be named uniquely. See overwrite.

  • asl (str or NoneType) – If given, the surface will only be created for atoms in the structure that match the provided ASL. Note that only one of asl and atoms may be given. If neither are given, then the surface will be created for all atoms in the structure.

  • atoms (list or NoneType) – An optional list of atom numbers. If given, the surface will only be created for the specified atoms. Note that only one of asl and atoms may be given. If neither are given, then the surface will be created for all atoms in the structure.

  • resolution (float) – The resolution of the surface, generally between 0 and 1. Smaller numbers lead to a more highly detailed surface.

  • probe_radius (float) – The radius of the rolling sphere used to calculate the surface. Defaults to 1.4 if mol_surf_type is surface.MolSurfType.Molecular or surface.MolSurfType.Extended. May not be given if mol_surf_type is surface.MolSurfType.vdw.

  • vdw_scaling (float) – If given, all atomic radii will be scaled by the provided value before the surface is calculated.

  • mol_surf_type (surface.MolSurfType) – The type of surface to create.

  • overwrite (bool) – What to do if the new surface has the same name as an existing surface for this project row. If True, the existing surface will be overwritten. In False, a ValueError will be raised.

Returns

The new surface

Return type

project_surface.Surface

property property

Dictionary-like container of entry properties. Keys are strings of the form type_family_name as described in structure.PropertyName documentation.

property read_only

Whether the entry is read only or not

property row_number

This is the Project Table row number, as it appears to the user in Maestro. It is different from the internal row index.

selectOnly()

Select this entry and de-select all other entries in the Project Table.

setStructure(struct, props=True, copy=True, sync_workspace=True)

Set the structure of the entry to the specified structure. If the entry is included in the Workspace, the Workspace CT will be updated accordingly.

Parameters
  • struct (schrodinger.structure.Structure) – Set the entry to this Structure object

  • copy (bool) – If True, a copy of the Structure (CT) is made and that copy is used to set the entry. If False, the original Structure, struct, is placed into the project table. Doing this hands off control of struct and you should no longer use struct.

  • props (bool) – If True, update properties in the entry. If False, properties are ignored.

  • sync_workspace (bool) – Whether to update the maestro workspace

property structure

This attribute is deprecated. Please use ProjectRow.getStructure() and ProjectRow.setStructure() instead.

property surface

A dictionary of all surfaces for this row. Keys are surface names and values are project_surface.Surface objects. :type: project_surface.SurfaceDict

property surfaces

Return an interator to the surface objects available for this entry

property title

The title of the entry

ungroup()

Remove this entry from its current group.

schrodinger.utils.pymol.select_surf_asl(row, surf_handle, name='')

Make a PyMOL selection for surface ASL.

Returns

PyMOL selection name

class schrodinger.utils.pymol.WorkspaceIdMapper(prj_handle)

Bases: object

Maps workspace atom indices to (row.index, ID)

__init__(prj_handle)
Parameters

prj_handle (schrodinger.project.Project) – project handle

schrodinger.utils.pymol.get_measurement_items(key, mmprojadmin)

Get workspace atom ids from the measurements table. If not running from Maestro, read the .tab files from the .mmproj-admin directory.

Parameters

key (str) – one of distance, angle or dihedral

Return type

list(int)

Returns

List of lists of atom ids (workspace)

schrodinger.utils.pymol.create_selection(cmd, idmapper, atom_ids)

Create selection list of strings from atom ids. Like this [‘1fjs & id 345’, ‘1fjs & id 571’]

Parameters
Returns

selection list of strings

schrodinger.utils.pymol.get_interaction_data()

Get interactions data

Returns

interactions data

schrodinger.utils.pymol.create_interactions_group(cmd, interaction_name, object_names)

Create interactions group

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • interaction_name (string) – interaction’s name

  • object_names (string) – space separated string of object names which will be added to the group

schrodinger.utils.pymol.create_pi_pi_interaction_distance(cmd, idmapper, interaction_data_list, interaction_name, color)

Create workspace Pi Pi interaction as a distance object in PyMOL

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • idmapper (WorkspaceIdMapper) – id mapper

  • interaction_data_list (list) – list of interactions

  • interaction_name (string) – interaction’s name

  • name (string) – rgb color

schrodinger.utils.pymol.create_pi_cation_interaction_distance(cmd, idmapper, interaction_data_list, interaction_name, color)

Create workspace Pi Cation interaction as a distance object in PyMOL

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • idmapper (WorkspaceIdMapper) – id mapper

  • interaction_data_list (list) – list of interactions

  • interaction_name (string) – interaction’s name

  • name (string) – rgb color

schrodinger.utils.pymol.create_interaction_distance(cmd, idmapper, interaction_data_list, interaction_name, color)

Create workspace interaction as a distance object in PyMOL

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • idmapper (WorkspaceIdMapper) – id mapper

  • interaction_data_list (list) – list of interactions

  • interaction_name (string) – interaction’s name

  • name (string) – rgb color

schrodinger.utils.pymol.process_interactions(cmd, prj_handle)

Send workspace interactions to PyMOL

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • prj_handle (schrodinger.project.Project) – project handle

schrodinger.utils.pymol.process_measurements(cmd, prj_handle)

Send workspace measurements to PyMOL

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • prj_handle (schrodinger.project.Project) – project handle

schrodinger.utils.pymol.get_font_id(font_name, font_style)

Get the PyMOL label_font_id which best matches the given font name and style.

Return type

int

schrodinger.utils.pymol.process_highlights(cmd, prj_handle)

Send “highlights” (label+arrow annotation) to PyMOL

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • prj_handle (schrodinger.project.Project) – project handle

schrodinger.utils.pymol.process_prj(cmd, prj_handle, limit='all', with_surf=True, mimic=True, include_trajectories=False)

Send maestro project to PyMOL. By default send everything, optional filters may apply.

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • prj_handle (schrodinger.project.Project) – project handle

  • limit (str) – all, included or selected. The latter will not send workspace items like measurements and text highlights.

  • with_surf (bool) – send surfaces and maps (volumes)

  • mimic (bool) – use PyMOL settings to match style as close as possible

  • include_trajectories (bool) – include trajectories

schrodinger.utils.pymol.process_hypothesis(cmd, row, mae)

Import Phase pharmacophores as CGOs into PyMOL.

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • row (schrodinger.project.ProjectRow) – project table row

  • mae (str) – reference mae filename

schrodinger.utils.pymol.process_row(cmd, proj, row, limit_included=False, with_surf=True, mimic=True, include_trajectories=False)

Send a row from the project table to PyMOL.

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • proj (schrodinger.project.Project) – project

  • row (schrodinger.project.ProjectRow) – project table row

  • limit_included (bool) – limit surface export to workspace

  • with_surf (bool) – send surfaces

  • mimic (bool) – use PyMOL settings to match style as close as possible

  • include_trajectories (bool) – include trajectories

schrodinger.utils.pymol.process_trajectory(cmd, proj, row, mae_file_name, mimic=True)

Send trajectory to PyMOL

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • proj (schrodinger.project.Project) – project

  • row (RowProxy - proxy for project table with additional data) – project table row

  • mae_file_name (str) – mae file name to send to PyMOL

  • mimic (bool) – use PyMOL settings to match style as close as possible

schrodinger.utils.pymol.process_surface(cmd, row, e_surf)

Send a surface to PyMOL

Parameters
  • cmd (PymolInstance) – PyMOL API proxy

  • row (RowProxy) – project table row

  • e_surf (schrodinger.project.EntrySurface) – surface

schrodinger.utils.pymol.send_maestro_settings(cmd)

Map Maestro settings to closest matching PyMOL settings.

Parameters

cmd (PymolInstance) – PyMOL API proxy

Return type

bool

Returns

True on success and False if Maestro is not available