Computation of clusters of docking poses. More...

#include <BALL/DOCKING/COMMON/poseClustering.h>

Classes
class	ClusterProperties

class	ClusterTreeNodeComparator

class	ClusterTreeWriter_

struct	Default
	Default values for options. More...

struct	Option
	Option names. More...

class	PosePointer

class	RigidTransformation

Public Member Functions
void	printClusters (std::ostream &out=std::cout) const

void	printClusterRMSDs (std::ostream &out=std::cout)

operation methods
bool	compute ()

Access methods
void	setConformationSet (ConformationSet *new_set)
	sets the poses to be clustered, the conformation set's reference system will the base system More...

void	setBaseSystemAndPoses (System const &base_system, std::vector< PosePointer > const &poses)

void	setBaseSystemAndTransformations (System const &base_system, String transformation_file_name)

const ConformationSet *	getConformationSet () const
	returns the poses to be clustered as ConformationSet More...

ConformationSet *	getConformationSet ()
	returns the poses to be clustered as ConformationSet More...

const System &	getSystem () const
	returns the reference pose More...

System &	getSystem ()
	returns the reference pose More...

Size	getNumberOfPoses () const
	returns the number of poses More...

Size	getNumberOfClusters () const
	returns the number of clusters found More...

const std::set< Index > &	getCluster (Index i) const

std::set< Index > &	getCluster (Index i)

Size	getClusterSize (Index i) const
	returns the size of cluster i More...

float	getClusterScore (Index i) const
	returns the score of cluster i More...

float	getScore (const System sys_a, const System sys_b, Options options) const
	returns the score between two poses given as systems More...

boost::shared_ptr< System >	getPose (Index i) const
	returns the pose i as system More...

boost::shared_ptr< System >	getClusterRepresentative (Index i) const
	returns the first conformation of cluster i as system More...

boost::shared_ptr < ConformationSet >	getClusterConformationSet (Index i)
	returns cluster i as ConformationSet More...

boost::shared_ptr < ConformationSet >	getReducedConformationSet ()
	returns a ConformationSet containing one structure per cluster More...

bool	refineClustering (Options const &refined_options)

methods given a full clustering
std::vector< std::set< Index > >	extractClustersForThreshold (float threshold)

std::vector< std::set< Index > >	extractNBestClusters (Size n)

void	exportWardClusterTree (std::ostream &out)

Static Public Member Functions
rigid transformation methods
static float	getRigidRMSD (Eigen::Vector3f const &t_ab, Eigen::Matrix3f const &M_ab, Eigen::Matrix3f const &covariance_matrix)

static float	getSquaredRigidRMSD (Eigen::Vector3f const &t_ab, Eigen::Matrix3f const &M_ab, Eigen::Matrix3f const &covariance_matrix)

static Eigen::Matrix3f	computeCovarianceMatrix (System const &system, Index rmsd_level_of_detail=C_ALPHA)

Protected Member Functions
bool	trivialCompute_ ()

bool	linearSpaceCompute_ ()

void	slinkInner_ (int current_level)

void	clinkInner_ (int current_level)

bool	nearestNeighborChainCompute_ ()

void	initWardDistance_ (Index rmsd_type)

void	updateWardDistance_ (ClusterTreeNode parent, ClusterTreeNode i, ClusterTreeNode j, Index rmsd_type)

float	computeWardDistance_ (ClusterTreeNode i, ClusterTreeNode j, Index rmsd_type)

std::set< Index >	collectClusterBelow_ (ClusterTreeNode const &v)

void	computeCenterOfMasses_ ()

void	precomputeAtomBijection_ ()

float	getClusterRMSD_ (Index i, Index j, Index rmsd_type)

bool	readTransformationsFromFile_ (String filename)

float	getRMSD_ (Index i, Index j, Index rmsd_type)

void	storeSnapShotReferences_ ()

void	convertTransformations2Snaphots_ ()

void	convertSnaphots2Transformations_ ()

void	printCluster_ (Index i, std::ostream &out=std::cout) const

void	printVariables_ (int a, int b, double c, int d, double e, int current_level)

void	clear_ ()

Static Protected Member Functions
static bool	isExcludedByLevelOfDetail_ (Atom const *atom, Index rmsd_level_of_detail)

Protected Attributes
Eigen::MatrixXd	pairwise_scores_

ConformationSet *	current_set_
	the ConformationSet we wish to cluster More...

std::vector< std::set< Index > >	clusters_
	the clusters: sets of pose indices More...

std::vector< float >	cluster_scores_
	the scores of the clusters More...

Index	rmsd_level_of_detail_
	the RMSD definition used for clustering More...

std::vector< PosePointer >	poses_

std::vector< RigidTransformation >	transformations_

Eigen::Matrix3f	covariance_matrix_

System	base_system_

SnapShot	base_conformation_

bool	has_rigid_transformations_

bool	delete_conformation_set_

std::vector< double >	lambda_

std::vector< int >	pi_

std::vector< double >	mu_

Size	number_of_selected_atoms_

std::vector< Vector3 >	com_

AtomBijection	atom_bijection_

System	system_i_

System	system_j_

ClusterTree	cluster_tree_
	The tree built during hierarchical clustering. More...

ClusterTreeNode	cluster_tree_root_

Constant Definitions
typedef boost::adjacency_list < boost::vecS, boost::vecS, boost::directedS, ClusterProperties >	ClusterTree

typedef ClusterTree::vertex_descriptor	ClusterTreeNode

	BALL_CREATE (PoseClustering)

	PoseClustering ()
	Default constructor. More...

	PoseClustering (ConformationSet *poses, float rmsd)

	PoseClustering (System const &base_system, String transformation_file_name)
	PoseClustering for a given set of rigid transformations of a base structure. More...

virtual	~PoseClustering ()

Public Attributes
Options	options
	options More...

void	setDefaultOptions ()

Detailed Description

Computation of clusters of docking poses.

Pose ClusteringThis class computes clusters of docking poses given as a conformation set using a complete linkage algorithm.

The class assumes the following setup

a pairwise rigid protein-protein docking
all receptor-ligand poses have already been mapped onto each other such that the "receptors" are kept fixed
the given pose set only contains the "ligands"

We offer several algorithms via the option CLUSTER_METHOD:

TRIVIAL_COMPLETE_LINKAGE: a naive implementation, that guarantees an optimal final partition.
CLINK_DEFAYS as described in D. Defays: An efficient algorithm for a complete link method. The Computer Journal. 20, 4, British Computer Society, 1977, p. 364-366. Please note that this implementation does not guarantee to find the best final clustering!
NEAREST_NEIGHBOR_CHAIN_WARD as described in Murtagh, Fionn (1983): "A survey of recent advances in hierarchical clustering algorithms", The Computer Journal 26 (4): 354–359 Note that this algorithm computes a full clustering.
SLINK_SIBSON as described in R. Sibson: SLINK: an optimally efficient algorithm for the single-link cluster method. The Computer Journal. 16, 1, British Computer Society, 1973, p. 30-34

The scope of the scoring (the atoms to be considered) can be defined via the option RMSD_LEVEL_OF_DETAIL. If the option is set to PROPERTY_BASED_ATOM_BIJECTION, arbitrary sets of atoms, e.g. binding pockets, can be used by assigning property named "ATOMBIJECTION_RMSD_SELECTION" to the respective atoms in the reference system. See also BALL::Expression.

The minimal rmsd or ward distance between the final clusters can be defined via option DISTANCE_THRESHOLD. In order to relate RMSD and ward distance, we use sqrt(ward_dist / number_of_selected_atoms) for threshold extraction.

The nearest neighbor chain ward clustering in principle computes a full clustering. Option DISTANCE_THRESHOLD gives a ward distance that is automatically used to extract clusters. Further extractions with different thresholds are possible.

The complete linkage algorithms guarantee a minimal cluster distance (max RMSD between all pairs of two clusters), specified with option DISTANCE_THRESHOLD.

The initial poses can be given as ConformationSet or as transformation file, i.e. translation and rotation of each pose. Depending on this choice, the option RMSD_TYPE has to be set to SNAPSHOT_RMSD or RIGID_RMSD. If RMSD_TYPE is set to CENTER_OF_MASS_DISTANCE, the option RMSD_LEVEL_OF_DETAIL will be ignored.

Definition at line 108 of file poseClustering.h.

Member Typedef Documentation

typedef boost::adjacency_list<boost::vecS, boost::vecS, boost::directedS, ClusterProperties> BALL::PoseClustering::ClusterTree

Definition at line 242 of file poseClustering.h.

typedef ClusterTree::vertex_descriptor BALL::PoseClustering::ClusterTreeNode

Definition at line 244 of file poseClustering.h.

Constructor & Destructor Documentation

BALL::PoseClustering::PoseClustering ( )

Default constructor.

Constructors and Destructor

BALL::PoseClustering::PoseClustering	(	ConformationSet *	poses,
		float	rmsd
	)

Detailed constructor. (TODO: really pass a pointer here?)

BALL::PoseClustering::PoseClustering	(	System const &	base_system,
		String	transformation_file_name
	)

PoseClustering for a given set of rigid transformations of a base structure.

virtual BALL::PoseClustering::~PoseClustering ( )

virtual

Member Function Documentation

BALL::PoseClustering::BALL_CREATE ( PoseClustering )

void BALL::PoseClustering::clear_ ( )

protected

void BALL::PoseClustering::clinkInner_ ( int current_level )

protected

std::set<Index> BALL::PoseClustering::collectClusterBelow_ ( ClusterTreeNode const & v )

protected

bool BALL::PoseClustering::compute ( )

start method.

void BALL::PoseClustering::computeCenterOfMasses_ ( )

protected

static Eigen::Matrix3f BALL::PoseClustering::computeCovarianceMatrix	(	System const &	system,
		Index	rmsd_level_of_detail = `C_ALPHA`
	)

static

Compute the covariance matrix for the given system

float BALL::PoseClustering::computeWardDistance_	(	ClusterTreeNode	i,
		ClusterTreeNode	j,
		Index	rmsd_type
	)

protected

void BALL::PoseClustering::convertSnaphots2Transformations_ ( )

protected

void BALL::PoseClustering::convertTransformations2Snaphots_ ( )

protected

void BALL::PoseClustering::exportWardClusterTree ( std::ostream & out )

Export the cluster tree in graphviz format.

std::vector<std::set<Index> > BALL::PoseClustering::extractClustersForThreshold ( float threshold )

Extract clusters wrt a threshold if a complete clustering was performed Note: the Ward distance does not equal the rmsd. We use threshold = sqrt(ward_dist / number_of_selected_atoms). see NEAREST_NEIGHBOR_CHAIN_WARD

std::vector<std::set<Index> > BALL::PoseClustering::extractNBestClusters ( Size n )

returns the first n clusters if previously a complete clustering was performed see NEAREST_NEIGHBOR_CHAIN_WARD

const std::set<Index>& BALL::PoseClustering::getCluster ( Index i ) const

returns indices of all poses assigned to cluster i Note: enumeration starts with 0

std::set<Index>& BALL::PoseClustering::getCluster ( Index i )

returns indices of all poses assigned to cluster i Note: enumeration starts with 0

boost::shared_ptr<ConformationSet> BALL::PoseClustering::getClusterConformationSet ( Index i )

returns cluster i as ConformationSet

boost::shared_ptr<System> BALL::PoseClustering::getClusterRepresentative ( Index i ) const

returns the first conformation of cluster i as system

float BALL::PoseClustering::getClusterRMSD_	(	Index	i,
		Index	j,
		Index	rmsd_type
	)

protected

float BALL::PoseClustering::getClusterScore ( Index i ) const

returns the score of cluster i

Size BALL::PoseClustering::getClusterSize ( Index i ) const

returns the size of cluster i

const ConformationSet* BALL::PoseClustering::getConformationSet ( ) const

inline

returns the poses to be clustered as ConformationSet

Definition at line 294 of file poseClustering.h.

ConformationSet* BALL::PoseClustering::getConformationSet ( )

inline

returns the poses to be clustered as ConformationSet

Definition at line 297 of file poseClustering.h.

Size BALL::PoseClustering::getNumberOfClusters ( ) const

inline

returns the number of clusters found

Definition at line 309 of file poseClustering.h.

Size BALL::PoseClustering::getNumberOfPoses ( ) const

inline

returns the number of poses

Definition at line 306 of file poseClustering.h.

boost::shared_ptr<System> BALL::PoseClustering::getPose ( Index i ) const

returns the pose i as system

boost::shared_ptr<ConformationSet> BALL::PoseClustering::getReducedConformationSet ( )

returns a ConformationSet containing one structure per cluster

static float BALL::PoseClustering::getRigidRMSD	(	Eigen::Vector3f const &	t_ab,
		Eigen::Matrix3f const &	M_ab,
		Eigen::Matrix3f const &	covariance_matrix
	)

static

Compute the root mean square deviation due to a rigid transformation of a point cloud (here, atoms)

Parameters

t_ab	difference vector between the transformations to be compared
M_ab	difference of the rotation matrices between the transformations to be compared
covariance_matrix	the covariance matrix of the atom positions

float BALL::PoseClustering::getRMSD_	(	Index	i,
		Index	j,
		Index	rmsd_type
	)

protected

float BALL::PoseClustering::getScore	(	const System	sys_a,
		const System	sys_b,
		Options	options
	)		const

returns the score between two poses given as systems

static float BALL::PoseClustering::getSquaredRigidRMSD	(	Eigen::Vector3f const &	t_ab,
		Eigen::Matrix3f const &	M_ab,
		Eigen::Matrix3f const &	covariance_matrix
	)

static

Compute the mean square deviation due to a rigid transformation of a point cloud (here, atoms)

Parameters

t_ab	difference vector between the transformations to be compared
M_ab	difference of the rotation matrices between the transformations to be compared
covariance_matrix	the covariance matrix of the atom positions

const System& BALL::PoseClustering::getSystem ( ) const

returns the reference pose

System& BALL::PoseClustering::getSystem ( )

returns the reference pose

void BALL::PoseClustering::initWardDistance_ ( Index rmsd_type )

protected

static bool BALL::PoseClustering::isExcludedByLevelOfDetail_	(	Atom const *	atom,
		Index	rmsd_level_of_detail
	)

staticprotected

bool BALL::PoseClustering::linearSpaceCompute_ ( )

protected

bool BALL::PoseClustering::nearestNeighborChainCompute_ ( )

protected

void BALL::PoseClustering::precomputeAtomBijection_ ( )

protected

void BALL::PoseClustering::printCluster_	(	Index	i,
		std::ostream &	out = `std::cout`
	)		const

protected

void BALL::PoseClustering::printClusterRMSDs ( std::ostream & out = std::cout )

print clusters of pose indices with RMSD between clusters Note: start counting with 0

void BALL::PoseClustering::printClusters ( std::ostream & out = std::cout ) const

print the clusters as set of pose indices Note: start counting with 0

void BALL::PoseClustering::printVariables_	(	int	a,
		int	b,
		double	c,
		int	d,
		double	e,
		int	current_level
	)

protected

bool BALL::PoseClustering::readTransformationsFromFile_ ( String filename )

protected

bool BALL::PoseClustering::refineClustering ( Options const & refined_options )

Refine a given clustering. This function can be used to refine a precomputed clustering further. An important use case would be to pre-cluster using an efficient rmsd implementation (e.g., center of mass or rigid rmsd), and then refine the resulting clusters with the general (i.e., snapshot based) rmsd.

NOTE: This function requires that clusters have already been computed. In the case of a full hierarchical clustering, extractClustersForThreshold or extractNBestClusters must have been called previously.

Parameters

refined_options The parameters for the refinment step.

void BALL::PoseClustering::setBaseSystemAndPoses	(	System const &	base_system,
		std::vector< PosePointer > const &	poses
	)

Set a vector of PosePointers to be clustered Poses (RigidTransformations or SnapShots) can live outside of this class and will not be destroyed.

void BALL::PoseClustering::setBaseSystemAndTransformations	(	System const &	base_system,
		String	transformation_file_name
	)

reads the poses given as transformations from a file and update the covariance matrix Note: the given system will be taken as reference, e.g. all transformations

void BALL::PoseClustering::setConformationSet ( ConformationSet * new_set )

sets the poses to be clustered, the conformation set's reference system will the base system

void BALL::PoseClustering::setDefaultOptions ( )

reset the options to default values

void BALL::PoseClustering::slinkInner_ ( int current_level )

protected

void BALL::PoseClustering::storeSnapShotReferences_ ( )

protected

bool BALL::PoseClustering::trivialCompute_ ( )

protected

void BALL::PoseClustering::updateWardDistance_	(	ClusterTreeNode	parent,
		ClusterTreeNode	i,
		ClusterTreeNode	j,
		Index	rmsd_type
	)

protected

Member Data Documentation

AtomBijection BALL::PoseClustering::atom_bijection_

protected

Definition at line 595 of file poseClustering.h.

SnapShot BALL::PoseClustering::base_conformation_

protected

Definition at line 560 of file poseClustering.h.

System BALL::PoseClustering::base_system_

protected

Definition at line 557 of file poseClustering.h.

std::vector< float > BALL::PoseClustering::cluster_scores_

protected

the scores of the clusters

Definition at line 541 of file poseClustering.h.

ClusterTree BALL::PoseClustering::cluster_tree_

protected

The tree built during hierarchical clustering.

Definition at line 602 of file poseClustering.h.

ClusterTreeNode BALL::PoseClustering::cluster_tree_root_

protected

Definition at line 604 of file poseClustering.h.

std::vector< std::set<Index> > BALL::PoseClustering::clusters_

protected

the clusters: sets of pose indices

Definition at line 538 of file poseClustering.h.

std::vector<Vector3> BALL::PoseClustering::com_

protected

Definition at line 588 of file poseClustering.h.

Eigen::Matrix3f BALL::PoseClustering::covariance_matrix_

protected

Definition at line 554 of file poseClustering.h.

ConformationSet* BALL::PoseClustering::current_set_

protected

the ConformationSet we wish to cluster

Definition at line 535 of file poseClustering.h.

bool BALL::PoseClustering::delete_conformation_set_

protected

Definition at line 567 of file poseClustering.h.

bool BALL::PoseClustering::has_rigid_transformations_

protected

Definition at line 563 of file poseClustering.h.

std::vector<double> BALL::PoseClustering::lambda_

protected

Definition at line 573 of file poseClustering.h.

std::vector<double> BALL::PoseClustering::mu_

protected

Definition at line 579 of file poseClustering.h.

Size BALL::PoseClustering::number_of_selected_atoms_

protected

Definition at line 583 of file poseClustering.h.

Options BALL::PoseClustering::options

options

Definition at line 361 of file poseClustering.h.

Eigen::MatrixXd BALL::PoseClustering::pairwise_scores_

protected

Definition at line 532 of file poseClustering.h.

std::vector<int> BALL::PoseClustering::pi_

protected

Definition at line 577 of file poseClustering.h.

std::vector<PosePointer> BALL::PoseClustering::poses_

protected

Definition at line 549 of file poseClustering.h.

Index BALL::PoseClustering::rmsd_level_of_detail_

protected

the RMSD definition used for clustering

Definition at line 544 of file poseClustering.h.

System BALL::PoseClustering::system_i_

protected

Definition at line 598 of file poseClustering.h.

System BALL::PoseClustering::system_j_

protected

Definition at line 599 of file poseClustering.h.

std::vector<RigidTransformation> BALL::PoseClustering::transformations_

protected

Definition at line 552 of file poseClustering.h.

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Constant Definitions

Public Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation