IMP  2.4.0
The Integrative Modeling Platform
Classes | Typedefs | Functions
IMP::rmf Namespace Reference

Support for the RMF file format for storing hierarchical molecular data and markup. More...

Detailed Description

Support for the RMF file format for storing hierarchical molecular data and markup.

RMF can store hierarchical molecular data (such as atomic or coarse grained representations of proteins), along with markup, including geometry and score data.

IMP.rmf supports I/O of IMP::atom::Hierarchy and associated types as well as output of IMP::display::Geometry, IMP::Restraint and arbitrary IMP::Particles. For each of these there are methods like:

Once objects are linked/added/created, they are attached to the RMF file. IMP::rmf::load_frame() can be used to change the state of the linked objects to that of an arbitrary frame and IMP::rmf::save_frame() can be used to save the current state of the objects into a frame in the RMF file.

See the RMF library for more information.

Several helper programs are also provided:

rmf_display

Export an RMF file to a viewer. rmf_display outputs an arbitrary RMF file to pymol or chimera as appropriate (based on the file name of the second argument). It supports hierarchies, restraints and geometry.

pdb_rmf

Make an RMF file from a PDB.

rmf_simplify

Create a simplified representation of a PDB.

Info

Author(s): Daniel Russel

Maintainer: benmwebb

License: LGPL This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Publications:

Classes

class  HierarchyLoadLink
 
class  HierarchySaveLink
 
class  LoadLink
 
class  SaveLink
 
class  SaveOptimizerState
 
class  SimpleLoadLink
 
class  SimpleSaveLink
 

Typedefs

typedef base::ObjectAssociationType
 
typedef IMP::base::Vector
< IMP::base::Pointer< LoadLink > > 
LoadLinks
 
typedef IMP::base::Vector
< IMP::base::WeakPointer
< LoadLink > > 
LoadLinksTemp
 
typedef IMP::base::Vector
< IMP::base::Pointer< SaveLink > > 
SaveLinks
 
typedef IMP::base::Vector
< IMP::base::WeakPointer
< SaveLink > > 
SaveLinksTemp
 

Functions

template<class T >
T * get_association (RMF::NodeConstHandle nh)
 
void load_frame (RMF::FileConstHandle file, RMF::FrameID frame)
 
void load_frame (RMF::FileConstHandle file, unsigned int frame)
 
RMF::FrameID save_frame (RMF::FileHandle file, std::string name="")
 
void save_frame (RMF::FileHandle file, unsigned int, std::string name="")
 
void set_association (RMF::NodeConstHandle nh, base::Object *o, bool overwrite=false)
 

Associations

RMF supports tracking associations between an RMF file and native objects. In the IMP case these are IMP::base::Object and we provide some special methods to aid in this process.

RMF::NodeConstHandle get_node_from_association (RMF::FileConstHandle nh, base::Object *oi)
 
RMF::NodeHandle get_node_from_association (RMF::FileHandle nh, base::Object *oi)
 
bool get_has_associated_node (RMF::FileConstHandle nh, base::Object *oi)
 

Hierarchy I/O

Hierarchy I/O writes IMP::atom::Hierarchy information along with the information contained in the following decorators

Note
IMP::core::XYZ and IMP::core::RigidBody data are stored at each frame. Data for all the other decorators are assumed to be static attributes, and are stored once for the entire RMF file. There is currently no way to customize this. Complain to the IMP team if this is problematic.

Note
To avoid unexpected behavior, be aware that when linking atom::Hierarchies against an RMF file, the linked hierarchies are assumed to be identical in all of their static attributes to the hierarchies in the RMF file (within RMF::REPRESENTATION nodes). In particular, these hierarchies must have the same tree topology (number of children for each node).
void add_hierarchies (RMF::FileHandle fh, const atom::Hierarchies &hs)
 
void add_hierarchies (RMF::NodeHandle fh, const atom::Hierarchies &hs)
 
void add_hierarchy (RMF::FileHandle fh, atom::Hierarchy hs)
 
atom::Hierarchies create_hierarchies (RMF::FileConstHandle fh, kernel::Model *m)
 
void link_hierarchies (RMF::FileConstHandle fh, const atom::Hierarchies &hs)
 

Geometry I/O

The geometry I/O support currently handles geometry composed of

Other types can be supported when requested. Be aware, many more complex geometry types are automatically decomposed into the above types and so, more or less, supported.

void add_geometries (RMF::FileHandle file, const display::GeometriesTemp &r)
 
void add_geometries (RMF::NodeHandle parent, const display::GeometriesTemp &r)
 
void add_static_geometries (RMF::FileHandle parent, const display::GeometriesTemp &r)
 
display::Geometries create_geometries (RMF::FileConstHandle parent)
 
void link_geometries (RMF::FileConstHandle parent, const display::GeometriesTemp &r)
 

kernel::Particle I/O

Arbitrary (non IMP::atom::Hierarchy) particles can be written to the file and read back from them. All non IMP::base::Object attributes are supported. Note that currently particles must be added so that any particles that are stored in a given particles attributes are added to the file first.

The data is stored in a category named IMP.

void add_particles (RMF::FileHandle fh, const kernel::ParticlesTemp &hs)
 
void add_particles (RMF::NodeHandle fh, const kernel::ParticlesTemp &hs)
 
void add_particle (RMF::FileHandle fh, kernel::Particle *hs)
 
kernel::ParticlesTemp create_particles (RMF::FileConstHandle fh, kernel::Model *m)
 
void link_particles (RMF::FileConstHandle fh, const kernel::ParticlesTemp &hs)
 

kernel::Restraint I/O

kernel::Restraints are written as am RMF::FEATURE node with subnodes for the decomposed restraints (kernel::Restraint::create_current_decomposition()). The kernel::Restraints::get_last_score() value is what is saved to the file, so make sure that the restraints have been evaluated before saving a frame.

Any particles returned by kernel::Restraint::get_input_particles() that are also linked in the RMF file will be included in the RMF file as inputs for the kernel::Restraint. This allows external software like e.g., Chimera to associate these restrains with a certain set of particles.

void add_restraints (RMF::FileHandle fh, const kernel::Restraints &hs)
 
void add_restraints (RMF::NodeHandle fh, const kernel::Restraints &hs)
 
void add_restraint (RMF::FileHandle fh, kernel::Restraint *hs)
 
kernel::Restraints create_restraints (RMF::FileConstHandle fh, kernel::Model *m)
 
void link_restraints (RMF::FileConstHandle fh, const kernel::Restraints &hs)
 
void add_restraints_as_bonds (RMF::FileHandle fh, const kernel::Restraints &rs)
 
void set_maximum_number_of_terms (RMF::FileHandle fh, unsigned int num)
 

Standard module functions

All IMP modules have a set of standard functions to help get information about the module and about files associated with the module.

std::string get_module_version ()
 
std::string get_module_name ()
 
std::string get_data_path (std::string file_name)
 Return the full path to installed data. More...
 
std::string get_example_path (std::string file_name)
 Return the path to installed example data for this module. More...
 

Typedef Documentation

Store a set of objects.

Definition at line 24 of file links.h.

Pass a set of objects.

See Also
LoadLink

Definition at line 26 of file links.h.

Store a set of objects.

Definition at line 23 of file links.h.

Pass a set of objects.

See Also
SaveLink

Definition at line 24 of file links.h.

Function Documentation

void IMP::rmf::add_geometries ( RMF::FileHandle  file,
const display::GeometriesTemp &  r 
)

Add the geometry to the file

void IMP::rmf::add_geometries ( RMF::NodeHandle  parent,
const display::GeometriesTemp &  r 
)

Add them to a given parent node.

void IMP::rmf::add_hierarchies ( RMF::FileHandle  fh,
const atom::Hierarchies &  hs 
)

Add objects to the file.

Note
This does not save a configuration; make sure you use save_frame() to do that.
void IMP::rmf::add_hierarchies ( RMF::NodeHandle  fh,
const atom::Hierarchies &  hs 
)

Add objects to the file under the specified node.

Note
This does not save a configuration; make sure you use save_frame() to do that.
void IMP::rmf::add_hierarchy ( RMF::FileHandle  fh,
atom::Hierarchy  hs 
)

Add a single Hierarchy object to the RMF file.

Note
This does not save a configuration; make sure you use save_frame() to do that.
void IMP::rmf::add_particle ( RMF::FileHandle  fh,
kernel::Particle *  hs 
)

Add a single kernel::Particle object to the RMF file.

Note
This does not save a configuration; make sure you use save_frame() to do that.
void IMP::rmf::add_particles ( RMF::NodeHandle  fh,
const kernel::ParticlesTemp &  hs 
)

Add objects to the file under the specified node.

Note
This does not save a configuration; make sure you use save_frame() to do that.
void IMP::rmf::add_particles ( RMF::FileHandle  fh,
const kernel::ParticlesTemp &  hs 
)

Add objects to the file.

Note
This does not save a configuration; make sure you use save_frame() to do that.
void IMP::rmf::add_restraint ( RMF::FileHandle  fh,
kernel::Restraint *  hs 
)

Add a single Restraint object to the RMF file.

Note
This does not save a configuration; make sure you use save_frame() to do that.
void IMP::rmf::add_restraints ( RMF::FileHandle  fh,
const kernel::Restraints &  hs 
)

Add objects to the file.

Note
This does not save a configuration; make sure you use save_frame() to do that.
void IMP::rmf::add_restraints ( RMF::NodeHandle  fh,
const kernel::Restraints &  hs 
)

Add objects to the file under the specified node.

Note
This does not save a configuration; make sure you use save_frame() to do that.
void IMP::rmf::add_restraints_as_bonds ( RMF::FileHandle  fh,
const kernel::Restraints &  rs 
)

Add a list of restraints to the file as (static) bonds. There restraints must decompose into pairwise restraints. Their scores will not be recorded in the file.

void IMP::rmf::add_static_geometries ( RMF::FileHandle  parent,
const display::GeometriesTemp &  r 
)

Add the following geometry, assuming they do not move between frames. This can be space saving compared to resaving the constant position each frame.

display::Geometries IMP::rmf::create_geometries ( RMF::FileConstHandle  parent)

Create geometry objects for the geometry nodes found in the file.

atom::Hierarchies IMP::rmf::create_hierarchies ( RMF::FileConstHandle  fh,
kernel::Model *  m 
)

Create Hierarchy objects from the RMF file.

Note
This does not load a frame. Make sure you call IMP::rmf::load_frame() before using.
kernel::ParticlesTemp IMP::rmf::create_particles ( RMF::FileConstHandle  fh,
kernel::Model *  m 
)

Create kernel::Particle objects from the RMF file.

Note
This does not load a frame. Make sure you call IMP::rmf::load_frame() before using.
kernel::Restraints IMP::rmf::create_restraints ( RMF::FileConstHandle  fh,
kernel::Model *  m 
)

Create Restraint objects from the RMF file.

Note
This does not load a frame. Make sure you call IMP::rmf::load_frame() before using.
std::string IMP::rmf::get_data_path ( std::string  file_name)

Return the full path to installed data.

Each module has its own data directory, so be sure to use the version of this function in the correct module. To read the data file "data_library" that was placed in the data directory of module "mymodule", do something like

std::ifstream in(IMP::mymodule::get_data_path("data_library"));

This will ensure that the code works when IMP is installed or used via the setup_environment.sh script.

std::string IMP::rmf::get_example_path ( std::string  file_name)

Return the path to installed example data for this module.

Each module has its own example directory, so be sure to use the version of this function in the correct module. For example to read the file example_protein.pdb located in the examples directory of the IMP::atom module, do

model));

This will ensure that the code works when IMP is installed or used via the setup_environment.sh script.

void IMP::rmf::link_geometries ( RMF::FileConstHandle  parent,
const display::GeometriesTemp &  r 
)

Link the passed geometry objects to corresponding ones in the file. They must be in the same order, we don't search around for matches.

void IMP::rmf::link_hierarchies ( RMF::FileConstHandle  fh,
const atom::Hierarchies &  hs 
)

Link Hierarchy objects with the RMF file, possibly overwriting an existing link for loading from the file. This does not alter the object, but will affect the behavior of functions like load_frame() and save_frame(). See Linking hierarchies for more information and intricacies

void IMP::rmf::link_particles ( RMF::FileConstHandle  fh,
const kernel::ParticlesTemp &  hs 
)

Link kernel::Particle objects with the RMF file, possibly overwriting an existing link for loading from the file. This does not alter the object, but will affect the behavior of functions like load_frame() and save_frame().

void IMP::rmf::link_restraints ( RMF::FileConstHandle  fh,
const kernel::Restraints &  hs 
)

Link Restraint objects with the RMF file, possibly overwriting an existing link for loading from the file. This does not alter the object, but will affect the behavior of functions like load_frame() and save_frame().

void IMP::rmf::load_frame ( RMF::FileConstHandle  file,
RMF::FrameID  frame 
)

Load the specified frame into the state of the associated IMP::base::Objects with the RMF file.

The current frame is left as the passed frame number.

void IMP::rmf::load_frame ( RMF::FileConstHandle  file,
unsigned int  frame 
)
Deprecated:
As of IMP release 2.2. See the IMP Deprecation Policy for more information about deprecation in IMP. Pass the frame as an RMF::FrameID.

Definition at line 27 of file frames.h.

RMF::FrameID IMP::rmf::save_frame ( RMF::FileHandle  file,
std::string  name = "" 
)

Save the current state of the objects linked to the RMF file as the frameth frame.

The current frame is left as the passed frame number.

void IMP::rmf::save_frame ( RMF::FileHandle  file,
unsigned  int,
std::string  name = "" 
)
Deprecated:
As of IMP release 2.2. See the IMP Deprecation Policy for more information about deprecation in IMP. You cannot specify the frame. Drop it.

Definition at line 42 of file frames.h.

void IMP::rmf::set_maximum_number_of_terms ( RMF::FileHandle  fh,
unsigned int  num 
)

Certain restraint are made from a really large number of terms. Tracking and displaying all those terms can be very time consuming. If the number of terms is larger than the maximum, the terms are not displayed. By default this is 100.