Class Base_struct_API

The structural object base class.

All API methods are prototyped here as stub methods.

Instance Methods

__init__(self)
Initialise the structural object.

add_atom(self, mol_name=None, atom_name=None, res_name=None, res_num=None, pos=[None, None, None], element=None, atom_num=None, chain_id=None, segment_id=None, pdb_record=None)
Add a new atom to the structural data object.

ModelContainer instance add_model(self, model=None, coords_from=None)
Add a new model to the store.

add_molecule(self, name=None)
Prototype method stub for adding the given molecule to the store.

tuple consisting of optional molecule name (str), residue number (int), residue name (str), atom number (int), atom name(str), element name (str), and atomic position (array of len 3). atom_loop(self, atom_id=None, str_id=None, model_num=None, model_num_flag=False, mol_name_flag=False, res_num_flag=False, res_name_flag=False, atom_num_flag=False, atom_name_flag=False, element_flag=False, pos_flag=False, ave=False)
Prototype generator method stub for looping over all atoms in the structural data object.

tuple consisting of the atom number (int), atom name (str), element name (str), and atomic positions for each model (list of numpy arrays) attached_atom(self, atom_id=None, attached_atom=None, model=None)
Prototype method stub for finding the atom 'attached_atom' bonded to the atom 'atom_id'.

list of numpy arrays bond_vectors(self, attached_atom=None, model_num=None, mol_name=None, res_num=None, res_name=None, spin_num=None, spin_name=None, return_name=False, return_warnings=False)
Prototype method stub for finding the bond vectors between 'attached_atom' and 'atom_id'.

connect_atom(self, mol_name=None, index1=None, index2=None)
Connect two atoms in the structural data object.

delete(self)
Prototype method stub for deleting all structural data from the current data pipe.

bool empty(self)
Report if the structural data structure is empty or not.

from_xml(self, str_node, dir=None, id=None)
Recreate the structural object from the XML structural object node.

ModelContainer instance get_model(self, model)
Return or create the model.

MolContainer instance or None get_molecule(self, molecule, model=None)
Return the molecule.

bool load_pdb(self, file_path, read_mol=None, set_mol_name=None, read_model=None, set_model_num=None, verbosity=False)
Prototype method stub for loading structures from a PDB file.

bool load_xyz(self, file_path, read_mol=None, set_mol_name=None, read_model=None, set_model_num=None, verbosity=False)
Method for loading structures from a XYZ file.

ModelContainer container model_loop(self, model=None)
Generator method for looping over the models in numerical order.

int num_models(self)
Method for returning the number of models.

int num_molecules(self)
Method for returning the number of molecules.

pack_structs(self, data_matrix, orig_model_num=None, set_model_num=None, orig_mol_num=None, set_mol_name=None, file_name=None, file_path=None)
From the given structural data, expand the structural data data structure.

rotate(self, R=None, origin=None, model=None, atom_id=None)
Method stub for rotating a structure.

target_mol_name(self, set=None, target=None, index=None, mol_num=None, file=None)
Add the new molecule name to the target data structure.

translate(self, T=None, model=None, atom_id=None)
Method stub for displacing the structural information by the given translation vector.

to_xml(self, doc, element)
Prototype method for converting the structural object to an XML representation.

validate_models(self)
Check that the models are consistent with each other.

write_pdb(self, file, model_num=None)
Prototype method stub for the creation of a PDB file from the structural data.

validate(self)
Check the integrity of the structural data.

Class Variables

id = 'API'

Method Details

add_atom(self, mol_name=None, atom_name=None, res_name=None, res_num=None, pos=[None, None, None], element=None, atom_num=None, chain_id=None, segment_id=None, pdb_record=None)

Add a new atom to the structural data object.

Parameters:

• mol_name (str) - The name of the molecule.
• atom_name (str or None) - The atom name, e.g. 'H1'.
• res_name (str or None) - The residue name.
• res_num (int or None) - The residue number.
• pos (list (length = 3)) - The position vector of coordinates.
• element (str or None) - The element symbol.
• atom_num (int or None) - The atom number.
• chain_id (str or None) - The chain identifier.
• segment_id (str or None) - The segment identifier.
• pdb_record (str or None) - The optional PDB record name, e.g. 'ATOM' or 'HETATM'.

add_model(self, model=None, coords_from=None)

Add a new model to the store.

The new model will be constructured with the structural information from the other models currently present. The coords_from argument allows the atomic positions to be taken from a certain model. If this argument is not set, then the atomic positions from the first model will be used.

Parameters:

• model (int or None) - The number of the model to create.
• coords_from (int or None) - The model number to take the coordinates from.

Returns: ModelContainer instance

The model container.

add_molecule(self, name=None)

Prototype method stub for adding the given molecule to the store.

Parameters:

• name (str) - The molecule identification string.

atom_loop(self, atom_id=None, str_id=None, model_num=None, model_num_flag=False, mol_name_flag=False, res_num_flag=False, res_name_flag=False, atom_num_flag=False, atom_name_flag=False, element_flag=False, pos_flag=False, ave=False)

Prototype generator method stub for looping over all atoms in the structural data object.

This method should be designed as a generator (http://www.python.org/dev/peps/pep-0255/). It should loop over all atoms of the system yielding the following atomic information, if the corresponding flag is True, in tuple form:

1. Model number.
2. Molecule name.
3. Residue number.
4. Residue name.
5. Atom number.
6. Atom name.
7. The element name (its atomic symbol and optionally the isotope, e.g. 'N', 'Mg', '17O', '13C', etc).
8. The position of the atom in Euclidean space.

Parameters:

• atom_id (str) - The molecule, residue, and atom identifier string. Only atoms matching this selection will be yielded.
• str_id (str, int, or None) - The structure identifier. This can be the file name, model number, or structure number. If None, then all structures will be looped over.
• model_num (int or None) - Only loop over a specific model.
• model_num_flag (bool) - A flag which if True will cause the model number to be yielded.
• mol_name_flag (bool) - A flag which if True will cause the molecule name to be yielded.
• res_num_flag (bool) - A flag which if True will cause the residue number to be yielded.
• res_name_flag (bool) - A flag which if True will cause the residue name to be yielded.
• atom_num_flag (bool) - A flag which if True will cause the atom number to be yielded.
• atom_name_flag (bool) - A flag which if True will cause the atom name to be yielded.
• element_flag (bool) - A flag which if True will cause the element name to be yielded.
• pos_flag (bool) - A flag which if True will cause the atomic position to be yielded.
• ave (bool) - A flag which if True will result in this method returning the average atom properties across all loaded structures.

Returns: tuple consisting of optional molecule name (str), residue number (int), residue name (str), atom number (int), atom name(str), element name (str), and atomic position (array of len 3).

A tuple of atomic information, as described in the docstring.

attached_atom(self, atom_id=None, attached_atom=None, model=None)

Prototype method stub for finding the atom 'attached_atom' bonded to the atom 'atom_id'.

Parameters:

• atom_id (str) - The molecule, residue, and atom identifier string. This must correspond to a single atom in the system.
• attached_atom (str) - The name of the attached atom to return.
• model (None or int) - The model to return the positional information from. If not supplied and multiple models exist, then the returned atomic position will be a list of the positions in each model.

Returns: tuple consisting of the atom number (int), atom name (str), element name (str), and atomic positions for each model (list of numpy arrays)

A tuple of information about the bonded atom.

bond_vectors(self, attached_atom=None, model_num=None, mol_name=None, res_num=None, res_name=None, spin_num=None, spin_name=None, return_name=False, return_warnings=False)

Prototype method stub for finding the bond vectors between 'attached_atom' and 'atom_id'.

Parameters:

• attached_atom (str) - The name of the bonded atom.
• model_num (None or int) - The model of which to return the vectors from. If not supplied and multiple models exist, then vectors from all models will be returned.
• mol_name (str) - The name of the molecule that attached_atom belongs to.
• res_num (str) - The number of the residue that attached_atom belongs to.
• res_name (str) - The name of the residue that attached_atom belongs to.
• spin_num (str) - The number of the spin that attached_atom is attached to.
• spin_name (str) - The name of the spin that attached_atom is attached to.
• return_name (bool) - A flag which if True will cause the name of the attached atom to be returned together with the bond vectors.
• return_warnings (bool) - A flag which if True will cause warning messages to be returned.

Returns: list of numpy arrays

The list of bond vectors for each model.

connect_atom(self, mol_name=None, index1=None, index2=None)

Connect two atoms in the structural data object.

Parameters:

• mol_name (str) - The name of the molecule.
• index1 (str) - The global index of the first atom.
• index2 (str) - The global index of the first atom.

empty(self)

Report if the structural data structure is empty or not.

Returns: bool

True if empty, False otherwise.

from_xml(self, str_node, dir=None, id=None)

Recreate the structural object from the XML structural object node.

Parameters:

• str_node (xml.dom.minicompat.Element instance) - The structural object XML node.
• dir (str) - The name of the directory containing the results file.
• id (str) - The specific structural object ID string. This can be 'scientific', 'internal', etc.

get_model(self, model)

Return or create the model.

Parameters:

• model (int or None) - The model number.

Returns: ModelContainer instance

The ModelContainer corresponding to the model number or that newly created.

get_molecule(self, molecule, model=None)

Return the molecule.

Parameters:

• molecule (int or None) - The molecule name.
• model (int or None) - The model number.

Returns: MolContainer instance or None

The MolContainer corresponding to the molecule name and model number.

load_pdb(self, file_path, read_mol=None, set_mol_name=None, read_model=None, set_model_num=None, verbosity=False)

Prototype method stub for loading structures from a PDB file.

This inherited prototype method is a stub which, if the functionality is desired, should be overwritten by the derived class.

Parameters:

• file_path (str) - The full path of the PDB file.
• read_mol (None, int, or list of int) - The molecule(s) to read from the file, independent of model. The molecules are determined differently by the different parsers, but are numbered consecutively from 1. If set to None, then all molecules will be loaded.
• set_mol_name (None, str, or list of str) - Set the names of the molecules which are loaded. If set to None, then the molecules will be automatically labelled based on the file name or other information.
• read_model (None, int, or list of int) - The PDB model to extract from the file. If set to None, then all models will be loaded.
• set_model_num (None, int, or list of int) - Set the model number of the loaded molecule. If set to None, then the PDB model numbers will be preserved, if they exist.
• verbosity (bool) - A flag which if True will cause messages to be printed.

Returns: bool

The status of the loading of the PDB file.

load_xyz(self, file_path, read_mol=None, set_mol_name=None, read_model=None, set_model_num=None, verbosity=False)

Method for loading structures from a XYZ file.

Parameters:

• file_path (str) - The full path of the XYZ file.
• read_mol (None, int, or list of int) - The molecule(s) to read from the file, independent of model. The molecules are determined differently by the different parsers, but are numbered consecutively from 1. If set to None, then all molecules will be loaded.
• set_mol_name (None, str, or list of str) - Set the names of the molecules which are loaded. If set to None, then the molecules will be automatically labelled based on the file name or other information.
• read_model (None, int, or list of int) - The XYZ model to extract from the file. If set to None, then all models will be loaded.
• set_model_num (None, int, or list of int) - Set the model number of the loaded molecule. If set to None, then the XYZ model numbers will be preserved, if they exist.
• verbosity (bool) - A flag which if True will cause messages to be printed.

Returns: bool

The status of the loading of the XYZ file.

model_loop(self, model=None)

Generator method for looping over the models in numerical order.

Parameters:

• model (int) - Limit the loop to a single number.

Returns: ModelContainer container

The model structural object.

num_models(self)

Method for returning the number of models.

Returns: int

The number of models in the structural object.

num_molecules(self)

Method for returning the number of molecules.

Returns: int

The number of molecules in the structural object.

pack_structs(self, data_matrix, orig_model_num=None, set_model_num=None, orig_mol_num=None, set_mol_name=None, file_name=None, file_path=None)

From the given structural data, expand the structural data data structure.

Parameters:

• data_matrix (list of lists of structural objects) - A matrix of structural objects.
• orig_model_num (list of int) - The original model numbers (for storage).
• set_model_num (list of int) - The new model numbers (for model renumbering).
• orig_mol_num (list of int) - The original molecule numbers (for storage).
• set_mol_name (list of str) - The new molecule names.
• file_name (None or str) - The name of the file from which the molecular data has been extracted.
• file_path (None or str) - The full path to the file specified by 'file_name'.

rotate(self, R=None, origin=None, model=None, atom_id=None)

Method stub for rotating a structure.

Parameters:

• R (numpy 3D, rank-2 array) - The forwards rotation matrix.
• origin (numpy 3D, rank-1 array) - The origin of the rotation.
• model (int) - The model to rotate. If None, all models will be rotated.
• atom_id (str or None) - The molecule, residue, and atom identifier string. Only atoms matching this selection will be used.

target_mol_name(self, set=None, target=None, index=None, mol_num=None, file=None)

Add the new molecule name to the target data structure.

Parameters:

• set (None or list of str) - The list of new molecule names. If not supplied, the names will be generated from the file name.
• target (list) - The target molecule name data structure to which the new name will be appended.
• index (int) - The molecule index, matching the set argument.
• mol_num (int) - The molecule number.
• file (str) - The name of the file, excluding all directories.

translate(self, T=None, model=None, atom_id=None)

Method stub for displacing the structural information by the given translation vector.

Parameters:

• T (numpy 3D, rank-1 array) - The translation vector.
• model (int) - The model to rotate. If None, all models will be rotated.
• atom_id (str or None) - The molecule, residue, and atom identifier string. Only atoms matching this selection will be used.

to_xml(self, doc, element)

Prototype method for converting the structural object to an XML representation.

Parameters:

• doc (xml.dom.minidom.Document instance) - The XML document object.
• element (XML element object) - The element to add the alignment tensors XML element to.

validate_models(self)

Check that the models are consistent with each other.

This checks that the primary structure is identical between the models.

write_pdb(self, file, model_num=None)

Prototype method stub for the creation of a PDB file from the structural data.

The PDB records

The following information about the PDB records has been taken from the "Protein Data Bank Contents Guide: Atomic Coordinate Entry Format Description" version 3.1, February 11, 2008.

HET record

The HET record describes non-standard residues. The format of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "HET   "     |                                                |
|  8 - 10 | LString(3)   | hetID        | Het identifier, right-justified.               |
| 13      | Character    | ChainID      | Chain identifier.                              |
| 14 - 17 | Integer      | seqNum       | Sequence number.                               |
| 18      | AChar        | iCode        | Insertion code.                                |
| 21 - 25 | Integer      | numHetAtoms  | Number of HETATM records for the group present |
|         |              |              | in the entry.                                  |
| 31 - 70 | String       | text         | Text describing Het group.                     |
|_________|______________|______________|________________________________________________|

HETNAM record

The HETNAM associates a chemical name with the hetID from the HET record. The format is of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "HETNAM"     |                                                |
|  9 - 10 | Continuation | continuation | Allows concatenation of multiple records.      |
| 12 - 14 | LString(3)   | hetID        | Het identifier, right-justified.               |
| 16 - 70 | String       | text         | Chemical name.                                 |
|_________|______________|______________|________________________________________________|

FORMUL record

The chemical formula for non-standard groups. The format of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "FORMUL"     |                                                |
|  9 - 10 | Integer      | compNum      | Component number.                              |
| 13 - 15 | LString(3)   | hetID        | Het identifier.                                |
| 17 - 18 | Integer      | continuation | Continuation number.                           |
| 19      | Character    | asterisk     | "*" for water.                                 |
| 20 - 70 | String       | text         | Chemical formula.                              |
|_________|______________|______________|________________________________________________|

MODEL record

The model number, for multiple structures. The format of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "MODEL "     |                                                |
| 11 - 14 | Integer      | serial       | Model serial number.                           |
|_________|______________|______________|________________________________________________|

ATOM record

The ATOM record contains the atomic coordinates for atoms belonging to standard residues. The format of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "ATOM"       |                                                |
|  7 - 11 | Integer      | serial       | Atom serial number.                            |
| 13 - 16 | Atom         | name         | Atom name.                                     |
| 17      | Character    | altLoc       | Alternate location indicator.                  |
| 18 - 20 | Residue name | resName      | Residue name.                                  |
| 22      | Character    | chainID      | Chain identifier.                              |
| 23 - 26 | Integer      | resSeq       | Residue sequence number.                       |
| 27      | AChar        | iCode        | Code for insertion of residues.                |
| 31 - 38 | Real(8.3)    | x            | Orthogonal coordinates for X in Angstroms.     |
| 39 - 46 | Real(8.3)    | y            | Orthogonal coordinates for Y in Angstroms.     |
| 47 - 54 | Real(8.3)    | z            | Orthogonal coordinates for Z in Angstroms.     |
| 55 - 60 | Real(6.2)    | occupancy    | Occupancy.                                     |
| 61 - 66 | Real(6.2)    | tempFactor   | Temperature factor.                            |
| 73 - 76 | LString(4)   | segID        | Segment identifier, left-justified.            |
| 77 - 78 | LString(2)   | element      | Element symbol, right-justified.               |
| 79 - 80 | LString(2)   | charge       | Charge on the atom.                            |
|_________|______________|______________|________________________________________________|

HETATM record

The HETATM record contains the atomic coordinates for atoms belonging to non-standard groups. The format of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "HETATM"     |                                                |
|  7 - 11 | Integer      | serial       | Atom serial number.                            |
| 13 - 16 | Atom         | name         | Atom name.                                     |
| 17      | Character    | altLoc       | Alternate location indicator.                  |
| 18 - 20 | Residue name | resName      | Residue name.                                  |
| 22      | Character    | chainID      | Chain identifier.                              |
| 23 - 26 | Integer      | resSeq       | Residue sequence number.                       |
| 27      | AChar        | iCode        | Code for insertion of residues.                |
| 31 - 38 | Real(8.3)    | x            | Orthogonal coordinates for X.                  |
| 39 - 46 | Real(8.3)    | y            | Orthogonal coordinates for Y.                  |
| 47 - 54 | Real(8.3)    | z            | Orthogonal coordinates for Z.                  |
| 55 - 60 | Real(6.2)    | occupancy    | Occupancy.                                     |
| 61 - 66 | Real(6.2)    | tempFactor   | Temperature factor.                            |
| 73 - 76 | LString(4)   | segID        | Segment identifier; left-justified.            |
| 77 - 78 | LString(2)   | element      | Element symbol; right-justified.               |
| 79 - 80 | LString(2)   | charge       | Charge on the atom.                            |
|_________|______________|______________|________________________________________________|

TER record

The end of the ATOM and HETATM records for a chain. According to the draft atomic coordinate entry format description:

"The TER record has the same residue name, chain identifier, sequence number and insertion code as the terminal residue. The serial number of the TER record is one number greater than the serial number of the ATOM/HETATM preceding the TER."

The format of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "TER   "     |                                                |
|  7 - 11 | Integer      | serial       | Serial number.                                 |
| 18 - 20 | Residue name | resName      | Residue name.                                  |
| 22      | Character    | chainID      | Chain identifier.                              |
| 23 - 26 | Integer      | resSeq       | Residue sequence number.                       |
| 27      | AChar        | iCode        | Insertion code.                                |
|_________|______________|______________|________________________________________________|

CONECT record

The connectivity between atoms. This is required for all HET groups and for non-standard bonds. The format of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "CONECT"     |                                                |
|  7 - 11 | Integer      | serial       | Atom serial number                             |
| 12 - 16 | Integer      | serial       | Serial number of bonded atom                   |
| 17 - 21 | Integer      | serial       | Serial number of bonded atom                   |
| 22 - 26 | Integer      | serial       | Serial number of bonded atom                   |
| 27 - 31 | Integer      | serial       | Serial number of bonded atom                   |
| 32 - 36 | Integer      | serial       | Serial number of hydrogen bonded atom          |
| 37 - 41 | Integer      | serial       | Serial number of hydrogen bonded atom          |
| 42 - 46 | Integer      | serial       | Serial number of salt bridged atom             |
| 47 - 51 | Integer      | serial       | Serial number of hydrogen bonded atom          |
| 52 - 56 | Integer      | serial       | Serial number of hydrogen bonded atom          |
| 57 - 61 | Integer      | serial       | Serial number of salt bridged atom             |
|_________|______________|______________|________________________________________________|

ENDMDL record

The end of model record, for multiple structures. The format of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "ENDMDL"     |                                                |
|_________|______________|______________|________________________________________________|

MASTER record

The control record for bookkeeping. The format of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "MASTER"     |                                                |
| 11 - 15 | Integer      | numRemark    | Number of REMARK records                       |
| 16 - 20 | Integer      | "0"          |                                                |
| 21 - 25 | Integer      | numHet       | Number of HET records                          |
| 26 - 30 | Integer      | numHelix     | Number of HELIX records                        |
| 31 - 35 | Integer      | numSheet     | Number of SHEET records                        |
| 36 - 40 | Integer      | numTurn      | Number of TURN records                         |
| 41 - 45 | Integer      | numSite      | Number of SITE records                         |
| 46 - 50 | Integer      | numXform     | Number of coordinate transformation records    |
|         |              |              | (ORIGX+SCALE+MTRIX)                            |
| 51 - 55 | Integer      | numCoord     | Number of atomic coordinate records            |
|         |              |              | (ATOM+HETATM)                                  |
| 56 - 60 | Integer      | numTer       | Number of TER records                          |
| 61 - 65 | Integer      | numConect    | Number of CONECT records                       |
| 66 - 70 | Integer      | numSeq       | Number of SEQRES records                       |
|_________|______________|______________|________________________________________________|

END record

The end of the PDB file. The format of the record is:

__________________________________________________________________________________________
|         |              |              |                                                |
| Columns | Data type    | Field        | Definition                                     |
|_________|______________|______________|________________________________________________|
|         |              |              |                                                |
|  1 -  6 | Record name  | "END   "     |                                                |
|_________|______________|______________|________________________________________________|

Parameters:

• file (file object) - The PDB file object. This object must be writable.
• model_num (None or int) - The model to place into the PDB file. If not supplied, then all models will be placed into the file.

validate(self)

Check the integrity of the structural data.

The number of molecules must be the same in all models.