Detailed Description

This module provides a divide and conquer sampler. It provides a simpler interface and (hopefully) faster performance than the original IMP.domino module.

This module provides a sampler which finds good solutions over a discrete sampling space. That is given

a set of criteria for defining a good model (encoded via SubsetFilter objects)
and a list of possible states for each particle of the model that is allowed to change (encoded via ParticleStates),

it finds all configurations of the model that can be expressed as a combination of the provided particle states and are accepted by the filters.

The criteria that can be filtered on can be any aspect that can be measured on a subset of the particles. Provided examples include

accepting only models where a certain restraint has a score that is less than the threshold specified for it in the Model (RestraintScoreSubsetFilterTable)
accepting only models where no two particles are in the same state (PermutationSubsetFilterTable)

The key idea underpinning all the sampling is that of dividing the set of all optimized particles into subsets (each represented using a Subset object). Good conformations for these subsets are found which are then combined together to produce the score for the whole model. A conformation is represented using a SubsetState object.

The idea of a Table is used in several places in the module. A Table, here, is an object which, for example, knows how to create a an object which can filter the subset states of a particular subset. That is, a SubsetFilterTable knows how to create a SubsetFilter (via the SubsetFilterTable::get_subset_filter() ) which can answer queries about whether a particular SubsetState is OK (via the SubsetFilter::get_is_ok() method). This makes it easy to perform preprocessing to make the SubsetFilter::get_is_ok() calls faster. The table idea is usedf with ParticleStatesTable, SubsetStatesTable and SubsetFilterTable.

Implementation todo list:

replace Subset with something that uses a memory pool if allocation becomes an issue
have a central table which lists dofs left for each particle, if any node can't find a state with the particle in a given state, it is removed from the list
make things work with particles that are a function of multiple optimized particles (eg centroids). Lots of things will have to change.
provide a means to filter a node based on already enumerated tables for adjacent nodes, this can probably be subsumed by the global allowed particle states table

Examples:

Author(s)

Daniel Russel, Keren Lasker

Version

SVN 8931:8938

License:

LGPL

Publications:

Daniel Russel, Keren Lasker, Ben Webb, Dina Schneidman, Javier Velázquez-Muriel, Andrej Sali, “Integrative assembly modeling using IMP”, submitted, 2010. This paper provides an overview of the key concepts in IMP and how to apply them to biological problems.
Frank Alber, Friedrich Foerster, Dmitry Korkin, Maya Topf, Andrej Sali, “Integrating diverse data for structure determination of macromolecular assemblies”, Annual Review of Biochemistry, 2008. This paper provides a review of the integrative structure determination methodology and various data sources that can be used.

Data Structures
class	BranchAndBoundSampler
	Sample best solutions using BranchAndBound. More...
class	BranchAndBoundSubsetStatesTable
class	CompoundStates
class	DiscreteSampler
	A base class for discrete samplers in Domino2. More...
class	DisjointSetsSubsetFilterTable
	A base class. More...
class	DominoSampler
	Sample best solutions using Domino. More...
class	EqualitySubsetFilterTable
	Do not allow two particles to be in the same state. More...
class	EquivalenceSubsetFilterTable
	Define sets of equivalent particles. More...
class	ExclusionSubsetFilterTable
	Do not allow two particles to be in the same state. More...
class	IndexStates
class	ListSubsetFilterTable
	Maintain an explicit list of what states each particle is allowed to have. More...
class	ListSubsetStatesTable
class	OptimizeRestraints
class	ParticleStates
class	ParticleStatesTable
class	RecursiveStates
class	RestraintScoreSubsetFilter
class	RestraintScoreSubsetFilterTable
	Filter a configuration of the subset using the Model thresholds. More...
class	RigidBodyStates
class	Subset
	Represent a subset of the particles being optimized. More...
class	SubsetFilter
class	SubsetFilterTable
class	SubsetState
	Store a configuration of a subset. More...
class	SubsetStatesTable
class	XYZStates
Typedefs
typedef boost::graph	InteractionGraph
typedef boost::graph	SubsetGraph
Functions
std::string	get_data_path (std::string file_name)
	Return the path to installed data for this module.
std::string	get_example_path (std::string file_name)
	Return the path to installed example data for this module.
Ints	get_index (const ParticlesTemp &particles, const Subset &subset, const Subsets &excluded)
SubsetGraph	get_junction_tree (const InteractionGraph &ig)
std::string	get_module_name ()
const VersionInfo &	get_module_version_info ()
Ints	get_order (const Subset &s, const SubsetFilterTables &sft)
Ints	get_partial_index (const ParticlesTemp &particles, const Subset &subset, const Subsets &excluded)
SubsetGraph	get_restraint_graph (RestraintSet rs, const ParticleStatesTable pst)
SubsetStates	get_state_clusters (const Subset &subset, const SubsetStates &states, ParticleStatesTable *pst, double resolution)
Subsets	get_subsets (const SubsetGraph &g)
	Gets all of the Subsets of a SubsetGraph.

InteractionGraph	get_interaction_graph (RestraintSet rs, const ParticleStatesTable pst)
display::Geometries	get_interaction_graph_geometry (const InteractionGraph &ig)
display::Geometries	get_subset_graph_geometry (const SubsetGraph &ig)
Debug tools
We provide a number of different functions for helpering optimize and understand domino-based sampling. These functions are expose part of the implementation and are liable to change without notice.
ParticlesTemp	get_dependent_particles (Particle *p)
ParticlesTemp	get_dependent_particles (Particle *p, const DependencyGraph &dg)
void	load_particle_states (const Subset &s, const SubsetState &ss, const ParticleStatesTable *pst)
RestraintsTemp	get_restraints (const Subset &s, const ParticleStatesTable pst, const DependencyGraph &dg, RestraintSet rs)

Typedef Documentation

typedef boost::graph IMP::domino::InteractionGraph

An undirected graph with one vertex per particle of interest. Two particles are connected by an edge if a Restraint or ScoreState creates and interaction between the two particles.

See Graphs in IMP for more information.

typedef boost::graph IMP::domino::SubsetGraph

A directed graph on subsets of vertices. Each vertex is named with an Subset.

Function Documentation

std::string IMP::domino::get_data_path ( std::string file_name )

Return the path to installed data for this module.

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 tools/imppy.sh script.

ParticlesTemp IMP::domino::get_dependent_particles ( Particle * p )

Returns the subset of particles that depend on p as input. This will include p.

Note:: This function is here to aid in debugging of optimization protocols that use Domino2. As a result, its signature and functionality may change without notice.

ParticlesTemp IMP::domino::get_dependent_particles	(	Particle *	p,
		const DependencyGraph &	dg
	)

Returns the subset of particles that depend on p as input. This will include p.

Note:: This function is here to aid in debugging of optimization protocols that use Domino2. As a result, its signature and functionality may change without notice.

std::string IMP::domino::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

    IMP::atom::read_pdb(IMP::atom::get_example_path("example_protein.pdb", model));

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

Ints IMP::domino::get_index	(	const ParticlesTemp &	particles,
		const Subset &	subset,
		const Subsets &	excluded
	)

If the passed particles are all contained in the Subset and are not contained any of the Subsets in excluded, then return a a list of indices given the location of each passed particle in the passed subset. That is

    particles[i]==subset[returned[i]];

Otherwise return an empty list.

This function is designed to be used for implementing SubsetFilterTable classes.

InteractionGraph IMP::domino::get_interaction_graph	(	RestraintSet *	rs,
		const ParticleStatesTable *	pst
	)

Compute the interaction graph of the restraints and the specified particles. The dependency graph in the model is traversed to determine how the passed particles relate to the actual particles read as input by the model. For example, if particles contains a rigid body, then an restraint which uses a member of the rigid body will have an edge from the rigid body particle.

Note:: This function is here to aid in debugging of optimization protocols that use Domino2. As a result, its signature and functionality may change without notice.

display::Geometries IMP::domino::get_interaction_graph_geometry ( const InteractionGraph & ig )

Assuming that all the particles have Cartesian coordinates, output edges corresponding to the edges in the interaction graph. The edges are named by the restraint which induces them.

SubsetGraph IMP::domino::get_junction_tree ( const InteractionGraph & ig )

Compute the exact junction tree for an interaction graph. The resulting graph has the junction tree properties

it is a tree
for any two vertices whose subsets both contain a vertex, that vertex is contained in all subsets along the path connecting those two vertices.

Ints IMP::domino::get_order	(	const Subset &	s,
		const SubsetFilterTables &	sft
	)

Return the order computed for the particles in the subset to be used for enumeration. This function is there in order to expose internal functionality for easier testing and should not be depended upon.

Ints IMP::domino::get_partial_index	(	const ParticlesTemp &	particles,
		const Subset &	subset,
		const Subsets &	excluded
	)

All of the passed particles are not contained in an ofthe Subsets in excluded, then return a a list of indices given the location of each passed particle in the passed subset or -1 if it is missing.

This function is designed to be used for implementing SubsetFilterTable classes.

SubsetGraph IMP::domino::get_restraint_graph	(	RestraintSet *	rs,
		const ParticleStatesTable *	pst
	)

The restraint graph is formed by having one node per restraint and an edge connecting two restraints if they share input particles. The associated Subsets are the set of input particles for the restraint, projected onto ps.

Note:: The graph for the optimized restraints (after temporary application of OptimizeContainers and OptimizeRestraints) is returned.

RestraintsTemp IMP::domino::get_restraints	(	const Subset &	s,
		const ParticleStatesTable *	pst,
		const DependencyGraph &	dg,
		RestraintSet *	rs
	)

Return a list of all restraints from rs that

do not depend on any particle in pst->get_particles() that is not in s The dependency graph is passed for efficiency.

SubsetStates IMP::domino::get_state_clusters	(	const Subset &	subset,
		const SubsetStates &	states,
		ParticleStatesTable *	pst,
		double	resolution
	)

Return subset of the passed states which are representative. The states for each particle is clustered and then the passed states are reduced to only be on the centers of that clustering.

The XYZ coordinates are used for clustering, there is not currently a nice mechanism to vary this, but it should be figured out. Probably by subclasses statistics::Embedding to statistics::ParticleEmbedding which has a method which takes a particle.

display::Geometries IMP::domino::get_subset_graph_geometry ( const SubsetGraph & ig )

Display the subsets of a subset graph, superimposed on the 3D coordinates of the particles.

void IMP::domino::load_particle_states	(	const Subset &	s,
		const SubsetState &	ss,
		const ParticleStatesTable *	pst
	)

Load the appropriate state for each particle in a Subset.

IMP::domino Namespace Reference