Module mol_res_spin

Module for the manipulation of the molecule-residue-spin data structures in the relax data store.

The functionality of this module is diverse:

• Documentation for the spin identification string.
• Functions for parsing or generating spin identification strings.
• The mol-res-spin selection object (derived from the Selection class).
• Generator functions for looping over molecules, residues, or spins.
• Functions for returning MoleculeContainer, ResidueContainer, and SpinContainer objects or information about these.
• Functions for copying, creating, deleting, displaying, naming, and numbering MoleculeContainer, ResidueContainer, and SpinContainer objects in the relax data store.
• Functions for counting spins or testing their existence.

Classes

Selection
An object containing mol-res-spin selections.

Functions

bool are_spins_named(spin_id=None)
Determine if any spins have been named.

bmrb_read(star)
Generate the molecule and residue spin containers from the entity saveframe records.

bmrb_write_entity(star, version=None)
Generate the entity saveframe records for the NMR-STAR dictionary object.

copy_molecule(pipe_from=None, mol_from=None, pipe_to=None, mol_to=None)
Copy the contents of a molecule container to a new molecule.

copy_residue(pipe_from=None, res_from=None, pipe_to=None, res_to=None)
Copy the contents of the residue structure from one residue to a new residue.

copy_spin(pipe_from=None, spin_from=None, pipe_to=None, spin_to=None)
Copy the contents of the spin structure from one spin to a new spin.

int count_molecules(selection=None, pipe=None)
Count the number of molecules for which there is data.

int count_residues(selection=None, pipe=None)
Count the number of residues for which there is data.

int count_spins(selection=None, pipe=None, skip_desel=True)
Function for counting the number of spins for which there is data.

MoleculeContainer instance create_molecule(mol_name=None, mol_type=None, pipe=None)
Add a molecule into the relax data store.

ResidueContainer instance create_residue(res_num=None, res_name=None, mol_name=None, pipe=None)
Add a residue into the relax data store (and molecule if necessary).

create_pseudo_spin(spin_name=None, spin_num=None, res_id=None, members=None, averaging=None, pipe=None)
Add a pseudo-atom spin container into the relax data store.

SpinContainer instance create_spin(spin_num=None, spin_name=None, res_num=None, res_name=None, mol_name=None, pipe=None)
Add a spin into the relax data store (and molecule and residue if necessary).

tuple of int convert_from_global_index(global_index=None, pipe=None)
Convert the global index into the molecule, residue, and spin indices.

delete_molecule(mol_id=None)
Function for deleting molecules from the current data pipe.

delete_residue(res_id=None)
Function for deleting residues from the current data pipe.

delete_spin(spin_id=None)
Function for deleting spins from the current data pipe.

display_molecule(mol_id=None)
Function for displaying the information associated with the molecule.

display_residue(res_id=None)
Function for displaying the information associated with the residue.

display_spin(spin_id=None)
Function for displaying the information associated with the spin.

bool exists_mol_res_spin_data(pipe=None)
Function for determining if any molecule-residue-spin data exists.

int or tuple of 3 int find_index(selection=None, pipe=None, global_index=True)
Find and return the spin index or indices for the selection string.

int first_residue_num(selection=None)
Determine the first residue number.

str generate_spin_id(pipe_cont=None, pipe_name=None, mol_name=None, res_num=None, res_name=None, spin_num=None, spin_name=None)
Generate the spin selection string.

str generate_spin_id_data_array(data=None, mol_name_col=None, res_num_col=None, res_name_col=None, spin_num_col=None, spin_name_col=None)
Generate the spin selection string from the given data array.

str generate_spin_id_unique(pipe_cont=None, pipe_name=None, mol=None, res=None, spin=None, mol_name=None, res_num=None, res_name=None, spin_num=None, spin_name=None)
Generate a list of spin ID variants for the given set of molecule, residue and spin indices.

list of str get_molecule_ids(selection=None)
Return a list of the molecule ID strings.

list of str get_molecule_names(selection=None)
Return a list of the molecule names.

list of str get_residue_ids(selection=None)
Return a list of the residue ID strings.

list of str get_residue_names(selection=None)
Return a list of the residue names.

list of str get_residue_nums(selection=None)
Return a list of the residue numbers.

list of str get_spin_ids(selection=None)
Return a list of the spin ID strings.

int or None index_molecule(mol_name=None, pipe=None)
Return the index of the molecule of the given name.

int or None index_residue(res_num=None, res_name=None, mol_index=None, pipe=None)
Return the index of the residue.

int last_residue_num(selection=None)
Determine the last residue number.

list of numpy float arrays linear_ave(positions)
Perform linear averaging of the atomic positions.

metadata_cleanup(mol_index=None, res_index=None, spin_index=None, pipe=None)
Prune all of the metadata matching the given indices.

metadata_counts(pipe_cont=None)
Update the molecule, residue, and spin name and number count metadata.

metadata_prune(mol_index=None, res_index=None, spin_index=None, pipe=None)
Prune all of the metadata matching the given indices.

metadata_update(mol_index=None, res_index=None, spin_index=None, pipe=None)
Update all of the private look up metadata for the given containers.

instance of the MoleculeContainer class. molecule_loop(selection=None, pipe=None, return_id=False)
Generator function for looping over all the molecules of the given selection.

name_molecule(mol_id, name=None, force=False)
Name the molecules.

name_residue(res_id, name=None, force=False)
Name the residues.

name_spin(spin_id=None, name=None, pipe=None, force=False)
Name the spins.

number_residue(res_id, number=None, force=False)
Number the residues.

number_spin(spin_id=None, number=None, force=False)
Number the spins.

str one_letter_code(res_names)
Convert the list of residue names into a string of one letter residue codes.

list of int and str parse_token(token, verbosity=False)
Parse the token string and return a list of identifying numbers and names.

instance of the ResidueContainer class. If full_info=True, the type is the tuple (ResidueContainer, str). residue_loop(selection=None, pipe=None, full_info=False, return_id=False)
Generator function for looping over all the residues of the given selection.

instance of the MoleculeContainer class. return_molecule(selection=None, pipe=None)
Function for returning the molecule data container of the given selection.

MoleculeContainer instance return_molecule_by_name(pipe_cont=None, pipe_name=None, mol_name=None)
Return the molecule container matching the given name.

instance of the ResidueContainer class. return_residue(selection=None, pipe=None, indices=False)
Function for returning the residue data container of the given selection.

ResidueContainer instance return_residue_by_info(mol=None, res_name=None, res_num=None)
Return the residue container matching the given name.

SpinContainer instance of list of instances or tuple of (str, int, str, SpinContainer instance or list of instances) return_spin(spin_id=None, pipe=None, full_info=False, multi=False)
Return the spin data container corresponding to the given spin ID string.

SpinContainer instance return_spin_by_info(res=None, spin_name=None, spin_num=None)
Return the spin container matching the given name.

SpinContainer instance of list of instances or tuple of (str, int, str, SpinContainer instance or list of instances) return_spin_from_selection(selection=None, pipe=None, full_info=False, multi=False)
Function for returning the spin data container of the given selection.

instance of the SpinContainer class (or tuple of SpinContainer and str) return_spin_from_index(global_index=None, pipe=None, return_spin_id=False)
Function for returning the spin data container corresponding to the global index.

list of int return_spin_indices(spin_id=None, pipe=None)
Return the molecule, residue and spin indices corresponding to the given spin ID string.

str return_single_molecule_info(molecule_token)
Return the single molecule name corresponding to the molecule token.

(int, str) return_single_residue_info(residue_token)
Return the single residue number and name corresponding to the residue token.

(int, str) return_single_spin_info(spin_token)
Return the single spin number and name corresponding to the spin token.

bool same_sequence(pipe1, pipe2)
Test if the sequence data in both pipes are the same.

set_spin_element(spin_id=None, element=None, pipe=None, force=False)
Set the element type of the spins.

set_spin_isotope(spin_id=None, isotope=None, pipe=None, force=False)
Set the nuclear isotope type of the spins.

str, int, str, int, str spin_id_to_data_list(id)
Convert the single spin ID string into a list of the mol, res, and spin names and numbers.

list of str spin_id_variants(dp=None, mol_index=None, res_index=None, spin_index=None)
Generate a list of spin ID variants for the given set of molecule, residue and spin indices.

list of str spin_id_variants_cleanup(dp=None, mol_index=None, res_index=None, spin_index=None)
Generate a list of spin ID variants to eliminate for the given set of molecule, residue and spin indices.

list of str spin_id_variants_prune(dp=None, mol_index=None, res_index=None, spin_index=None)
Generate a list of spin ID variants to eliminate for the given set of molecule, residue and spin indices.

bool spin_in_list(spin_list, mol_name_col=None, res_num_col=None, res_name_col=None, spin_num_col=None, spin_name_col=None, mol_name=None, res_num=None, res_name=None, spin_num=None, spin_name=None)
Function for determining if the spin is located within the list of spins.

tuple of 3 int spin_index_loop(selection=None, pipe=None)
Generator function for looping over all selected spins, returning the mol-res-spin indices.

If full_info and return_id are False, SpinContainer instance. If full_info is True and return_id is false, a tuple of (SpinContainer instance, str, int, str). If full_info is False and return_id is True, a tuple of (SpinContainer instance, str). If full_info and return_id are False, a tuple of (SpinContainer instance, str, int, str, str) spin_loop(selection=None, pipe=None, full_info=False, return_id=False)
Generator function for looping over all the spin systems of the given selection.

3-tuple of str or None tokenise(selection)
Split the input selection string returning the mol_token, res_token, and spin_token strings.

type_molecule(mol_id, type=None, force=False)
Set the molecule type.

Variables

status = Status()

ALLOWED_MOL_TYPES = ['protein', 'DNA', 'RNA', 'organic molecul...
The list of allowable molecule types.

id_string_doc = Desc_container("Spin ID string documentation")

__package__ = 'generic_fns'

Imports: array, float64, split, sys, fill, warn, is_unicode, MoleculeContainer, ResidueContainer, SpinContainer, exp_info, pipes, relax_re, RelaxError, RelaxNoSpinError, RelaxMultiMolIDError, RelaxMultiResIDError, RelaxMultiSpinIDError, RelaxResSelectDisallowError, RelaxSpinSelectDisallowError, RelaxWarning, Status, Desc_container

Function Details

are_spins_named(spin_id=None)

Determine if any spins have been named.

Parameters:

• spin_id (None or str) - The spin ID string.

Returns: bool

True if a spin has been named or False if no spins have been named.

bmrb_read(star)

Generate the molecule and residue spin containers from the entity saveframe records.

Parameters:

• star (NMR_STAR instance) - The NMR-STAR dictionary object.

bmrb_write_entity(star, version=None)

Generate the entity saveframe records for the NMR-STAR dictionary object.

Parameters:

• star (NMR_STAR instance) - The NMR-STAR dictionary object.
• version (str) - The BMRB NMR-STAR dictionary format to output to.

copy_molecule(pipe_from=None, mol_from=None, pipe_to=None, mol_to=None)

Copy the contents of a molecule container to a new molecule.

For copying to be successful, the mol_from identification string must match an existent molecule.

Parameters:

• pipe_from (str) - The data pipe to copy the molecule data from. This defaults to the current data pipe.
• mol_from (str) - The molecule identification string for the structure to copy the data from.
• pipe_to (str) - The data pipe to copy the molecule data to. This defaults to the current data pipe.
• mol_to (str) - The molecule identification string for the structure to copy the data to.

copy_residue(pipe_from=None, res_from=None, pipe_to=None, res_to=None)

Copy the contents of the residue structure from one residue to a new residue.

For copying to be successful, the res_from identification string must match an existent residue. The new residue number must be unique.

Parameters:

• pipe_from (str) - The data pipe to copy the residue from. This defaults to the current data pipe.
• res_from (str) - The residue identification string for the structure to copy the data from.
• pipe_to (str) - The data pipe to copy the residue to. This defaults to the current data pipe.
• res_to (str) - The residue identification string for the structure to copy the data to.

copy_spin(pipe_from=None, spin_from=None, pipe_to=None, spin_to=None)

Copy the contents of the spin structure from one spin to a new spin.

For copying to be successful, the spin_from identification string must match an existent spin. The new spin number must be unique.

Parameters:

• pipe_from (str) - The data pipe to copy the spin from. This defaults to the current data pipe.
• spin_from (str) - The spin identification string for the structure to copy the data from.
• pipe_to (str) - The data pipe to copy the spin to. This defaults to the current data pipe.
• spin_to (str) - The spin identification string for the structure to copy the data to.

count_molecules(selection=None, pipe=None)

Count the number of molecules for which there is data.

Parameters:

• selection (str) - The selection string.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.

Returns: int

The number of non-empty molecules.

count_residues(selection=None, pipe=None)

Count the number of residues for which there is data.

Parameters:

• selection (str) - The selection string.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.

Returns: int

The number of non-empty residues.

count_spins(selection=None, pipe=None, skip_desel=True)

Function for counting the number of spins for which there is data.

Parameters:

• selection (str) - The selection string.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.
• skip_desel (bool) - A flag which if true will cause deselected spins to be skipped in the count.

Returns: int

The number of non-empty spins.

create_molecule(mol_name=None, mol_type=None, pipe=None)

Add a molecule into the relax data store.

Parameters:

• mol_name (str) - The name of the molecule.
• pipe (str or None) - The data pipe to add the molecule to. Defaults to the current data pipe.
• mol_type (str) - The type of molecule.

Returns: MoleculeContainer instance

The newly created molecule.

create_residue(res_num=None, res_name=None, mol_name=None, pipe=None)

Add a residue into the relax data store (and molecule if necessary).

Parameters:

• res_num (int) - The number of the new residue.
• res_name (str) - The name of the new residue.
• mol_name (str) - The name of the molecule to add the residue to.
• pipe (str or None) - The data pipe to add the residue to. Defaults to the current data pipe.

Returns: ResidueContainer instance

The newly created residue.

create_pseudo_spin(spin_name=None, spin_num=None, res_id=None, members=None, averaging=None, pipe=None)

Add a pseudo-atom spin container into the relax data store.

Parameters:

• spin_name (str) - The name of the new pseudo-spin.
• spin_num (int) - The identification number of the new spin.
• res_id (str) - The molecule and residue identification string.
• pipe (str or None) - The data pipe to add the spin to. Defaults to the current data pipe.

create_spin(spin_num=None, spin_name=None, res_num=None, res_name=None, mol_name=None, pipe=None)

Add a spin into the relax data store (and molecule and residue if necessary).

Parameters:

• spin_num (int) - The number of the new spin.
• spin_name (str) - The name of the new spin.
• res_num (int) - The number of the residue to add the spin to.
• res_name (str) - The name of the residue to add the spin to.
• mol_name (str) - The name of the molecule to add the spin to.
• pipe (str or None) - The data pipe to add the spin to. Defaults to the current data pipe.

Returns: SpinContainer instance

The newly created spin.

convert_from_global_index(global_index=None, pipe=None)

Convert the global index into the molecule, residue, and spin indices.

Parameters:

• global_index (int) - The global spin index, spanning the molecule and residue containers.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.

Returns: tuple of int

The corresponding molecule, residue, and spin indices.

delete_molecule(mol_id=None)

Function for deleting molecules from the current data pipe.

Parameters:

• mol_id (str) - The molecule identifier string.

delete_residue(res_id=None)

Function for deleting residues from the current data pipe.

Parameters:

• res_id (str) - The molecule and residue identifier string.

delete_spin(spin_id=None)

Function for deleting spins from the current data pipe.

Parameters:

• spin_id (str) - The molecule, residue, and spin identifier string.

display_molecule(mol_id=None)

Function for displaying the information associated with the molecule.

Parameters:

• mol_id (str) - The molecule identifier string.

display_residue(res_id=None)

Function for displaying the information associated with the residue.

Parameters:

• res_id (str) - The molecule and residue identifier string.

display_spin(spin_id=None)

Function for displaying the information associated with the spin.

Parameters:

• spin_id (str) - The molecule and residue identifier string.

exists_mol_res_spin_data(pipe=None)

Function for determining if any molecule-residue-spin data exists.

Parameters:

• pipe (str) - The data pipe in which the molecule-residue-spin data will be checked for.

Returns: bool

The answer to the question about the existence of data.

find_index(selection=None, pipe=None, global_index=True)

Find and return the spin index or indices for the selection string.

Parameters:

• selection (str) - The spin selection identifier.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.
• global_index (bool) - A flag which if True will cause the global index to be returned. If False, then the molecule, residue, and spin indices will be returned.

Returns: int or tuple of 3 int

The global spin index or the molecule, residue, and spin indices.

first_residue_num(selection=None)

Determine the first residue number.

Returns: int

The number of the first residue.

generate_spin_id(pipe_cont=None, pipe_name=None, mol_name=None, res_num=None, res_name=None, spin_num=None, spin_name=None)

Generate the spin selection string.

Parameters:

• pipe_cont (PipeContainer instance) - The data pipe object.
• pipe_name (str) - The data pipe name.
• mol_name (str or None) - The molecule name.
• res_num (int or None) - The residue number.
• res_name (str or None) - The residue name.
• spin_num (int or None) - The spin number.
• spin_name (str or None) - The spin name.

Returns: str

The spin identification string.

generate_spin_id_data_array(data=None, mol_name_col=None, res_num_col=None, res_name_col=None, spin_num_col=None, spin_name_col=None)

Generate the spin selection string from the given data array.

Parameters:

• data (list of str) - An array containing the molecule, residue, and/or spin data.
• mol_name_col (int or None) - The column containing the molecule name information.
• res_name_col (int or None) - The column containing the residue name information.
• res_num_col (int or None) - The column containing the residue number information.
• spin_name_col (int or None) - The column containing the spin name information.
• spin_num_col (int or None) - The column containing the spin number information.

Returns: str

The spin identification string.

generate_spin_id_unique(pipe_cont=None, pipe_name=None, mol=None, res=None, spin=None, mol_name=None, res_num=None, res_name=None, spin_num=None, spin_name=None)

Generate a list of spin ID variants for the given set of molecule, residue and spin indices.

Parameters:

• pipe_cont (PipeContainer instance) - The data pipe object.
• pipe_name (str) - The data pipe name.
• mol (MoleculeContainer instance) - The molecule container.
• res (ResidueContainer instance) - The residue container.
• spin (SpinContainer instance) - The spin container.
• mol_name (str or None) - The molecule name (an alternative to the molecule container).
• res_num (int or None) - The residue number (an alternative to the residue container).
• res_name (str or None) - The residue name (an alternative to the residue container).
• spin_num (int or None) - The spin number (an alternative to the spin container).
• spin_name (str or None) - The spin name (an alternative to the spin container).

Returns: str

The unique spin ID.

get_molecule_ids(selection=None)

Return a list of the molecule ID strings.

Parameters:

• selection (str) - The molecule selection identifier.

Returns: list of str

The molecule ID strings.

get_molecule_names(selection=None)

Return a list of the molecule names.

Parameters:

• selection (str) - The molecule selection identifier.

Returns: list of str

The molecule names.

get_residue_ids(selection=None)

Return a list of the residue ID strings.

Parameters:

• selection (str) - The molecule and residue selection identifier.

Returns: list of str

The residue ID strings.

get_residue_names(selection=None)

Return a list of the residue names.

Parameters:

• selection (str) - The molecule and residue selection identifier.

Returns: list of str

The residue names.

get_residue_nums(selection=None)

Return a list of the residue numbers.

Parameters:

• selection (str) - The molecule and residue selection identifier.

Returns: list of str

The residue numbers.

get_spin_ids(selection=None)

Return a list of the spin ID strings.

Parameters:

• selection (str) - The molecule and spin selection identifier.

Returns: list of str

The spin ID strings.

index_molecule(mol_name=None, pipe=None)

Return the index of the molecule of the given name.

Parameters:

• mol_name (str or None) - The name of the molecule.
• pipe (str or None) - The data pipe, defaulting to the current data pipe.

Returns: int or None

The index of the molecule, if it exists.

index_residue(res_num=None, res_name=None, mol_index=None, pipe=None)

Return the index of the residue.

Parameters:

• res_num (int) - The number of the residue.
• res_name (str) - The name of the residue.
• mol_index (str) - The index of the molecule.
• pipe (str or None) - The data pipe, defaulting to the current data pipe.

Returns: int or None

The index of the residue, if it exists.

last_residue_num(selection=None)

Determine the last residue number.

Parameters:

• selection (str) - The molecule selection identifier.

Returns: int

The number of the last residue.

linear_ave(positions)

Perform linear averaging of the atomic positions.

Parameters:

• positions (list of lists of numpy float arrays) - The atomic positions. The first index is that of the positions to be averaged over. The second index is over the different models. The last index is over the x, y, and z coordinates.

Returns: list of numpy float arrays

The averaged positions as a list of vectors.

metadata_cleanup(mol_index=None, res_index=None, spin_index=None, pipe=None)

Prune all of the metadata matching the given indices.

Parameters:

• mol_index (int or None) - The index of the molecule to prune. If not supplied, all molecules will be pruned.
• res_index (int or None) - The index of the residue to prune. If not supplied, all residues of the matching molecules will be pruned.
• spin_index (int or None) - The index of the spin to prune. If not supplied, all spins of the matching residues will be pruned.
• pipe (str or None) - The data pipe to update, defaulting to the current data pipe.

metadata_counts(pipe_cont=None)

Update the molecule, residue, and spin name and number count metadata.

Parameters:

• pipe_cont (PipeContainer instance) - The data pipe object.

metadata_prune(mol_index=None, res_index=None, spin_index=None, pipe=None)

Prune all of the metadata matching the given indices.

Parameters:

• mol_index (int or None) - The index of the molecule to prune. If not supplied, all molecules will be pruned.
• res_index (int or None) - The index of the residue to prune. If not supplied, all residues of the matching molecules will be pruned.
• spin_index (int or None) - The index of the spin to prune. If not supplied, all spins of the matching residues will be pruned.
• pipe (str or None) - The data pipe to update, defaulting to the current data pipe.

metadata_update(mol_index=None, res_index=None, spin_index=None, pipe=None)

Update all of the private look up metadata for the given containers.

Parameters:

• mol_index (int or None) - The index of the molecule to update. If not supplied, all molecules will be updated.
• res_index (int or None) - The index of the residue to update. If not supplied, all residues will be updated.
• spin_index (int or None) - The index of the spin to update. If not supplied, all spins will be updated.
• pipe (str or None) - The data pipe to update, defaulting to the current data pipe.

molecule_loop(selection=None, pipe=None, return_id=False)

Generator function for looping over all the molecules of the given selection.

Parameters:

• selection (str) - The molecule selection identifier.
• pipe (str) - The data pipe containing the molecule. Defaults to the current data pipe.
• return_id (bool) - A flag which if True will cause the molecule identification string of the molecule spin to be returned in addition to the spin container.

Returns: instance of the MoleculeContainer class.

The molecule specific data container.

name_molecule(mol_id, name=None, force=False)

Name the molecules.

Parameters:

• mol_id (str) - The molecule identification string.
• name (str) - The new molecule name.
• force (bool) - A flag which if True will cause the named molecule to be renamed.

name_residue(res_id, name=None, force=False)

Name the residues.

Parameters:

• res_id (str) - The residue identification string.
• name (str) - The new residue name.
• force (bool) - A flag which if True will cause the named residue to be renamed.

name_spin(spin_id=None, name=None, pipe=None, force=False)

Name the spins.

Parameters:

• spin_id (str) - The spin identification string.
• name (str) - The new spin name.
• pipe (str) - The data pipe to operate on. Defaults to the current data pipe.
• force (bool or None) - A flag which if True will cause the named spin to be renamed. If None, then the warning messages will not mention the need to change this flag to rename.

number_residue(res_id, number=None, force=False)

Number the residues.

Parameters:

• res_id (str) - The residue identification string.
• number (int) - The new residue number.
• force (bool) - A flag which if True will cause the numbered residue to be renumbered.

number_spin(spin_id=None, number=None, force=False)

Number the spins.

Parameters:

• spin_id (str) - The spin identification string.
• number (int) - The new spin number.
• force (bool) - A flag which if True will cause the numbered spin to be renumbered.

one_letter_code(res_names)

Convert the list of residue names into a string of one letter residue codes.

Standard amino acids are converted to the one letter code. Unknown residues are labelled as 'X'.

Parameters:

• res_names (list or str) - A list of residue names.

Returns: str

The one letter codes for the residues.

parse_token(token, verbosity=False)

Parse the token string and return a list of identifying numbers and names.

Firstly the token is split by the ',' character into its individual elements and all whitespace stripped from the elements. Numbers are converted to integers, names are left as strings, and ranges are converted into the full list of integers.

Parameters:

• token (str) - The identification string, the elements of which are separated by commas. Each element can be either a single number, a range of numbers (two numbers separated by '-'), or a name.
• verbosity (bool) - A flag which if True will cause a number of printouts to be activated.

Returns: list of int and str

A list of identifying numbers and names.

residue_loop(selection=None, pipe=None, full_info=False, return_id=False)

Generator function for looping over all the residues of the given selection.

Parameters:

• selection (str) - The residue selection identifier.
• pipe (str) - The data pipe containing the residue. Defaults to the current data pipe.
• full_info (boolean) - A flag specifying if the amount of information to be returned. If false, only the data container is returned. If true, the molecule name, residue number, and residue name is additionally returned.
• return_id (bool) - A flag which if True will cause the molecule identification string of the molecule spin to be returned in addition to the spin container.

Returns: instance of the ResidueContainer class. If full_info=True, the type is the tuple (ResidueContainer, str).

The residue specific data container and, if full_info=True, the molecule name.

return_molecule(selection=None, pipe=None)

Function for returning the molecule data container of the given selection.

Parameters:

• selection (str) - The molecule selection identifier.
• pipe (str) - The data pipe containing the molecule. Defaults to the current data pipe.

Returns: instance of the MoleculeContainer class.

The molecule specific data container.

return_molecule_by_name(pipe_cont=None, pipe_name=None, mol_name=None)

Return the molecule container matching the given name.

Parameters:

• pipe_cont (PipeContainer instance) - The data pipe object.
• pipe_name (str) - The data pipe name.
• mol_name (str) - The molecule name. If not supplied and only a single molecule container exists, then that container will be returned.

Returns: MoleculeContainer instance

The molecule container object.

return_residue(selection=None, pipe=None, indices=False)

Function for returning the residue data container of the given selection.

Parameters:

• selection (str) - The residue selection identifier.
• pipe (str) - The data pipe containing the residue. Defaults to the current data pipe.

Returns: instance of the ResidueContainer class.

The residue specific data container, and the molecule and residue indices if asked.

return_residue_by_info(mol=None, res_name=None, res_num=None)

Return the residue container matching the given name.

Parameters:

• mol (MoleculeContainer instance) - The molecule container.
• res_name (str) - The residue name. If not supplied and only a single residue container exists, then that container will be returned.
• res_num (str) - The residue number. If not supplied and only a single residue container exists, then that container will be returned.

Returns: ResidueContainer instance

The residue container object.

return_spin(spin_id=None, pipe=None, full_info=False, multi=False)

Return the spin data container corresponding to the given spin ID string.

Parameters:

• spin_id (str) - The unique spin ID string.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.
• full_info (bool) - A flag specifying if the amount of information to be returned. If false, only the data container is returned. If true, the molecule name, residue number, and residue name is additionally returned.
• multi (bool) - A flag which if True will allow multiple spins to be returned.

Returns: SpinContainer instance of list of instances or tuple of (str, int, str, SpinContainer instance or list of instances)

The spin system specific data container and, if full_info=True, the molecule name, residue number, and residue name.

return_spin_by_info(res=None, spin_name=None, spin_num=None)

Return the spin container matching the given name.

Parameters:

• res (ResidueContainer instance) - The residue container.
• spin_name (str) - The spin name. If not supplied and only a single spin container exists, then that container will be returned.
• spin_num (str) - The spin number. If not supplied and only a single spin container exists, then that container will be returned.

Returns: SpinContainer instance

The spin container object.

return_spin_from_selection(selection=None, pipe=None, full_info=False, multi=False)

Function for returning the spin data container of the given selection.

If more than one selection is given, then the boolean AND operation will be used to pull out the spin.

Parameters:

• selection (str) - The spin selection identifier.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.
• full_info (bool) - A flag specifying if the amount of information to be returned. If false, only the data container is returned. If true, the molecule name, residue number, and residue name is additionally returned.
• multi (bool) - A flag which if True will allow multiple spins to be returned.

Returns: SpinContainer instance of list of instances or tuple of (str, int, str, SpinContainer instance or list of instances)

The spin system specific data container and, if full_info=True, the molecule name, residue number, and residue name.

return_spin_from_index(global_index=None, pipe=None, return_spin_id=False)

Function for returning the spin data container corresponding to the global index.

Parameters:

• global_index (int) - The global spin index, spanning the molecule and residue containers.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.
• return_spin_id (bool) - A flag which if True will cause both the spin container and spin identification string to be returned.

Returns: instance of the SpinContainer class (or tuple of SpinContainer and str)

The spin specific data container (additionally the spin identification string if return_spin_id is set).

return_spin_indices(spin_id=None, pipe=None)

Return the molecule, residue and spin indices corresponding to the given spin ID string.

Parameters:

• spin_id (str) - The unique spin ID string.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.

Returns: list of int

The molecule, residue and spin indices.

return_single_molecule_info(molecule_token)

Return the single molecule name corresponding to the molecule token.

Parameters:

• molecule_token (str) - The molecule identification string.

Returns: str

The molecule name.

return_single_residue_info(residue_token)

Return the single residue number and name corresponding to the residue token.

Parameters:

• residue_token (str) - The residue identification string.

Returns: (int, str)

A tuple containing the residue number and the residue name.

return_single_spin_info(spin_token)

Return the single spin number and name corresponding to the spin token.

Parameters:

• spin_token (str) - The spin identification string.

Returns: (int, str)

A tuple containing the spin number and the spin name.

same_sequence(pipe1, pipe2)

Test if the sequence data in both pipes are the same.

Parameters:

• pipe1 (str) - The first data pipe.
• pipe2 (str) - The second data pipe.

Returns: bool

True if the sequence data matches, False otherwise.

set_spin_element(spin_id=None, element=None, pipe=None, force=False)

Set the element type of the spins.

Parameters:

• spin_id (str) - The spin identification string.
• element (str) - The IUPAC element name.
• pipe (str) - The data pipe to operate on. Defaults to the current data pipe.
• force (bool) - A flag which if True will cause the element to be changed.

set_spin_isotope(spin_id=None, isotope=None, pipe=None, force=False)

Set the nuclear isotope type of the spins.

Parameters:

• spin_id (str) - The spin identification string.
• isotope (str) - The nuclear isotope type.
• pipe (str) - The data pipe to operate on. Defaults to the current data pipe.
• force (bool or None) - A flag which if True will cause the isotope type to be changed. If None, then the warning messages will not mention the need to change this flag to rename.

spin_id_to_data_list(id)

Convert the single spin ID string into a list of the mol, res, and spin names and numbers.

Parameters:

• id (str) - The spin ID string.

Returns: str, int, str, int, str

The molecule name, the residue number and name, and the spin number and name.

spin_id_variants(dp=None, mol_index=None, res_index=None, spin_index=None)

Generate a list of spin ID variants for the given set of molecule, residue and spin indices.

Parameters:

• dp (PipeContainer instance) - The data pipe to work on.
• mol_index (int) - The molecule index.
• res_index (int) - The residue index.
• spin_index (int) - The spin index.

Returns: list of str

The list of all spin IDs matching the spin.

spin_id_variants_cleanup(dp=None, mol_index=None, res_index=None, spin_index=None)

Generate a list of spin ID variants to eliminate for the given set of molecule, residue and spin indices.

Parameters:

• dp (PipeContainer instance) - The data pipe to work on.
• mol_index (int) - The molecule index.
• res_index (int) - The residue index.
• spin_index (int) - The spin index.

Returns: list of str

The list of all spin IDs matching the spin.

spin_id_variants_prune(dp=None, mol_index=None, res_index=None, spin_index=None)

Generate a list of spin ID variants to eliminate for the given set of molecule, residue and spin indices.

Parameters:

• dp (PipeContainer instance) - The data pipe to work on.
• mol_index (int) - The molecule index.
• res_index (int) - The residue index.
• spin_index (int) - The spin index.

Returns: list of str

The list of all spin IDs matching the spin.

spin_in_list(spin_list, mol_name_col=None, res_num_col=None, res_name_col=None, spin_num_col=None, spin_name_col=None, mol_name=None, res_num=None, res_name=None, spin_num=None, spin_name=None)

Function for determining if the spin is located within the list of spins.

Parameters:

• spin_list (list of lists of str) - The list of spins. The first dimension corresponds to different spins, the second corresponds to the spin information columns.
• mol_name_col (int or None) - The column containing the molecule name information.
• res_num_col (int or None) - The column containing the residue number information.
• res_name_col (int or None) - The column containing the residue name information.
• spin_num_col (int or None) - The column containing the spin number information.
• spin_name_col (int or None) - The column containing the spin name information.
• mol_name (str or None) - The molecule name.
• res_num (int or None) - The residue number.
• res_name (str or None) - The residue name.
• spin_num (int or None) - The spin number.
• spin_name (str or None) - The spin name.

Returns: bool

The answer of whether the spin is within the list.

spin_index_loop(selection=None, pipe=None)

Generator function for looping over all selected spins, returning the mol-res-spin indices.

Parameters:

• selection (str) - The spin system selection identifier.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.

Returns: tuple of 3 int

The molecule, residue, and spin index.

spin_loop(selection=None, pipe=None, full_info=False, return_id=False)

Generator function for looping over all the spin systems of the given selection.

Parameters:

• selection (str) - The spin system selection identifier.
• pipe (str) - The data pipe containing the spin. Defaults to the current data pipe.
• full_info (bool) - A flag which if True will cause the the molecule name, residue number, and residue name to be returned in addition to the spin container.
• return_id (bool) - A flag which if True will cause the spin identification string of the current spin to be returned in addition to the spin container.

Returns: If full_info and return_id are False, SpinContainer instance. If full_info is True and return_id is false, a tuple of (SpinContainer instance, str, int, str). If full_info is False and return_id is True, a tuple of (SpinContainer instance, str). If full_info and return_id are False, a tuple of (SpinContainer instance, str, int, str, str)

The spin system specific data container. If full_info is True, a tuple of the spin container, the molecule name, residue number, and residue name. If return_id is True, a tuple of the spin container and spin id. If both flags are True, then a tuple of the spin container, the molecule name, residue number, residue name, and spin id.

tokenise(selection)

Split the input selection string returning the mol_token, res_token, and spin_token strings.

The mol_token is identified as the text from the '#' to either the ':' or '@' characters or the end of the string.

The res_token is identified as the text from the ':' to either the '@' character or the end of the string.

The spin_token is identified as the text from the '@' to the end of the string.

Parameters:

• selection (str) - The selection identifier.

Returns: 3-tuple of str or None

The mol_token, res_token, and spin_token.

type_molecule(mol_id, type=None, force=False)

Set the molecule type.

Parameters:

• mol_id (str) - The molecule identification string.
• type (str) - The molecule type.
• force (bool) - A flag which if True will cause the molecule type to be overwritten.

Variables Details

ALLOWED_MOL_TYPES

The list of allowable molecule types.

Value:

['protein', 'DNA', 'RNA', 'organic molecule', 'inorganic molecule']