Class Internal

The internal relax structural data object.

The structural data object for this class is a container possessing a number of different arrays corresponding to different structural information. These objects are described in the structural container docstring.

Instance Methods

__init__(self)
Initialise the structural object.

tuple consisting of the atom number (int), atom name (str), element name (str), and atomic position (Numeric array of len 3) _bonded_atom(self, attached_atom, index, mol)
Find the atom named attached_atom directly bonded to the atom located at the index.

_find_bonded_atoms(self, index, mol, radius=1.2)
Find all atoms within a sphere and say that they are attached to the central atom.

str or None _get_chemical_name(self, hetID)
Return the chemical name corresponding to the given residue ID.

tuple of int and array of str _parse_models_gaussian(self, file_path, verbosity=1)
Generator function for looping over the models in the Gaussian log file.

list of str _parse_pdb_connectivity_annotation(self, lines)
Loop over and parse the PDB connectivity annotation records.

tuple of int and array of str _parse_pdb_coord(self, lines)
Generator function for looping over the models in the PDB file.

list of str _parse_pdb_hetrogen(self, lines)
Loop over and parse the PDB hetrogen records.

list of str _parse_pdb_misc(self, lines)
Loop over and parse the PDB miscellaneous records.

list of str _parse_pdb_prim_struct(self, lines)
Loop over and parse the PDB primary structure records.

list of str _parse_pdb_ss(self, lines, read_mol=None, helices=None, sheets=None)
Loop over and parse the PDB secondary structure records.

list of str _parse_pdb_title(self, lines)
Loop over and parse the PDB title records.

list of str _parse_pdb_transform(self, lines)
Loop over and parse the PDB transform records.

tuple of int and array of str _parse_models_xyz(self, file_path, verbosity=1)
Generator function for looping over the models in the XYZ file.

tuple of int and list of str _parse_mols_pdb(self, records)
Generator function for looping over the molecules in the PDB records of a model.

int _pdb_chain_id_to_mol_index(self, chain_id=None)
Convert the PDB chain ID into the molecule index in a regular way.

dict of str _residue_data(self, res_nums=None, res_names=None)
Convert the residue info into a dictionary of unique residues with numbers as keys.

_validate_data_arrays(self, struct)
Check the validity of the data arrays in the given structure object.

list of str _validate_records(self, lines)
Make sure all PDB records are 80 char in length, padding with whitespace when needed.

_mol_type(self, mol)
Determine the type of molecule.

_protein_connect(self, mol)
Set up the connectivities for the protein.

_protein_intra_connect(self, mol, res_atoms)
Set up the connectivities for the protein.

str _translate(self, data, format='str')
Convert the data into a format for writing to file.

list or None _trim_helix(self, helix=None, trim_res_list=[], res_data=None)
Trim the given helix based on the list of deleted residue numbers.

list or None _trim_sheet(self, sheet=None, trim_res_list=[], res_data=None)
Trim the given sheet based on the list of deleted residue numbers.

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, sort=False)
Add a new atom to the structural data object.

add_coordinates(self, coord=None, mol_names=None, res_names=None, res_nums=None, atom_names=None, elements=None, set_mol_name=None, set_model_num=None)
Add a set of coordinates to the structural object.

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

add_molecule(self, model_num=None, name=None)
Add a new molecule to the store.

bool are_bonded(self, atom_id1=None, atom_id2=None)
Determine if two atoms are directly bonded to each other.

bool are_bonded_index(self, mol_index1=None, atom_index1=None, mol_index2=None, atom_index2=None)
Determine if two atoms, given as indices, are directly bonded to each other.

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, selection=None, str_id=None, model_num=None, 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, mol_index_flag=False, index_flag=False, ave=False)
Generator function for looping over all atoms in the internal relax structural object.

list of numpy arrays (or a tuple if return_name or return_warnings are set) 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)
Find the bond vector between the atoms of 'attached_atom' and 'atom_id'.

collapse_ensemble(self, model_num=None, model_to=1)
Collapse the ensemble into a single model.

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

delete(self, model=None, selection=None, verbosity=1)
Deletion of structural information.

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

from_xml(self, str_node, dir=None, file_version=1)
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 has_molecule(self, model_num=None, name=None)
Check if the molecule name exists.

bool load_gaussian(self, file_path, set_mol_name=None, set_model_num=None, verbosity=False)
Method for loading structures from a Gaussian log file.

bool load_pdb(self, file_path, read_mol=None, set_mol_name=None, read_model=None, set_model_num=None, alt_loc=None, verbosity=False, merge=False)
Method 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.

mean(self)
Calculate the mean structure from all models in the structural data object.

list of int model_list(self)
Create a list of all models.

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.

str one_letter_codes(self, mol_name=None, selection=None)
Generate and return the one letter code sequence for the given molecule.

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, file_path_abs=None, helices=None, sheets=None, verbosity=1, merge=False)
From the given structural data, expand the structural data data structure.

rotate(self, R=None, origin=None, model=None, selection=None)
Rotate the structural information about the given origin.

Internal_selection instance selection(self, atom_id=None, inv=False)
Convert the atom ID string into a special internal selection object for speed.

set_model(self, model_orig=None, model_new=None)
Set or reset the model number.

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, selection=None)
Displace 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, verbosity=1)
Check that the models are consistent with each other.

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

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

Method Details

_bonded_atom(self, attached_atom, index, mol)

Find the atom named attached_atom directly bonded to the atom located at the index.

Parameters:

• attached_atom (str) - The name of the attached atom to return.
• index (int) - The index of the atom which the attached atom is attached to.
• mol (MolContainer instance) - The molecule container.

Returns: tuple consisting of the atom number (int), atom name (str), element name (str), and atomic position (Numeric array of len 3)

A tuple of information about the bonded atom.

_find_bonded_atoms(self, index, mol, radius=1.2)

Find all atoms within a sphere and say that they are attached to the central atom.

The found atoms will be added to the 'bonded' data structure.

Parameters:

• index (int) - The index of the central atom.
• mol (MolContainer instance) - The molecule container.

_get_chemical_name(self, hetID)

Return the chemical name corresponding to the given residue ID.

The following names are currently returned:

________________________________________________
|        |                                     |
| hetID  | Chemical name                       |
|________|_____________________________________|
|        |                                     |
| TNS    | Tensor                              |
| COM    | Centre of mass                      |
| AXS    | Tensor axes                         |
| SIM    | Monte Carlo simulation tensor axes  |
| PIV    | Pivot point                         |
| CON    | Cone object                         |
| AVE    | Average vector                      |
|________|_____________________________________|

For any other residues, no description is returned.

Parameters:

• hetID (str) - The residue ID.

Returns: str or None

The chemical name.

_parse_models_gaussian(self, file_path, verbosity=1)

Generator function for looping over the models in the Gaussian log file.

Parameters:

• file_path (str) - The full path of the Gaussian log file.
• verbosity (int) - The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.

Returns: tuple of int and array of str

The model number and all the records for that model.

_parse_pdb_connectivity_annotation(self, lines)

Loop over and parse the PDB connectivity annotation records.

These are the records identified in the PDB version 3.30 documentation.

Parameters:

• lines (list of str) - The lines of the PDB file excluding the sections prior to the connectivity annotation section.

Returns: list of str

The remaining PDB lines with the connectivity annotation records stripped.

_parse_pdb_coord(self, lines)

Generator function for looping over the models in the PDB file.

These are the records identified in the PDB version 3.30 documentation at http://www.wwpdb.org/documentation/file-format/format33/sect9.html.

Parameters:

• lines (list of str) - The lines of the coordinate section.

Returns: tuple of int and array of str

The model number and all the records for that model.

_parse_pdb_hetrogen(self, lines)

Loop over and parse the PDB hetrogen records.

These are the records identified in the PDB version 3.30 documentation at http://www.wwpdb.org/documentation/file-format/format33/sect4.html.

Parameters:

• lines (list of str) - The lines of the PDB file excluding the sections prior to the hetrogen section.

Returns: list of str

The remaining PDB lines with the hetrogen records stripped.

_parse_pdb_misc(self, lines)

Loop over and parse the PDB miscellaneous records.

These are the records identified in the PDB version 3.30 documentation at http://www.wwpdb.org/documentation/file-format/format33/sect7.html.

Parameters:

• lines (list of str) - The lines of the PDB file excluding the sections prior to the miscellaneous section.

Returns: list of str

The remaining PDB lines with the miscellaneous records stripped.

_parse_pdb_prim_struct(self, lines)

Loop over and parse the PDB primary structure records.

These are the records identified in the PDB version 3.30 documentation at http://www.wwpdb.org/documentation/file-format/format33/sect3.html.

Parameters:

• lines (list of str) - The lines of the PDB file excluding the title section.

Returns: list of str

The remaining PDB lines with the primary structure records stripped.

_parse_pdb_ss(self, lines, read_mol=None, helices=None, sheets=None)

Loop over and parse the PDB secondary structure records.

These are the records identified in the PDB version 3.30 documentation at http://www.wwpdb.org/documentation/file-format/format33/sect5.html.

Parameters:

• lines (list of str) - The lines of the PDB file excluding the sections prior to the secondary structure section.
• 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.
• helices (list) - The list of helix data to append to.
• sheets (list) - The list of sheet data to append to.

Returns: list of str

The remaining PDB lines with the secondary structure records stripped.

_parse_pdb_title(self, lines)

Loop over and parse the PDB title records.

These are the records identified in the PDB version 3.30 documentation at http://www.wwpdb.org/documentation/file-format/format33/sect2.html.

Parameters:

• lines (list of str) - All lines of the PDB file.

Returns: list of str

The remaining PDB lines with the title records stripped.

_parse_pdb_transform(self, lines)

Loop over and parse the PDB transform records.

These are the records identified in the PDB version 3.30 documentation at http://www.wwpdb.org/documentation/file-format/format33/sect8.html.

Parameters:

• lines (list of str) - The lines of the PDB file excluding the sections prior to the transform section.

Returns: list of str

The remaining PDB lines with the transform records stripped.

_parse_models_xyz(self, file_path, verbosity=1)

Generator function for looping over the models in the XYZ file.

Parameters:

• file_path (str) - The full path of the XYZ file.
• verbosity (int) - The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.

Returns: tuple of int and array of str

The model number and all the records for that model.

_parse_mols_pdb(self, records)

Generator function for looping over the molecules in the PDB records of a model.

Parameters:

• records (list of str) - The list of PDB records for the model, or if no models exist the entire PDB file.

Returns: tuple of int and list of str

The molecule number and all the records for that molecule.

_pdb_chain_id_to_mol_index(self, chain_id=None)

Convert the PDB chain ID into the molecule index in a regular way.

Parameters:

• chain_id (str) - The PDB chain ID string.

Returns: int

The corresponding molecule index.

_residue_data(self, res_nums=None, res_names=None)

Convert the residue info into a dictionary of unique residues with numbers as keys.

Parameters:

• res_nums (list of int) - The list of residue numbers.
• res_names (list of str) - The list of residue names matching the numbers.

Returns: dict of str

The dictionary of residue names with residue numbers as keys.

_validate_data_arrays(self, struct)

Check the validity of the data arrays in the given structure object.

Parameters:

• struct (Structure_container instance) - The structural object.

_validate_records(self, lines)

Make sure all PDB records are 80 char in length, padding with whitespace when needed.

All newline characters are stripped from the records as well.

Parameters:

• lines (list of str) - All lines of the PDB file.

Returns: list of str

The padded PDB lines.

_mol_type(self, mol)

Determine the type of molecule.

Parameters:

• mol (MolContainer instance) - The molecule data container.

_protein_connect(self, mol)

Set up the connectivities for the protein.

Parameters:

• mol (MolContainer instance) - The molecule data container.

_protein_intra_connect(self, mol, res_atoms)

Set up the connectivities for the protein.

Parameters:

• mol (MolContainer instance) - The molecule data container.
• res_atoms (list of int) - The list of atom indices corresponding to the residue.

_translate(self, data, format='str')

Convert the data into a format for writing to file.

Parameters:

• data (anything) - The data to convert to the required format.
• format (str) - The format to convert to. This can be 'str', 'float', or 'int'.

Returns: str

The converted version of the data.

_trim_helix(self, helix=None, trim_res_list=[], res_data=None)

Trim the given helix based on the list of deleted residue numbers.

Parameters:

• helix (list) - The single helix metadata structure.
• trim_res_list (list of int) - The list of residue numbers which no longer exist.
• res_data (dict of str) - The dictionary of residue names with residue numbers as keys.

Returns: list or None

The trimmed helix metadata structure, or None if the whole helix is to be deleted.

_trim_sheet(self, sheet=None, trim_res_list=[], res_data=None)

Trim the given sheet based on the list of deleted residue numbers.

Parameters:

• sheet (list) - The single sheet metadata structure.
• trim_res_list (list of int) - The list of residue numbers which no longer exist.
• res_data (dict of str) - The dictionary of residue names with residue numbers as keys.

Returns: list or None

The trimmed sheet metadata structure, or None if the whole sheet is to be deleted.

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, sort=False)

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 (rank-1 or rank-2 array or list of float) - The position vector of coordinates. If a rank-2 array is supplied, the length of the first dimension must match the number of models.
• 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'.
• sort (bool) - A flag which if True will cause the structural data to be sorted after adding the atom.

add_coordinates(self, coord=None, mol_names=None, res_names=None, res_nums=None, atom_names=None, elements=None, set_mol_name=None, set_model_num=None)

Add a set of coordinates to the structural object.

Parameters:

• coord (numpy rank-2 float64 array) - The array of atomic coordinates (first dimension is the atoms and the second are the coordinates).
• mol_names (list of str) - The list of molecule names corresponding to the first dimension of the coordinate array.
• res_names (list of str) - The list of residue names corresponding to the first dimension of the coordinate array.
• res_nums (list of str) - The list of residue numbers corresponding to the first dimension of the coordinate array.
• atom_names (list of str) - The list of atom names corresponding to the first dimension of the coordinate array.
• elements (list of str) - The list of elements corresponding to the first dimension of the coordinate array.
• set_mol_name (None or str) - Set the names of the molecules which are loaded. If set to None, then all molecule names must be identical and the new molecule will have the same name.
• set_model_num (None or int) - Set the model number for the coordinates.

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

Add a new model to the store.

The new model will be constructed 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, model_num=None, name=None)

Add a new molecule to the store.

Parameters:

• model_num (None or int) - The optional model to add the molecule to. If not supplied, the molecule will be added to all models.
• name (str) - The molecule identifier string.

are_bonded(self, atom_id1=None, atom_id2=None)

Determine if two atoms are directly bonded to each other.

Parameters:

• atom_id1 (str) - The molecule, residue, and atom identifier string of the first atom.
• atom_id2 (str) - The molecule, residue, and atom identifier string of the second atom.

Returns: bool

True if the atoms are directly bonded.

are_bonded_index(self, mol_index1=None, atom_index1=None, mol_index2=None, atom_index2=None)

Determine if two atoms, given as indices, are directly bonded to each other.

Parameters:

• mol_index1 (int) - The molecule index of the first atom.
• atom_index1 (int) - The index of the first atom.
• mol_index2 (int) - The molecule index of the second atom.
• atom_index2 (int) - The index of the second atom.

Returns: bool

True if the atoms are directly bonded.

atom_loop(self, selection=None, str_id=None, model_num=None, 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, mol_index_flag=False, index_flag=False, ave=False)

Generator function for looping over all atoms in the internal relax structural object.

This method should be designed as a generator. 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:

• selection (lib.structure.internal.Internal_selection instance) - The internal structural selection object. This is obtained by calling the selection() method with the atom ID string.
• 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.
• 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.
• mol_index_flag (bool) - A flag which if True will cause the molecule index to be yielded.
• index_flag (bool) - A flag which if True will cause the atomic index 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.

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)

Find the bond vector between the atoms of '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 (or a tuple if return_name or return_warnings are set)

The list of bond vectors for each model.

collapse_ensemble(self, model_num=None, model_to=1)

Collapse the ensemble into a single model.

Parameters:

• model_num (int) - The number of the model to keep. All other models will be removed.
• model_to (int) - The model number for the sole remaining 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.

delete(self, model=None, selection=None, verbosity=1)

Deletion of structural information.

Parameters:

• model (None or int) - Individual structural models from a loaded ensemble can be deleted by specifying the model number.
• selection (lib.structure.internal.Internal_selection instance) - The internal structural selection object. This is obtained by calling the selection() method with the atom ID string.
• verbosity (int) - The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.

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, file_version=1)

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.
• file_version (int) - The relax XML version of the XML file.

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.

Only one model can be specified.

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.

Raises:

• RelaxError - If the model is not specified and there is more than one model loaded.

has_molecule(self, model_num=None, name=None)

Check if the molecule name exists.

Parameters:

• model_num (None or int) - The optional model to check. If not supplied, the molecule will be searched for across all models.
• name (str) - The molecule name.

Returns: bool

True if the molecule exists, False otherwise.

load_gaussian(self, file_path, set_mol_name=None, set_model_num=None, verbosity=False)

Method for loading structures from a Gaussian log file.

Parameters:

• file_path (str) - The full path of the Gaussian log file.
• 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.
• set_model_num (None, int, or list of int) - Set the model number of the loaded molecule. If set to None, then the Gaussian log 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 Gaussian log file.

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

Method for loading structures from a PDB file.

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.
• alt_loc (str or None) - The PDB ATOM record 'Alternate location indicator' field value to select which coordinates to use.
• verbosity (bool) - A flag which if True will cause messages to be printed.
• merge (bool) - A flag which if set to True will try to merge the PDB structure into the currently loaded structures.

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_list(self)

Create a list of all models.

Returns: list of int

The list of all models.

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.

one_letter_codes(self, mol_name=None, selection=None)

Generate and return the one letter code sequence for the given molecule.

Parameters:

• mol_name (str) - The name of the molecule to return the one letter codes for.
• selection (lib.structure.internal.Internal_selection instance) - The internal structural selection object. This is obtained by calling the selection() method with the atom ID string.

Returns: str

The one letter code sequence for the given molecule.

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, file_path_abs=None, helices=None, sheets=None, verbosity=1, merge=False)

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. The first dimension is the models, the second is the molecules.
• 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 list of int) - The original molecule numbers (for storage). The dimensions match the data matrix.
• 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'.
• file_path_abs (None or str) - The absolute path to the file specified by 'file_name'. This is a fallback mechanism in case results or save files are located somewhere other than the working directory.
• helices (list of lists) - The helix secondary structure information to store. The first dimension corresponds to each helix element. The second dimension consists of the helix_id, mol_init_index, init_res_name, init_seq_num, mol_end_index, end_res_name, end_seq_num, helix_class, and length.
• sheets (list of lists) - The sheet secondary structure information to store.
• verbosity (int) - The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.
• merge (bool) - A flag which if set to True will try to merge the structure into the currently loaded structures.

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

Rotate the structural information about the given origin.

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.
• selection (lib.structure.internal.Internal_selection instance) - The internal structural selection object. This is obtained by calling the selection() method with the atom ID string.

selection(self, atom_id=None, inv=False)

Convert the atom ID string into a special internal selection object for speed.

Parameters:

• atom_id (str or None) - The molecule, residue, and atom identifier string. Only atoms matching this selection will be used.
• inv (bool) - A flag which if True will cause the selection to be inverted.

Returns: Internal_selection instance

The internal structural selection object.

set_model(self, model_orig=None, model_new=None)

Set or reset the model number.

Parameters:

• model_orig (None or int) - The original model number. Leave as None if no models are currently present.
• model_new (int) - The new model number to set the model to.

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, selection=None)

Displace 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.
• selection (lib.structure.internal.Internal_selection instance) - The internal structural selection object. This is obtained by calling the selection() method with the atom ID string.

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, verbosity=1)

Check that the models are consistent with each other.

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

Parameters:

• verbosity (int) - If 0, then all printouts will be silenced.

write_pdb(self, file, model_num=None)

Method for the creation of a PDB file from the structural data.

A number of PDB records including HET, HETNAM, FORMUL, HELIX, SHEET, HETATM, TER, CONECT, MASTER, and END are created. To create the non-standard residue records HET, HETNAM, and FORMUL, the data structure 'het_data' is created. It is an array of arrays where the first dimension corresponds to a different residue and the second dimension has the elements:

0. Residue number.
1. Residue name.
2. Chain ID.
3. Total number of atoms in the residue.
4. Number of H atoms in the residue.
5. Number of C atoms in the residue.

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.