Package schrodinger :: Module structure :: Class Structure

Class Structure

object --+
         |
        Structure

Known Subclasses:

A general chemical structure object, which may contain multiple molecules. Structure is an object-oriented wrapper for the underlying MMCT library, where all state is stored.

There are several ways to create Structure instances. The structure.StructureReader provides a way to read Structures from a file, and the schrodinger.maestro.maestro.workspace_get function returns the workspace Structure from a Maestro session. The schrodinger.project module provides access to Structures in a Maestro project.

Properties of the Structure entry can be accessed from the property dictionary using the .mae file data name. For example, the Glide score of a docked pose may be accessed as:

   glide_score = st.property['r_i_glide_gscore']

A few additional Structure attributes are available as instance attributes (actually, as python properties). For example, the title of the structure can be accessed (and assigned) via the title attribute. See the Structure properties documentation for a full list.

Atom objects are accessed from the list-like schrodinger.structure.Structure.atom attribute. Each atom is an instance of the _StructureAtom class. See the "Properties" section of the schrodinger.structure._StructureAtom documentation for a list of available attributes (implemented again as python properties). For example, the atomic number of the first atom in a structure is accessed as:

   atomic_num = st.atom[1].atomic_number

Note that indices used to access atoms and bonds start at 1, not 0 as with regular python lists. Iteration over the atoms and bonds works as expected.

Structure atom properties may also be accessed from the atom's property dictionary. For example, the x-coordinate of the first atom may be accessed as:

   x_coord = st.atom[1].property['r_m_x_coord']

(However, it is preferable to simply use the x attribute - i.e. st.atom[1].x.)

Bond objects are instances of the schrodinger.structure._StructureBond class and are usually accessed via atoms using the schrodinger.structure._StructureAtom.bond attribute. Like atoms, bonds have some built-in attributes and a general property dictionary. Bonds can also be accessed from the schrodinger.structure.Structure.bond iterator, which iterates over all bonds in the Structure.

Iterators for various substructures can be accessed from the molecule, chain, residue, and ring attributes. Each of these yields an object that has a getAtomIndices method to get a list of atom indices, and an extractStructure method that can be used to create a separate Structure instance corresponding to the substructure.

Please see the Python Module Overview for a non-technical introduction and additional examples.

Instance Methods

[hide private]

__init__(self, handle, manage_handle=True, error_handler=None)
Initialize an object with an existing MMCT handle.

__repr__(self)
repr(x)

__copy__(self)
Allows the structure to be copied by copy.copy

__int__(self)
Return the underlying mmct handle when coerced to an integer.

copy(self)
Returns a copy of the structure.

__eq__(self, other)
Check for equality with other Structure instances based on the MMCT handle.

__ne__(self, other)
Check for inequality with other Structure instances based on the MMCT handle.

__getstate__(self)
Allows Structure to be pickled by returning a string representation

__setstate__(self, state)
Allows Structure to be unpickled by reading in a string representation

getXYZ(self, copy=True)
Get a numpy array of the xyz coordinates of all atoms in the molecule with shape (atom_total, 3).

setXYZ(self, xyz)
Set all xyz coordinates for the molecule from a numpy array.

findResidue(self, query)
Returns a _Residue object matching the given string (e.g.

_createProxy(self)
A method to create a proxy to be passed to subobjects that need to hold a reference to the parent Structure.

_proxy(...)

_createAtomContainer(self)

atom(...)
An iterable of structure atoms, each of which is a _StructureAtom instance.

_createBondContainer(self)

bond(...)
An iterable of structure bonds, each of which is a _StructureBond instance.

_createStructureMoleculeIterator(self)

molecule(...)
An iterable of molecules in the structure, each of which is a _Molecule instance.

_createStructureChainIterator(self)

chain(...)
An iterable of chains in the structure, each of which is a _Chain instance.

_createStructureRingIterator(self)

ring(...)
An iterable of rings in the structure, each of which is a _Ring instance.

_getManageHandle(self)
Return the current manage_handle attribute.

_setManageHandle(self, value)
Alter the manage_handle attribute.

_getManualUpdate(self)
Find whether mmct is in manual update mode.

_setManualUpdate(self, value)
Set the manual update mode.

_setTitle(self, title)
Set the title for this structure

_getTitle(self)
Get the title for this structure

_getAtomTotal(self)
Get total number of atoms in this structure

_getMolTotal(self)
Get total number of molecules in this structure

_getFormalCharge(self)
Get the sum of formal charges for the structure.

_getTotalWeight(self)

_getStructureResidueIterator(self)

_getStructureProperty(self)

_setStructureProperty(self, d)

retype(self)
Reassign all the MacroModel atom types based on the bond orders and formal charges.

writeToString(self, format)
Write the structure to a string representation and return the string.

write(self, filename, format=None)
Write the structure to a file, overwriting any previous content.

append(self, filename, format=None)
Append the structure to the named file.

putToM2ioFile(self, filehandle)
Used by the Maestro writer - put a single structure to the (already open) filehandle

closeBlockIfNecessary(self, filehandle)
Used by the Maestro writer to leave the header block if necessary.

deleteAtoms(self, indices, renumber_map=False)
Delete multiple atoms from the Structure.

addAtom(self, element, x, y, z, color=None, atom_type=None)
Add a new atom to the structure.

addAtoms(self, num_atoms)
Add the specified number of atoms to this structure.

extract(self, indices, copy_props=False)
Return a new structure object which contains the atoms of the current structure that appear in the specified list.

extend(self, other_structure)
Add the atoms in other_structure to the end of the current structure.

merge(self, other_structure, copy_props=False)
Return a new structure object which contains the atoms of the current structure and the atoms of other_structure.

areBound(self, atom1, atom2)
Returns True if atom1 and atom2 have a bond of any order between them and False is there is no bond.

getBond(self, atom1, atom2)
Returns a _StructureBond object for the bond between atom1 and atom2.

addBond(self, atom1, atom2, bond_type)
Add a bond of the specified type between the two atoms atom1 and atom2.

addBonds(self, bonds_list)
Add multiple bonds to this structure.

deleteBond(self, atom1, atom2)
Delete the bond between atom1 and atom2.

measure(self, atom1, atom2, atom3=None, atom4=None)
Return the measurement for the provided atoms.

adjust(self, value, atom1, atom2, atom3=None, atom4=None)
Adjust a distance, angle or dihedral angle.

inRing(self, atom1, atom2)
Returns True if atom1 and atom2 are both part of the same ring.

Set of ints

getMovingAtoms(self, fixed_atom, moving_atom)
Returns all atoms that would move if <moving_atom> is moved while <fixed_atom> is frozen.

getResidueAtoms(self, atom)
Return a list of atom objects that are in the same residue as 'atom'.

getMoleculeAtoms(self, atom)
Return a list of atom objects that are in the same molecule as 'atom'.

getChainAtoms(self, atom)
Return a list of atom objects that are in the same chain as 'atom'.

getAtomIndices(self)
Return a list of all atom indices in this structure.

isEquivalent(self, struct, check_stereo=True)
Return True if the 2 structures are equivalent Return False if the 2 structures are different

find_rings(self, sort=False)
Find all rings in the structure using SSSR.

applyStyle(self, atoms=3, bonds=3, atom_list=None)
Applies the given display styles to the atoms and bonds of the entire structure (by default) or to the atoms (and their bonds) given in atom_list.

update(self)
Update the Structure (for manual update mode).

has3dCoords(self)
Returns True if any atom in the structure has a non-zero z-coordinate.

Structure.Structure

get3dStructure(self, require_stereo=True)
If the structure is 2D (with stereo annotation properties), return a 3D version of it - volumized using fast3d.

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __str__, __subclasshook__

Static Methods

[hide private]

read(filename, index=1, error_handler=None, format=None, ignore_errors=False)
Read a single structure from file 'filename', returning a Structure instance.

Class Variables

[hide private]

_doc = '\n An iterable of residues in the structure, each o...

Properties

[hide private]

manage_handle
Return the current manage_handle attribute.

manual_update
Manual update mode boolean flag for mmct

title
Title of the structure

atom_total
Total number of atoms in the structure

mol_total
Total number of molecules in the structure

formal_charge
Sum of formal charges in the structure.

total_weight
The sum of atomic weights for the whole structure.

residue
An iterable of residues in the structure, each of which is a _Residue instance.

property
Dictionary-like container of Structure-level properties.

Inherited from object: __class__

Method Details

[hide private]

init(self, handle, manage_handle=True, error_handler=None)
(Constructor)

Initialize an object with an existing MMCT handle. The only way to get an existing handle in this module at the moment is by using the StructureReader class or the static read method below.

By default, the MMCT resources will be managed by the object. To keep these from being cleaned upon object deletion, set manage_handle=False.

Overrides: object.__init__

repr(self)
(Representation operator)

repr(x)

Overrides: object.__repr__: (inherited documentation)

getXYZ(self, copy=True)

Get a numpy array of the xyz coordinates of all atoms in the molecule with shape (atom_total, 3). Note that numpy arrays are indexed starting with 0.

You can avoid copying the underlying data by specifying copy=False, in which case modifying any values will modify the coordinate values in the Structure.

Note that if coordinates are retrieved with copy=False they will become invalid after their source Structure has been garbage collected. Any use of them after this point will likely cause a core dump. This is because the python numpy array provides access directly to the underlying C data.

findResidue(self, query)

Returns a _Residue object matching the given string (e.g. "A:123"). Currently only protein residues are supported.

If no residues were found that match the given string, or if the given string is of improper format, ValueError is raised.

NOTE: If the structure has more than one matching residue, then only the first match will be returned.

_createProxy(self)

A method to create a proxy to be passed to subobjects that need to hold a reference to the parent Structure. This prevents cyclic references and therefore allows Structure instances to be deallocated by reference counting rather than waiting for a garbage collection sweep.

atom(...)

An iterable of structure atoms, each of which is a _StructureAtom instance.

Example usage, where st is a Structure instance:

   # Access an atom (indices start at 1)
   atomobj = st.atom[n]

   # Delete an atom
   del st.atom[n]

   # Find the number of atoms
   len(st.atom)

   # Iterate over all atoms
   for atom in st.atom:
       take_some_action(atom)

Note: As with many other collections, the contents of the atom list should not be modified through additions or deletions while you are iterating over it.

bond(...)

An iterable of structure bonds, each of which is a _StructureBond instance.

To iterate over bonds:

   for bond in st.bond:
       take_some_action(bond)

Notes:

Atoms and bonds should not be added or deleted while you are iterating over bonds.
Bonds are not accessible by index.

molecule(...)

An iterable of molecules in the structure, each of which is a _Molecule instance.

Example usage:

   # Find the number of molecules in the structure
   len(st.molecule)

   # Retrieve a molecule by number (indices start at 1)
   mol = st.molecule[molnum]

   # Iterate over all molecules
   for mol in st.molecule:
       take_some_action(mol)

Note: Atoms and bonds should not be added or deleted while you are iterating over molecules.

chain(...)

An iterable of chains in the structure, each of which is a _Chain instance.

Example usage:

   # Find the number of chains in the structure
   len(st.chain)

   # Retrieve a _Chain instance by letter
   chain = st.chain[letter]

   # Iterate over chains
   for chain in st.chain:
       take_some_action(chain)

Note: Atoms and bonds should not be added or deleted while you are iterating over chains.

ring(...)

An iterable of rings in the structure, each of which is a _Ring instance.

To iterate over rings:

   for ring in st.ring:
       take_some_action(ring)

Note: Atoms and bonds should not be added or deleted while you are iterating over rings.

_setManageHandle(self, value)

Alter the manage_handle attribute. Be sure to modify the _StructureDeleter object appropriately.

retype(self)

Reassign all the MacroModel atom types based on the bond orders and formal charges. This function should be called after either of these have been changed.

read(filename, index=1, error_handler=None, format=None, ignore_errors=False)
Static Method

Read a single structure from file 'filename', returning a Structure instance.

Parameters:

index (int) - For multi-structure formats, the index of the structure to read.
error_handler (int) - The handle of the mmerr object to use for error logging. Defaults to schrodinger.infra.mm.error_handler.
format (str) - The format of the file, either 'pdb', 'sd', 'mol2', 'maestro' or 'maestro_text' (determined from file extension by default).
ignore_errors (bool) - If True, bad structures will be skipped instead of raising an exception. Currently only used by the SD reader.

writeToString(self, format)

Write the structure to a string representation and return the string. The format parameter is required.

write(self, filename, format=None)

Write the structure to a file, overwriting any previous content. Format is determined from the file suffix if None is specified, otherwise an explicit value of maestro, sd, pdb, or smiles can be used.

append(self, filename, format=None)

Append the structure to the named file.

This method should provided acceptable performance if you are writing a small number of structures, but if you need to write a large number of structures (more than a few hundred) to a file, the StructureWriter class will provide better performance.

Parameters:

format (str) - By default, the file format is determined from the filename suffix, but this can be specified explicitly. Supported option values are one of the PDB, MOL2, SD, MAESTRO, SMILES, SMILESCSV module-level constants.

closeBlockIfNecessary(self, filehandle)

Used by the Maestro writer to leave the header block if necessary. For Structure objects this is not needed so it only returns

deleteAtoms(self, indices, renumber_map=False)

Delete multiple atoms from the Structure. The argument indices must be a sequence or an iterable, and able to be interpreted as ints.

After deletion, indices are renumbered from 1 to len(atoms). Pre-existing references to Structure atoms will not be correct, as they store index values.

If renumber_map is set to True, will return a renumbering dictionary. Keys are atom numbers before deleting, and value for each is the new atom number, or None if that atom was deleted.

addAtom(self, element, x, y, z, color=None, atom_type=None)

Add a new atom to the structure. Return the created _StructureAtom object.

addAtoms(self, num_atoms)

Add the specified number of atoms to this structure.

The following atom attributes will have to be set for each atom afterwards:

element
x, y, z
color
atom_type

extract(self, indices, copy_props=False)

Return a new structure object which contains the atoms of the current structure that appear in the specified list. The argument indices must be a sequence or an iterable, and able to be interpreted as ints.

After extractions, indices are renumbered from 1 to len(atoms). Pre-existing references to Structure atoms will not be correct, as they store index values.

If copy_props is set to True, then the new structure object will inherit Structure-level properties from the source object.

extend(self, other_structure)

Add the atoms in other_structure to the end of the current structure. The other_structure is left unchanged.

merge(self, other_structure, copy_props=False)

Return a new structure object which contains the atoms of the current structure and the atoms of other_structure.

If copy_props is True, properties from the current structure and other_structure will be added to the new structure. If the same property is specifed in both the current structure and other_structure, the current value will take precedence.

getBond(self, atom1, atom2)

Returns a _StructureBond object for the bond between atom1 and atom2. The atom parameters can be _StructureAtom objects or integer indices from 1 to the number of atoms in the structure.

addBond(self, atom1, atom2, bond_type)

Add a bond of the specified type between the two atoms atom1 and atom2. The atom parameters can be _StructureAtom objects or integer indices from 1 to the number of atoms in the structure. If the two atoms are already bound then the bond type is just changed.

@param bond_type bond type (legacy integer 0-3 bond order)

addBonds(self, bonds_list)

Add multiple bonds to this structure. This is much faster than multiple calls to addBond() method when many bonds need to be added. Bonds are specified by a list of integer lists: (atom1, atom2, bond_type).

Example:

   st.addBonds([(10, 11, 1), (12, 13, 2)])

This will add a single-order bond between atoms 10 and 11, and a double-order bond between atoms 12 and 13.

deleteBond(self, atom1, atom2)

Delete the bond between atom1 and atom2. It will be an error if there is no bond between these two.

measure(self, atom1, atom2, atom3=None, atom4=None)

Return the measurement for the provided atoms. If atom3 is None, return the distance between atom1 and atom2. If atom4 is None, return the angle with atoms 1 through 3, and if all atoms are provided, return the dihedral angle.

All atom arguments can be integers or _StructureAtom objects.

If Periodic Boundary Condition CT-level properties are defined, uses the PBC measurement.

See also the structutil.measure module, which has functions to make measurements between atoms in different structures, and can also measure angles between planes.

adjust(self, value, atom1, atom2, atom3=None, atom4=None)

Adjust a distance, angle or dihedral angle. If atom3 is None then the distance between atom1 and atom2 will be set to value, atom2 and all atoms attached to that atom will be moved. If atom4 is None then the angle between atom1, atom2 and atom3 will set to value, atom3 and all other atoms attached to that will be moved. If all atoms are specified then the dihedral angle made by atom1, atom2, atom3 and atom4 will be set to value and atom4 and all other atoms attached to that will be moved. All distances are specified in Angstroms, all angles in degrees.

All atom arguments can be integers or _StructureAtom objects. There is no return value for this function.

Note, bond distances and angles within a ring system will not be adjusted. Modifications to atoms in rings via this call will silently fail. inRing() may be used to pre-check for this condition. If ring distortion from an adjustment is not an issue, then the moving bitset can be manually created and passed to mmct_atom_set_distance(), mmct_atom_set_bond_angle2(), or mmct_atom_set_dihedral_angle().

inRing(self, atom1, atom2)

Returns True if atom1 and atom2 are both part of the same ring. The test works by seeing which atoms would be transformed if movement was made on the vector atom1-atom2. If atom1 is itself part of that set then we can assume atom2 and atom1 are in the same ring.

All atom arguments can be integers or _StructureAtom objects.

getMovingAtoms(self, fixed_atom, moving_atom)

Returns all atoms that would move if <moving_atom> is moved while <fixed_atom> is frozen. This effectively returns all atoms in the same molecule substructure as <moving_atom> (atoms in the same substructure as fixed_atom are excluded).

In other words, if the bond between the moving_atom and fixed_atom (or towards the direction of fixed_atom) were to be broken, the atoms that would be in the same molecule as moving_atom are returned. Can be used for detecting things like residue side-chain atoms, etc.

NOTE: If fixed_atom and moving_atom are part of different molecules, then all atoms in the moving_atom's molecule will be returned. If fixed_atom and moving_atom are not bound directly, the intervening atoms will not be included in the result. If fixed_atom and moving_atom are connected with more than one path (are in a ring), then ValueError is raised.

Parameters:

fixed_atom (Atom index or _StructureAtom.) - Atom which is part of the molecule that is to be excluded from the result (frozen, not being moved).
moving_atom (Atom index or _StructureAtom.) - Atom of interest (atom to be moved); a set of atoms that would be moved with it (connected to it) will be returned.

Returns: Set of ints

Set of atom indices for atoms "connected" to moving_atom

those atoms that would be moved with it if it was moved. For example, if called with alpha carbon and beta carbon atoms of a protein residue, then all side-chain atoms would be returned. Atom moving_atom will also be included.

Raises ValueError if the given atoms are part of a ring (in other words, moving_atom is connected to fixed_atom via more than one path). This may happen if part of the moving_atom's "chain" is bonded to something unexpected; e.g. ZOBed to metals, or involved in a di-sulfide bond.

isEquivalent(self, struct, check_stereo=True)

Return True if the 2 structures are equivalent Return False if the 2 structures are different

struct: Another structure class object

check_stereo: Specifies whether or not to check stereo chemistry.

find_rings(self, sort=False)

Find all rings in the structure using SSSR.

Parameters:

sort (bool) - If True, sort the returned lists so that bonded atoms are adjacent in the list. If False, the order is not guaranteed.

Returns:

A list of lists of integers corresponding to the atom indices of the rings.

applyStyle(self, atoms=3, bonds=3, atom_list=None)

Applies the given display styles to the atoms and bonds of the entire structure (by default) or to the atoms (and their bonds) given in atom_list.

Parameters:

atoms (int) - Display style for atoms, given by structure module constants ATOM_NOSTYLE, ATOM_CIRCLE, ATOM_CPK, ATOM_BALLNSTICK. Default is ATOM_BALLNSTICK.
atoms (int) - Display style for bonds, given by structure module constants BOND_NOSTYLE, BOND_WIRE, BOND_TUBE, BOND_BALLNSTICK. Default is BOND_BALLNSTICK.
atom_list (iterable) - An iterable of atom objects or atom indices to apply the given styles to. If not included the styles are applied to all atoms in the structure. Possible examples include:
```
   [1, 3, 5]
   ring.atom
   schrodinger.structutils.analyze.evalulate_asl(asl_expr)
   [structure.atom[x] for x in xrange(50)]
   maestro.selected_atoms_get()
```
bonds (int)

get3dStructure(self, require_stereo=True)

If the structure is 2D (with stereo annotation properties), return a 3D version of it - volumized using fast3d. Any missing hydrogens will also be added.

Parameters:

require_stereo (bool) - Whether to require all chiral centers to have defined stereochemistry via annotation properties. Defaults to True. UndefinedStereochemistry exception is raised if any chiral atom has ambiguous chirality. If set to False, ambiguous chiralities will be expanded arbitrarily.

Returns: Structure.Structure

Volumized 3D structure.

Class Variable Details

[hide private]

_doc

Value:

'''
    An iterable of residues in the structure, each of which is a L{_Re
sidue}
    instance.

    To iterate over all residues::

        for residue in st.residue:
...

Property Details

[hide private]

manage_handle

Return the current manage_handle attribute.

Get Method:: _getManageHandle(self) - Return the current manage_handle attribute.
Set Method:: _setManageHandle(self, value) - Alter the manage_handle attribute.

manual_update

Manual update mode boolean flag for mmct

Get Method:: _getManualUpdate(self) - Find whether mmct is in manual update mode.
Set Method:: _setManualUpdate(self, value) - Set the manual update mode.

title

Title of the structure

Get Method:: _getTitle(self) - Get the title for this structure
Set Method:: _setTitle(self, title) - Set the title for this structure

atom_total

Total number of atoms in the structure

Get Method:: _getAtomTotal(self) - Get total number of atoms in this structure

mol_total

Total number of molecules in the structure

Get Method:: _getMolTotal(self) - Get total number of molecules in this structure

formal_charge

Sum of formal charges in the structure. Accessing this property is an O(N) operation.

Get Method:: _getFormalCharge(self) - Get the sum of formal charges for the structure.

total_weight

The sum of atomic weights for the whole structure.

The weight of implicit hydrogens is automatically included.

Accessing this property is an O(N) operation.

Get Method:: _getTotalWeight(self)

residue

An iterable of residues in the structure, each of which is a _Residue instance.

To iterate over all residues:

   for residue in st.residue:
       take_some_action(residue)

Get Method:: _getStructureResidueIterator(self)

Notes:

Atoms and bonds should not be added or deleted while you are iterating over residues.
residues are not accessible by index. See Structure.findResidue()

property

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

Get Method:: _getStructureProperty(self)
Set Method:: _setStructureProperty(self, d)

Class Structure

__init__(self, handle, manage_handle=True, error_handler=None) (Constructor)

__repr__(self) (Representation operator)

getXYZ(self, copy=True)

findResidue(self, query)

_createProxy(self)

atom(...)

bond(...)

molecule(...)

chain(...)

ring(...)

_setManageHandle(self, value)

retype(self)

read(filename, index=1, error_handler=None, format=None, ignore_errors=False) Static Method

writeToString(self, format)

write(self, filename, format=None)

append(self, filename, format=None)

closeBlockIfNecessary(self, filehandle)

deleteAtoms(self, indices, renumber_map=False)

addAtom(self, element, x, y, z, color=None, atom_type=None)

addAtoms(self, num_atoms)

extract(self, indices, copy_props=False)

extend(self, other_structure)

merge(self, other_structure, copy_props=False)

getBond(self, atom1, atom2)

addBond(self, atom1, atom2, bond_type)

addBonds(self, bonds_list)

deleteBond(self, atom1, atom2)

measure(self, atom1, atom2, atom3=None, atom4=None)

adjust(self, value, atom1, atom2, atom3=None, atom4=None)

inRing(self, atom1, atom2)

getMovingAtoms(self, fixed_atom, moving_atom)

isEquivalent(self, struct, check_stereo=True)

find_rings(self, sort=False)

applyStyle(self, atoms=3, bonds=3, atom_list=None)

get3dStructure(self, require_stereo=True)

_doc

manage_handle

manual_update

title

atom_total

mol_total

formal_charge

total_weight

residue

property

init(self, handle, manage_handle=True, error_handler=None)
(Constructor)

repr(self)
(Representation operator)

read(filename, index=1, error_handler=None, format=None, ignore_errors=False)
Static Method