IMP Reference Guide  develop.7a5fd2655d,2023/02/03 The Integrative Modeling Platform
IMP.pmi.tools Namespace Reference

Miscellaneous utilities. More...

## Detailed Description

Miscellaneous utilities.

## Classes

class  ColorChange
Change color code to hexadecimal to rgb. More...

class  OrderedDefaultDict
Store objects in order they were added, but with default type. More...

class  Segments
This class stores integers in ordered compact lists eg: [[1,2,3],[6,7,8]] the methods help splitting and merging the internal lists Example: s=Segments([1,2,3]) is [[1,2,3]] s.add(4) is [[1,2,3,4]] (add right) s.add(3) is [[1,2,3,4]] (item already existing) s.add(7) is [[1,2,3,4],[7]] (new list) s.add([8,9]) is [[1,2,3,4],[7,8,9]] (add item right) s.add([5,6]) is [[1,2,3,4,5,6,7,8,9]] (merge) s.remove(3) is [[1,2],[4,5,6,7,8,9]] (split) etc. More...

class  Stopwatch
Collect timing information. More...

## Functions

Add a PMI restraint to the model. More...

def color2rgb
Given a Chimera color name or hex color value, return RGB. More...

example '"{ID_Score}" > 28 AND "{Sample}" == "%10_1%" OR ":Sample}" == "%10_2%" OR ":Sample}" == "%10_3%" OR ":Sample}" == "%8_1%" OR ":Sample}" == "%8_2%"' More...

def display_bonds
Decorate the sequence-consecutive particles from a PMI2 molecule with a bond, so that they appear connected in the rmf file. More...

def get_all_leaves
Just get the leaves from a list of hierarchies. More...

def get_closest_residue_position
this function works with plain hierarchies, as read from the pdb, no multi-scale hierarchies More...

def get_densities
Given a list of PMI objects, returns all density hierarchies within these objects. More...

def get_molecules
This function returns the parent molecule hierarchies of given objects. More...

def get_particles_within_zone
Utility to retrieve particles from a hierarchy within a zone around a set of ps. More...

def get_prot_name_from_particle
Return the component name provided a particle and a list of names. More...

Returns unique objects in original order. More...

def get_residue_gaps_in_hierarchy
Return the residue index gaps and contiguous segments in the hierarchy. More...

def get_residue_indexes
Retrieve the residue indexes for the given particle. More...

def get_restraint_set
Get a RestraintSet containing all PMI restraints added to the model. More...

def get_sorted_segments
Returns sequence-sorted segments array, each containing the first particle the last particle and the first residue index. More...

Adapt things for PMI (degrees of freedom, restraints, ...) Returns list of list of hierarchies, separated into Molecules if possible. More...

def list_chunks_iterator
Yield successive length-sized chunks from a list. More...

def scatter_and_gather
Synchronize data over a parallel run. More...

def select_at_all_resolutions
Perform selection using the usual keywords but return ALL resolutions (BEADS and GAUSSIANS). More...

def select_by_tuple_2
New tuple format: molname OR (start,stop,molname,copynum,statenum) Copy and state are optional. More...

def set_coordinates_from_rmf
Extract frame from RMF file and fill coordinates. More...

def shuffle_configuration
Shuffle particles. More...

def sublist_iterator
Yield all sublists of length >= lmin and <= lmax. More...

## Function Documentation

 def IMP.pmi.tools.add_restraint_to_model ( model, restraint, add_to_rmf = False )

Add a PMI restraint to the model.

Since Model.add_restraint() no longer exists (in modern IMP restraints should be added to a ScoringFunction instead) store them instead in a RestraintSet, and keep a reference to it in the Model.

If add_to_rmf is True, also add the restraint to a separate list of restraints that will be written out to RMF files (by default, most PMI restraints are not).

Note
This function is only available in Python.

Definition at line 91 of file tools.py.

 def IMP.pmi.tools.color2rgb ( colorname )

Given a Chimera color name or hex color value, return RGB.

Note
This function is only available in Python.

Definition at line 1632 of file tools.py.

example '"{ID_Score}" > 28 AND "{Sample}" == "%10_1%" OR ":Sample}" == "%10_2%" OR ":Sample}" == "%10_3%" OR ":Sample}" == "%8_1%" OR ":Sample}" == "%8_2%"'

Note
This function is only available in Python.

Definition at line 332 of file tools.py.

 def IMP.pmi.tools.display_bonds ( mol )

Decorate the sequence-consecutive particles from a PMI2 molecule with a bond, so that they appear connected in the rmf file.

Note
This function is only available in Python.

Definition at line 1107 of file tools.py.

 def IMP.pmi.tools.get_all_leaves ( list_of_hs )

Just get the leaves from a list of hierarchies.

Note
This function is only available in Python.

Definition at line 1129 of file tools.py.

 def IMP.pmi.tools.get_closest_residue_position ( hier, resindex, terminus = 'N' )

this function works with plain hierarchies, as read from the pdb, no multi-scale hierarchies

Note
This function is only available in Python.

Definition at line 386 of file tools.py.

 def IMP.pmi.tools.get_densities ( input_objects )

Given a list of PMI objects, returns all density hierarchies within these objects.

The output of this function can be inputted into things such as EM restraints. This function is intended to gather density particles appended to molecules (and not other hierarchies which might have been appended to the root node directly).

Note
This function is only available in Python.

Definition at line 1280 of file tools.py.

 def IMP.pmi.tools.get_molecules ( input_objects )

This function returns the parent molecule hierarchies of given objects.

Note
This function is only available in Python.

Definition at line 1233 of file tools.py.

 def IMP.pmi.tools.get_particles_within_zone ( hier, target_ps, sel_zone, entire_residues, exclude_backbone )

Utility to retrieve particles from a hierarchy within a zone around a set of ps.

Parameters
 hier The hierarchy in which to look for neighbors target_ps The particles for zoning sel_zone The maximum distance entire_residues If True, will grab entire residues exclude_backbone If True, will only return sidechain particles
Note
This function is only available in Python.

Definition at line 1174 of file tools.py.

 def IMP.pmi.tools.get_prot_name_from_particle ( p, list_of_names )

Return the component name provided a particle and a list of names.

Note
This function is only available in Python.

Definition at line 550 of file tools.py.

Returns unique objects in original order.

Note
This function is only available in Python.

Definition at line 1209 of file tools.py.

 def IMP.pmi.tools.get_residue_gaps_in_hierarchy ( hierarchy, start, end )

Return the residue index gaps and contiguous segments in the hierarchy.

Parameters
 hierarchy hierarchy to examine start first residue index end last residue index
Returns
A list of lists of the form [[1,100,"cont"],[101,120,"gap"],[121,200,"cont"]]
Note
This function is only available in Python.

Definition at line 424 of file tools.py.

 def IMP.pmi.tools.get_residue_indexes ( hier )

Retrieve the residue indexes for the given particle.

The particle must be an instance of Fragment,Residue, Atom or Molecule or else returns an empty list

Note
This function is only available in Python.

Definition at line 570 of file tools.py.

 def IMP.pmi.tools.get_restraint_set ( model, rmf = False )

Get a RestraintSet containing all PMI restraints added to the model.

If rmf is True, return only the subset of these restraints that should be written out to RMF files.

Note
This function is only available in Python.

Definition at line 111 of file tools.py.

 def IMP.pmi.tools.get_sorted_segments ( mol )

Returns sequence-sorted segments array, each containing the first particle the last particle and the first residue index.

Note
This function is only available in Python.

Definition at line 1081 of file tools.py.

 def IMP.pmi.tools.input_adaptor ( stuff, pmi_resolution = 0, flatten = False, selection_tuple = None, warn_about_slices = True )

Adapt things for PMI (degrees of freedom, restraints, ...) Returns list of list of hierarchies, separated into Molecules if possible.

The input can be a list, or a list of lists (iterable of ^1 or iterable of ^2) (iterable of ^2) Hierarchy -> returns input as list of list of hierarchies, only one entry, not grouped by molecules. (iterable of ^2) PMI::System/State/Molecule/TempResidue -> returns residue hierarchies, grouped in molecules, at requested resolution

Parameters
 stuff Can be one of the following inputs: IMP Hierarchy, PMI System/State/Molecule/TempResidue, or a list/set (of list/set) of them. Must be uniform input, however. No mixing object types. pmi_resolution For selecting, only does it if you pass PMI objects. Set it to "all" if you want all resolutions! flatten Set to True if you just want all hierarchies in one list. warn_about_slices Print a warning if you are requesting only part of a bead. Sometimes you just don't care!
Note
since this relies on IMP::atom::Selection, this will not return any objects if they weren't built! But there should be no problem if you request unbuilt residues - they should be ignored.
This function is only available in Python.

Definition at line 946 of file tools.py.

 def IMP.pmi.tools.list_chunks_iterator ( list, length )

Yield successive length-sized chunks from a list.

Note
This function is only available in Python.

Definition at line 661 of file tools.py.

 def IMP.pmi.tools.scatter_and_gather ( data )

Synchronize data over a parallel run.

Note
This function is only available in Python.

Definition at line 613 of file tools.py.

 def IMP.pmi.tools.select_at_all_resolutions ( hier = None, hiers = None, kwargs )

Perform selection using the usual keywords but return ALL resolutions (BEADS and GAUSSIANS).

Returns in flat list!

Note
This function is only available in Python.

Definition at line 1136 of file tools.py.

 def IMP.pmi.tools.select_by_tuple_2 ( hier, tuple_selection, resolution )

New tuple format: molname OR (start,stop,molname,copynum,statenum) Copy and state are optional.

Can also use 'None' for them which will get all. You can also pass -1 for stop which will go to the end. Returns the particles

Note
This function is only available in Python.

Definition at line 501 of file tools.py.

 def IMP.pmi.tools.set_coordinates_from_rmf ( hier, rmf_fn, frame_num = 0 )

Extract frame from RMF file and fill coordinates.

Must be identical topology.

Parameters
 hier The (System) hierarchy to fill (e.g. after you've built it) rmf_fn The file to extract from frame_num The frame number to extract
Note
This function is only available in Python.

Definition at line 920 of file tools.py.

 def IMP.pmi.tools.shuffle_configuration ( objects, max_translation = 300.0, max_rotation = 2.0 * math.pi, avoidcollision_rb = True, avoidcollision_fb = False, cutoff = 10.0, niterations = 100, bounding_box = None, excluded_rigid_bodies = [], hierarchies_excluded_from_collision = [], hierarchies_included_in_collision = [], verbose = False, return_debug = False )

Shuffle particles.

Used to restart the optimization. The configuration of the system is initialized by placing each rigid body and each bead randomly in a box. If bounding_box is specified, the particles are placed inside this box; otherwise, each particle is displaced by up to max_translation angstroms, and randomly rotated. Effort is made to place particles far enough from each other to prevent any steric clashes.

Parameters
 objects Can be one of the following inputs: IMP Hierarchy, PMI System/State/Molecule/TempResidue, or a list/set of them max_translation Max translation (rbs and flexible beads) max_rotation Max rotation (rbs only) avoidcollision_rb check if the particle/rigid body was placed close to another particle; uses the optional arguments cutoff and niterations avoidcollision_fb Advanced. Generally you want this False because it's hard to shuffle beads. cutoff Distance less than this is a collision niterations How many times to try avoiding collision bounding_box Only shuffle particles within this box. Defined by ((x1,y1,z1),(x2,y2,z2)). excluded_rigid_bodies Don't shuffle these rigid body objects hierarchies_excluded_from_collision Don't count collision with these bodies hierarchies_included_in_collision Hierarchies that are not shuffled, but should be included in collision calculation (for fixed regions) verbose Give more output
Note
Best to only call this function after you've set up degrees of freedom For debugging purposes, returns: <shuffled indexes>="">, <collision avoided="" indexes>="">
This function is only available in Python.

Definition at line 1316 of file tools.py.

 def IMP.pmi.tools.sublist_iterator ( ls, lmin = 1, lmax = None )

Yield all sublists of length >= lmin and <= lmax.

Note
This function is only available in Python.

Definition at line 645 of file tools.py.