ms_treecluster Class Reference [Mascot utilities and tools module]

This class is an interface to the cluster algorithm described at http://bonsai.hgc.jp/~mdehoon/software/cluster/. More...

#include <ms_treecluster.hpp>

Inheritance diagram for ms_treecluster:

Collaboration diagram for ms_treecluster:

List of all members.

Public Types
enum	TREE_CLUSTER_DISTANCE {   TCD_CORRELATION,   TCD_ABS_CORRELATION,   TCD_UNCENTERED_CORRELATION,   TCD_ABS_UNCENTERED_CORRELATION,   TCD_SPEARMANS_RANK_CORRELATION,   TCD_KENDALLS_TAU_CORRELATION,   TCD_EUCLIDEAN,   TCD_CITY_BLOCK }
	Flags for cluster(). More...
Public Member Functions
	ms_treecluster (int rows, int columns)
	Constructor.
	ms_treecluster (const ms_treecluster &right)
	Copying constructor.
	~ms_treecluster ()
	Destructor.
void	appendErrors (const ms_errors &src)
	Copies all errors from another instance and appends them at the end of own list.
void	clearAllErrors ()
	Remove all errors from the current list of errors.
bool	cluster (TREE_CLUSTER_DISTANCE tcd, ms_mascotresults::TREE_CLUSTER_METHOD tcm, const std::vector< double > &weight, std::vector< int > &left, std::vector< int > &right, std::vector< double > &distance, bool transpose=false)
	Perform the clustering and populate the left, right and distance vectors with the results.
void	copyFrom (const ms_errors *right)
	Use this member to make a copy of another instance.
void	copyFrom (const ms_treecluster *right)
	Copies all data from another instance of the class.
void	defaultValues ()
	Initialises the instance.
const ms_errs *	getErrorHandler () const
	Retrive the error object using this function to get access to all errors and error parameters.
int	getLastError () const
	Return the error description of the last error that occurred.
std::string	getLastErrorString () const
	Return the error description of the last error that occurred.
bool	isValid () const
	Call this function to determine if there have been any errors.
ms_treecluster &	operator= (const ms_treecluster &right)
	Assignment operator.
bool	setRow (int row, std::vector< double > datarow, std::vector< int > maskrow)
	Sets the values for the specified row in the data and mask arrays.

---

Detailed Description

This class is an interface to the cluster algorithm described at http://bonsai.hgc.jp/~mdehoon/software/cluster/.

The License agreement for using this excellent Open Source code is included with Mascot Parser; see C Clustering library.

• To use this function, create an ms_treecluster object with the required number of rows and columns.
• Call ms_treecluster::setRow() for each row.
• Call ms_treecluster::cluster()
• Access the nodes and distances from the 'returned' left, right and distance parameters

---

Member Enumeration Documentation

enum TREE_CLUSTER_DISTANCE

Flags for cluster().

In order to cluster data into groups we need to define what exactly we mean by similar. In the C Clustering Library, eight distance functions are available to measure similarity, or conversely, distance.

See Using enumerated values and static const ints in Perl, Java, Python and C#.

Enumerator:

TCD_CORRELATION	'c': Pearson correlation coefficient
TCD_ABS_CORRELATION	'a': Absolute value of the Pearson correlation coefficient
TCD_UNCENTERED_CORRELATION	'u': Uncentered Pearson correlation (equivalent to the cosine of the angle between two data vectors)
TCD_ABS_UNCENTERED_CORRELATION	'x': Absolute uncentered Pearson correlation
TCD_SPEARMANS_RANK_CORRELATION	's': Spearman�s rank correlation;
TCD_KENDALLS_TAU_CORRELATION	'k': Kendall tau rank correlation coefficient
TCD_EUCLIDEAN	'e': Euclidean distance
TCD_CITY_BLOCK	'b': City-block distance

---

Constructor & Destructor Documentation

ms_treecluster	(	int	rows,
		int	columns
	)

Constructor.

Parameters:

rows	is the number of rows in the data
columns	is the number of columns in the data

---

Member Function Documentation

void appendErrors

(

const ms_errors &

src )

[inherited]

Copies all errors from another instance and appends them at the end of own list.

Parameters:

src	The object to copy the errors across from. See Maintaining object references: two rules of thumb.

void clearAllErrors

(

)

[inherited]

Remove all errors from the current list of errors.

The list of 'errors' can include fatal errors, warning messages, information messages and different levels of debugging messages.

All messages are accumulated into a list in this object, until clearAllErrors() is called.

See Error Handling.

See also:

isValid(), getLastError(), getLastErrorString(), getErrorHandler()

Examples:

common_error.cpp, resfile_error.cpp, and resfile_summary.cpp.

bool cluster	(	TREE_CLUSTER_DISTANCE	tcd,
		ms_mascotresults::TREE_CLUSTER_METHOD	tcm,
		const std::vector< double > &	weight,
		std::vector< int > &	left,
		std::vector< int > &	right,
		std::vector< double > &	distance,
		bool	transpose = false
	)

Perform the clustering and populate the left, right and distance vectors with the results.

Call this function after making rows calls to setRow()

For details of how to use the weight, left, right and distance parameters, see Using STL vector classes vectori, vectord and VectorString in Perl, Java, Python and C#.

The function returns a list of items, nodes and distances in the left, right and distance vectors.

The original elements are numbered {0, . . . , nelements-1} and the nodes are numbered {-1, . . . , -(nelements-1)}.

The left, right and distance vectors are guaranteed to have the same number of elements, and for example, left[2], right[2], distance[2] all correspond to the same 'node'.

Element 0 from each of the three vectors corresponds to node -1, element 1 to node -2, element 2 to node -3 etc.

See also ms_peptidesummary::getTreeClusterNodes

Parameters:

[in]	tcd	is used to define which method should be used as a measure of the distance between data items. See ms_treecluster::TREE_CLUSTER_DISTANCE.
[in]	tcm	Specifies which type of hierarchical clustering is used. See ms_mascotresults::TREE_CLUSTER_METHOD
[in]	weight	Dimension: columns (as passed to the constructor) if transpose is false, or rows (as passed to the constructor) if transpose is true. A zero length array is also accepted, in which case this is replaced by an array of 1s - i.e. all the same weight
[out]	left	returns an array, size rows -1 (as passed to the constructor) of element and node numbers
[out]	right	returns an array, size rows -1 (as passed to the constructor) of element and node numbers.
[out]	distance	returns an array, size rows -1 (as passed to the constructor) of distances between the elements/nodes
[in]	transpose	indicates whether row-wise or column-wise clustering is being performed. If transpose is false, rows are being clustered. Otherwise, columns are being clustered.

Returns:

false if the weight array is not of the correct size and false if there is insufficient memory for the arrays.

void copyFrom

(

const ms_treecluster *

right )

Copies all data from another instance of the class.

Called by copy constructor, or may be called directly.

Parameters:

right

is the object to copy values from

void copyFrom

(

const ms_errors *

right )

[inherited]

Use this member to make a copy of another instance.

Parameters:

right

is the source to initialise from

void defaultValues

(

)

Initialises the instance.

Allocates internal memory based on the number of rows and columns passed to the constructor

const ms_errs * getErrorHandler

(

)

const [inherited]

Retrive the error object using this function to get access to all errors and error parameters.

See Error Handling.

Returns:

Constant pointer to the error handler

See also:

isValid(), getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples:

common_error.cpp, and http_helper_getstring.cpp.

int getLastError

(

)

const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

See Error Handling.

See also:

isValid(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Returns:

the error number of the last error, or 0 if there have been no errors.

Reimplemented in ms_mascotresfile.

std::string getLastErrorString

(

)

const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

Returns:

Most recent error, warning, information or debug message

See Error Handling.

See also:

isValid(), getLastError(), clearAllErrors(), getErrorHandler()

Reimplemented in ms_mascotresfile.

Examples:

common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, and tools_aahelper.cpp.

bool isValid

(

)

const [inherited]

Call this function to determine if there have been any errors.

This will return true unless there have been any fatal errors.

See Error Handling.

Returns:

True if no fatal error occured

See also:

getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples:

common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, peptide_list.cpp, resfile_summary.cpp, and tools_aahelper.cpp.

ms_treecluster & operator=

(

const ms_treecluster &

right )

Assignment operator.

Used from C++

Parameters:

right

is the object to copy values from

Returns:

reference to the current object

bool setRow	(	int	row,
		std::vector< double >	datarow,
		std::vector< int >	maskrow
	)

Sets the values for the specified row in the data and mask arrays.

For details of how to use the datarow and maskrow parameters, see Using STL vector classes vectori, vectord and VectorString in Perl, Java, Python and C#.

Parameters:

row	is the zero based row number. Must be in the range 0..rows-1 passed to the constructor
datarow	is an array of the data points for the specified row. The length of the datarow array must be the same as columns passed to the constructor.
maskrow	is an array which specifies which elements in the data array, (if any), are missing. If mask[i][j]==0, then data[i][j] is missing. An empty array may be passed to show that no elements in the data array are missing. However, if a non empty array is passed, then the length of the maskrow array must be the same as columns passed to the constructor.

Returns:

The function will return false if any of the following are true:

• the row value is less than 0 or greater than or equal the rows value passed to the constructor.
• the number of values in the datarow parameter is not the same as the columns parameter passed to the constructor.
• the number of values in the maskrow parameter is not the same as the rows parameter passed to the constructor or is zero.
• there was an out of memory error.

---

The documentation for this class was generated from the following files:

• ms_treecluster.hpp
• ms_treecluster.cpp