schrodinger.project.surface module

Pythonic wrappings for mmsurf surfaces retrieved from a project

class schrodinger.project.surface.ProjectSurface(proj_handle, eid, name, proj_row)

Bases: schrodinger.surface.Surface

A Pythonic wrapping for mmsurf surfaces retrieved from a project. ProjectSurface objects are typically accessed via the schrodinger.project.ProjectRow.surface SurfaceDict object or created via schrodinger.project.ProjectRow.newMolecularSurface.

__init__(proj_handle, eid, name, proj_row)
Parameters
  • proj_handle (int) – The project handle

  • eid (str) – The entry ID of the entry containing the surface

  • name (str) – The name of the surface

Note

This method does not confirm that the specified surface exists, as this check is done in SurfaceDict.__getitem__. Attempting to get or set values on a non-existent surface will lead to a RuntimeError.

delete()

Delete this surface. After the surface is deleted, any further attempt to interact with this object will result in a RuntimeError.

setColoring(coloring)

Set the surface coloring. Must be one of:

  • A ColorBy value other than ColorBy.SourceColor to color based on the nearest atom

  • A Color value for constant coloring

  • A list or numpy array containing a color for each vertex

property name

The name of the surface. Note that all surfaces for a given project entry have unique names. :type: str

rename(new_name, overwrite=True)

Rename this surface

Parameters
  • new_name (str) – The new surface name

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

classmethod newMolecularSurface(proj, row, name, asl=None, atoms=None, resolution=0.5, probe_radius=None, vdw_scaling=1.0, mol_surf_type=MolSurfType.molecular, overwrite=True)

Create a new molecular surface for the specified project row

Parameters
  • proj (schrodinger.project.Project) – The project that this surface will be part of

  • row (schrodinger.project.ProjectRow) – The project row that this surface will belong to. This is the structure that the surface will be created around.

  • 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 MolSurfType.Molecular or MolSurfType.Extended. May not be given if mol_surf_type is 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 (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

ProjectSurface

classmethod addSurfaceToProject(surf, proj, row, overwrite=True, copy=False)

Add an existing Surface object to a project. Note that, by default, this method will invalidate the input Surface object, as the mmsurf handle will be managed by the project.

Parameters
  • surf (Surface) – The surface to add.

  • proj (schrodinger.project.Project) – The project to add the surface to.

  • row (schrodinger.project.ProjectRow) – The project row to add the surface to.

  • 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.

  • copy (bool) – If True, a copy of the surface will be added to the project and the input surface will not be invalidated.

classmethod read(filename)

Read surface data from a file.

Parameters

filename (str) – The file to read from.

Returns

The read surface.

Return type

Surface

class Color(color)

Bases: object

Represent a color as either an integer (colormap index), string (color name or hex “RRGGBB” value), or an RGB value (tuple/list of 3 ints, values 0-255).

Provides the following properties and methods:
  • Color.index = int(Color) - mmcolor index of the closest color

  • Color.name = str(Color) - mmcolor name of the closest color

  • Color.rgb - (tuple of 0-255 ints)

  • equal = (col1 == col2)

When object is initialized from the RGB value, the Color.index and Color.name attributes are set to the closest color in the mmcolor palette.

__init__(color)
property hex_string

Returns the color as string of hex RGB values (RRGGBB). For example, pure red will be returned as “FF0000”.

property rgb_float

Returns a tuple of (R, G, B) for this color, each ranging from 0.0 to 1.0.

class ColorBy(value)

Bases: schrodinger.StrEnum

Values for surface color schemes.

source_color = 'Color'
partial_charge = 'Atom Partial Charge'
atom_type = 'Atom Type'
atom_typeMM = 'Atom Type (MacroModel)'
chain_name = 'Chain Name'
element = 'Element'
mol_number = 'Molecule Number'
mol_number_carbon = 'Element (Molecule Number Carbons)'
residue_charge = 'Residue Charge'
residue_hydrophobicity = 'Residue Hydrophobicity'
residue_position = 'Residue Position'
residue_type = 'Residue Type'
grid_property = 'Grid Property'
atom_color = 'Atom Color'
cavity_depth = 'Cavity Depth'
class ColorFrom(value)

Bases: enum.IntEnum

Values for surface color sources.

surface = 0
vertex = 1
nearest_asl_atom = 2
volume = 3
entry = 4
SURFACE_TYPE_NAME = {MolSurfType.vdw: 'van der Waals', MolSurfType.extended: 'extended radius', MolSurfType.molecular: 'molecular surface'}
class Style(value)

Bases: enum.IntEnum

Surface representation styles.

solid = 0
mesh = 1
dot = 2
property back_transparency

The transparency of the back of the surface (relative to the workspace camera position). Measured on a scale from 0 (fully opaque) to 100 (fully transparent). :type: int

property color

The constant surface color. This value may be ignored unless color_source is set to ColorFrom.Surface and color_scheme is set to ColorBy.SourceColor. Note that coloring()/setColoring() are recommended over directly manipulating color, as this will ensure that color_source and color_scheme are set correctly. :type: Color

property color_scheme

The color scheme used to determine surface colors. This value may be ignored unless color_source is set to ColorFrom.NearestAslAtom. Note that coloring()/setColoring() are recommended over directly manipulating color_scheme, as this will ensure that color_source is set correctly. :type: ColorBy

property color_source

The source of the surface colors. Note that coloring()/setColoring() are recommended over directly manipulating color_source, as this will ensure that color_source is set correctly. :type: ColorFrom

coloring()

Return the current surface coloring. Is only guaranteed to return a non-None value if the surface coloring was set via setColoring. If the surface coloring cannot be determined, will return None.

Returns

The current surface coloring

Return type

ColorBy, Color, numpy.ndarray, or NoneType

copy()

Create a copy of this surface. Note that this method will always return a Surface object, even when a ProjectSurface object is copied.

Returns

The copied surface

Return type

Surface

curvatures(curvature_type)

Return curvature values for all vertices.

Parameters

curvature_type – mmsurf.CURVATURE_GAUSS, mmsurf.CURVATURE_MIN, mmsurf.CURVATURE_MAX, mmsurf.CURVATURE_MEAN

Type

curvature_type: mmsurf.CurvatureType enum

Return type

numpy.array

property darken_colors_by_cavity_depth

Whether the colors on the surface should be darkened based on the cavity depth. :type: bool

property front_transparency

The transparency of the front of the surface (relative to the workspace camera position). Measured on a scale from 0 (fully opaque) to 100 (fully transparent). :type: int

property has_vertex_colors

Does this surface contain manually specified per-vertex colors? :type: bool

hide()

Hides the surface.

property isovalue

The isovalue for the given surface :type: float

property nearest_atom_indices

A list of the atom indices closest to each vertex coordinate. Atom indices are listed in a corresponding order to vertex_coords. :type: list

property patch_count

The number of surface patches (i.e. triangles connecting three adjacent vertices). :type: int

property patch_vertices

A patch_count x 3 array containing vertex indices for each surface patch. :type: numpy.array

setTransparency(val)

Set both the front and the back transparency.

Parameters

val (int) – The value to set the transparency to

show()

Sets the surface to be visible.

smoothColors(colors, iterations)

Given a list of vertex colors, return a list of smoothed colors. Does not modify the surface in any way.

Parameters
  • colors (list or numpy.array) – A list or numpy array of the colors to smooth, where colors are represented as either RGB or RGBA values. Note that if this value is a numpy array, the input array will be modified in place.

  • iterations (int) – The number of smoothing iterations to carry out.

Returns

The smoothed colors as a numpy array. If colors was a numpy array, the return value will be a reference to the (modified) input array.

Return type

numpy.array

property style

The visual style of the surface representation (solid, mesh, or dot). :type: Style

property surface_area

The reported surface area of the surface :type: float

property surface_type

A textual description of the type of surface. :type: str

property surface_volume

Compute and return surface volume of the surface. Note that unlike surface_area, this is not cached, use appropriately.

Type

float

property vertex_colors

An array of manually specified per-vertex colors. :type: numpy.ndarray

property vertex_coords

A list of all vertex coordinates :type: list

property vertex_count
property vertex_normals

The normal for each vertex :type: numpy.ndarray

property visible

Whether the surface is currently visible. This setting will be remembered, but it will not have any effect until the surface is added to a project and loaded into Maestro. :type: bool

property volume_name

The volume name associated with the given surface :type: str

write(filename)

Write this surface to a file. Note that existing files will be overwritten.

Parameters

filename (str) – The file to write to.

class schrodinger.project.surface.SurfaceDict(proj, row)

Bases: collections.abc.MutableMapping

A dictionary of {surface name: ProjectSurface object} for the specified project row. Note that surfaces may not be created by assignment to a dictionary value. Use add, {addFromFile}, or schrodinger.project.ProjectRow.newMolecularSurface instead. SurfaceDict objects are typically accessed via schrodinger.project.ProjectRow.surface.

__init__(proj, row)
Parameters
  • proj (schrodinger.project.Project) – The project

  • row (L{schrodinger.project.ProjectRow) – The project row

__len__()
add(surf, overwrite=True, copy=False)

Add an existing Surface object to the project row. Note that if copy is False (the default), this method will invalidate the input Surface object, as the mmsurf handle will be managed by the project.

Parameters
  • surf (Surface) – The surface to add.

  • 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.

  • copy (bool) – If True, a copy of the surface will be added to the project and the input surface will not be invalidated.

Returns

A ProjectSurface object for the added surface.

Return type

ProjectSurface

__contains__(key)
addFromFile(filename, name=None, overwrite=True)

Read a surface from a file and add it to the project row.

Parameters
  • filename (str) – The file to read

  • name (str) – If given, the surface will be renamed to this before being loaded into the project.

  • 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

A ProjectSurface object for the added surface.

Return type

ProjectSurface

clear() None.  Remove all items from D.
get(k[, d]) D[k] if k in D, else d.  d defaults to None.
items() a set-like object providing a view on D’s items
keys() a set-like object providing a view on D’s keys
pop(k[, d]) v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) D.get(k,d), also set D[k]=d if k not in D
update([E, ]**F) None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() an object providing a view on D’s values