schrodinger.application.desmond.ffiostructure module¶

The central interface for reading and editing Maestro format chemical sructures with force field data.

FFIOStructure is a pythonic, object oriented wrapper for the mmffio library that provides access to sites, bonds, angles, dihedrals, exclusions, pairs, vdwtypes, restraints, virtuals, pseudos, constraints and their properties. It inherits from Structure and hence provides access to atoms, bonds and their properties.

The default error handler for the ffiostructure module is set to mm.error_handler. If no error handler is specified for error_handler arguments, its value is what will be used.

schrodinger.application.desmond.ffiostructure.make_property(getter, setter, doc)¶

schrodinger.application.desmond.ffiostructure.get_ffio_sub_block_std_prop_short_name(block_type, prop_name)¶: Function to get short names of properties. It is picked from the ffio_sub_block_prop_links dict if avaiable, else deduced from property name

schrodinger.application.desmond.ffiostructure.get_ffio_sub_block_std_prop_getter(block_type, prop_name)¶: Function to get mmffio getter method of properties. It is picked from the ffio_sub_block_prop_links dict if avaiable, else deduced from property name

schrodinger.application.desmond.ffiostructure.get_ffio_sub_block_std_prop_setter(block_type, prop_name)¶: Function to get mmffio setter method of properties. It is picked from the ffio_sub_block_prop_links dict if avaiable, else deduced from property name

schrodinger.application.desmond.ffiostructure.make_property_fepio(getter, setter, doc)¶

schrodinger.application.desmond.ffiostructure.get_fepio_sub_block_std_prop_short_name(block_type, prop_name)¶: Function to get short names of properties. It is picked from the fepio_sub_block_prop_links dict if avaiable, else deduced from property name

schrodinger.application.desmond.ffiostructure.get_fepio_sub_block_std_prop_getter(block_type, prop_name)¶: Function to get mmfepio getter method of properties. It is picked from the fepio_sub_block_prop_links dict if avaiable, else deduced from property name

schrodinger.application.desmond.ffiostructure.get_fepio_sub_block_std_prop_setter(block_type, prop_name)¶: Function to get mmfepio setter method of properties. It is picked from the fepio_sub_block_prop_links dict if avaiable, else deduced from property name

class schrodinger.application.desmond.ffiostructure.FFIOStructure(handle, error_handler=- 1)¶

Bases: schrodinger.structure._structure.Structure

Class to create python interface to force field data. This is just a wrapper around the mmffio/mmfepio functionality. I/O happens through the underlying libraries. mmffio/mmfepio handles are created on demand when ffio/fepio blocks are accesssed.

__init__(handle, error_handler=- 1)¶: Parent class would take care of basic CT data.

ffio¶

fepio¶

addAtom(element, x, y, z, color=None, atom_type=None)¶: Add a new atom to the structure. Return the created _StructureAtom object.

addAtoms(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

addBond(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(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.

adjust(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.

NOTE: To adjust improper dihedrals, use build.adjustImproperDihedral instead

Parameters

value (float) – value the internal coordinate will be set to
atom1 (int or _StructureAtom) – first atom in the coordinate
atom2 (int or _StructureAtom) – second atom in the coordinate
atom3 (int or _StructureAtom or None) – third atom in the coordinate (if None, the coordinate is a bond)
atom4 (int or _StructureAtom or None) – fourth atom in the coordinate (if None, the coordinate is an angle)

Raises

AtomsInRingError – if specified atoms are within a ring system.

applyCPKStyle(atom_list=None)¶

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

Parameters: 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.

applyStyle(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 – 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()

applyTubeStyle(atom_list=None)¶

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

Parameters: 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.

applyWireStyle(atom_list=None)¶

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

Parameters: 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.

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

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.

property atom_total¶: Get total number of atoms in this structure

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)

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

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.

closeBlockIfNecessary(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(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.

deleteBond(atom1, atom2)¶: Delete the bond between atom1 and atom2. Raises an Exception if there is no bond between these two.

deletePropertyFromAllAtoms(prop_name)¶

Deletes a property from all atoms present in structure

Param: prop_name: The name of the atom-level property to delete.

extend(other_structure)¶

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

Raises: ValueError – Extending a structure with itself is not allowed.

extract(indices, copy_props=False)¶

Return a new structure object which contains the atoms of the current structure that appear in the specified list.

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.

Parameters

indices (iterable or sequence) – List of atom indices to extract
copy_props (bool) – Whether to copy structure properties

Return type

Structure

Returns

Extracted structure

findResidue(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.

find_rings(sort=True)¶

Find all rings in the structure using SSSR.

Each ring is returned in connectivity order.

Parameters: sort (bool) – Deprecated and unused
Returns: A list of lists of integers corresponding to the atom indices of the rings.

property formal_charge¶: Get the sum of formal charges for the structure.

generate3dConformation(require_stereo=True)¶

Generate new 3D coordinates for the current structure, and add hydrogens if any are missing. This method is useful for “volumizing” a 2D structure into 3D. NOTE: For 2D inputs, annotation properties must be present for chiral centers to be processed correctly.

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.

get3dStructure(require_stereo=True)¶

Deprecated: Use generate3dConformation() instead.

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

getAtomPropertyNames(include_builtin=False)¶

Return a tuple of atom-level property names present in this CT.

Param: include_builtin: Whether to include built-in properties.

getBond(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.

getChainAtoms(atom)¶: Return a list of atom objects that are in the same chain as ‘atom’.

getMoleculeAtoms(atom)¶: Return a list of atom objects that are in the same molecule as ‘atom’.

getMovingAtoms(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.

Return type

Set of ints

Returns

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.

getPropertyNames()¶

getResidueAtoms(atom)¶: Return a list of atom objects that are in the same residue as ‘atom’.

getXYZ(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.

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

hasAtomProperty(prop_name)¶

Return True if the structure has the property named prop_name, False otherwise

Parameters: prop_name (str) – the name of the property

hasFfio()¶

isEquivalent(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.

measure(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.

merge(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.

property mol_total¶: Get total number of molecules in this structure

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.

property pbc¶: Access the PBC of the Structure. Throws KeyError if no PBC exists

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

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

static read(filename, index=1)¶: Convenience method for the preferred call to StructureReader.read()

property 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)

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

retype()¶: 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.

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.

setXYZ(xyz)¶: Set all xyz coordinates for the molecule from a numpy array.

property title¶: Get the title for this structure

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

writeToString(format)¶: Write the structure to a string representation and return the string. The format parameter is required.

hasFepio()¶

copy()¶: Returns a copy of the structure.

write(filename, format=None)¶: Write the cms 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. Only cms format is supported as of know, if other types are choosen, basic CT information would be written, which is taken care by the parent class.

append(filename, format=None)¶: Append the structure to the file. Format is determined from the file suffix if None is specified, otherwise an explicit value of maestro, sd, pdb, or smiles can be used. Only cms format is supported as of know, if other types are choosen, basic CT information would be written, which is taken care by the parent class.

class schrodinger.application.desmond.ffiostructure.CMSReader(filename, index=1, error_handler=None, input_string=None)¶

Bases: schrodinger.structure._io.MaestroReader

A class for reading structures from a CMS format file.

__init__(filename, index=1, error_handler=None, input_string=None)¶

Initialize the reader.

Parameters

filename (string) – The filename to read.
index (int) – The index of the first structure to read.
error_handler (int) – The handle of the mmerr object to use for error logging. Defaults to schrodinger.infra.mm.error_handler.
input_string (string) – A string with the contents of a Maestro format file. If provided, the filename argument is ignored.

close()¶: Close the file.

getErrorHandler()¶: Returns the error handler that is in use by m2io.

read(position=None)¶

Return the next Structure object. If position is given, this will be honoured. Otherwise the current position is taken. This raise an exception for zero size file, reading structure beyond end of file indicator and m2io errors.

Raises

EOFError – on EOF or zero size file.
Exception – otherwise.

read_mode = 16¶

seek(position)¶: Set the file position to the given position. This raise an exception for zero size file.

schrodinger.application.desmond.ffiostructure.write_cms(ct, filename, mode=2)¶: Write a CT to a Maestro format file.

schrodinger.application.desmond.ffiostructure.write_cms_to_string(ct)¶: Write a CT to a string.

schrodinger.application.desmond.ffiostructure.merge_ct(ct0, ct1)¶: Returns a new ct which is the result of merging ct0 and ct1.

schrodinger.application.desmond.ffiostructure.convert_ffioff_to_dummy(ffio_ct: schrodinger.application.desmond.ffiostructure.FFIOStructure)¶: Remove all terms from ffio_ff block, and rename FF name to ‘NONE’