The standard decorator for manipulating molecular structures. More...

#include <IMP/atom/Hierarchy.h>

Inheritance diagram for IMP::atom::Hierarchy:

Public Member Functions
	Hierarchy (Particle *p)

	Hierarchy (Model *m, ParticleIndex pi)

	Hierarchy ()
	null constructor

	Hierarchy (IMP::core::Hierarchy h)
	The traits must match.

void	add_child (Hierarchy o)
	Add a child and check that the types are appropriate. More...

Hierarchy	get_child (unsigned int i) const

Hierarchies	get_children () const
	Return the children in the order they were added.

template<class C >
C	get_children () const
	Get the children in a container of your choosing, eg ParticlesTemp.

bool	get_is_valid (bool print_info) const
	Return true if the hierarchy is valid. More...

Hierarchy	get_parent () const

void	show (std::ostream &out=std::cout) const

Public Member Functions inherited from IMP::core::Hierarchy
	Hierarchy (Model *m, ParticleIndex id, const HierarchyTraits &tr)

	Hierarchy (::IMP::kernel::Particle *p, const HierarchyTraits &tr=get_default_traits())

	Hierarchy (const HierarchyTraits &tr)

void	add_child (Hierarchy h) const

void	add_child_at (Hierarchy h, unsigned int pos)

void	clear_children ()

Hierarchy	get_child (unsigned int i) const

int	get_child_index () const

GenericHierarchies	get_children () const

const DecoratorTraits &	get_decorator_traits () const

unsigned int	get_number_of_children () const

Hierarchy	get_parent () const

const HierarchyTraits &	get_traits () const

void	remove_child (unsigned int i)

void	remove_child (Hierarchy h)

void	show (std::ostream &out=std::cout) const

Public Member Functions inherited from IMP::kernel::Decorator
ParticleIndex	get_particle_index () const

Particle *	get_particle () const

Model *	get_model () const
	Returns the Model containing the particle.

	Decorator (Particle *p)

	Decorator ()

Static Public Member Functions
static Hierarchy	decorate_particle (Particle *p)
	cast a particle which has the needed attributes

static const IMP::core::HierarchyTraits &	get_traits ()
	Get the molecular hierarchy HierararchyTraits.

static bool	particle_is_instance (Particle *p)

static bool	particle_is_instance (Model *m, ParticleIndex p)

static Hierarchy	setup_particle (Particle *p, const ParticlesTemp &children)

static Hierarchy	setup_particle (Model *m, ParticleIndex pi, const ParticlesTemp &children=ParticlesTemp())

static Hierarchy	setup_particle (Particle *p)

Static Public Member Functions inherited from IMP::core::Hierarchy
static Hierarchy	decorate_particle (::IMP::kernel::Particle *p, const HierarchyTraits &tr=get_default_traits())

static const DecoratorTraits &	get_default_decorator_traits ()

static const HierarchyTraits &	get_default_traits ()
	Get the default hierarchy traits.

static bool	particle_is_instance (Particle *, HierarchyTraits=Hierarchy::get_default_traits())

static Hierarchy	setup_particle (Particle *p, HierarchyTraits traits=Hierarchy::get_default_traits())
	Add the needed attributes to a particle.

static Hierarchy	setup_particle (Particle *p, const Particles &children, HierarchyTraits traits=Hierarchy::get_default_traits())
	Add the needed attributes to a particle and add the particles as children. More...

Static Public Member Functions inherited from IMP::kernel::Decorator
static bool	particle_is_instance (Particle *p)
	Return true if the particle can be cast to the decorator. More...

Related Functions
(Note that these are not member functions.)
Hierarchy	create_clone (Hierarchy d)
	Clone the Hierarchy. More...

Hierarchy	create_clone_one (Hierarchy d)
	Clone the node in the Hierarchy. More...

Restraint *	create_excluded_volume_restraint (const Hierarchies &hs, double resolution=-1)

Hierarchy	create_fragment (const Hierarchies &ps)
	Create a fragment containing the specified nodes. More...

Hierarchy	create_protein (Model *m, std::string name, double resolution, int number_of_residues, int first_residue_index=0, double volume=-1)
	Create a coarse grained molecule. More...

void	destroy (Hierarchy d)
	Delete the Hierarchy. More...

Atom	get_atom (Residue rd, AtomType at)
	Return a particle atom from the residue. More...

algebra::Sphere3D	get_bounding_sphere (const Hierarchy &h)

Hierarchies	get_by_type (Hierarchy mhd, GetByType t)

HierarchyTree	get_hierarchy_tree (Hierarchy h)

Hierarchies	get_leaves (const Selection &h)

Hierarchies	get_leaves (Hierarchy h)

Hierarchies	get_leaves (const Hierarchies &h)

Residue	get_residue (Atom d, bool nothrow=false)
	Return the Residue containing this atom. More...

Hierarchy	get_residue (Hierarchy mhd, unsigned int index)
	Get the residue with the specified index. More...

Hierarchy	get_root (Hierarchy h)
	Return the root of the hierarchy. More...

void	setup_as_approximation (Hierarchy h)

void	show (Hierarchy h, std::ostream &out=std::cout)
	Print out a molecular hierarchy.

Related Functions inherited from IMP::core::Hierarchy
template<class HD , class F >
HD	find_breadth_first (HD h, F f)
	Find the first node which matches some criteria.

template<class H , class Out , class F >
Out	gather (H h, F f, Out out)
	Gather all the particles in the hierarchy which meet some criteria.

template<class H , class Out , class K , class V >
Out	gather_by_attribute (H h, K k, V v, Out out)
	Gather all the particles in the hierarchy which match on an attribute.

template<class H , class Out , class K0 , class V0 , class K1 , class V1 >
Out	gather_by_attributes (H h, K0 k0, V0 v0, K1 k1, V1 v1, Out out)
	Gather all the particles in the hierarchy which match on two attributes.

template<class H , class Out , class F >
Out	gather_slice (H h, F f, Out out)
	Gather all the particles in the hierarchy which meet some criteria. More...

GenericHierarchies	get_all_descendants (Hierarchy mhd)
	Get all the particles in the subtree.

GenericHierarchies	get_internal (Hierarchy mhd)
	Get all the non-leaves of the bit of hierarchy.

GenericHierarchies	get_leaves (Hierarchy mhd)
	Get all the leaves of the bit of hierarchy. More...

Hierarchy	get_root (Hierarchy h)
	Return the root of the hierarchy. More...

template<class ND >
std::ostream &	show (Hierarchy h, std::ostream &out=std::cout)
	Print the hierarchy using a given decorator as to display each node. More...

template<class HD , class F >
F	visit_breadth_first (HD d, F f)
	Apply the visitor to each particle, breadth first. More...

template<class HD , class F >
F	visit_breadth_first_with_data (HD d, F f, typename F::result_type i)
	Apply functor F to each particle, traversing the hierarchy breadth first. More...

template<class HD , class F >
F	visit_depth_first (HD d, F f)
	Apply functor F to each particle, traversing the hierarchy depth first. More...

template<class HD , class F >
F	visit_depth_first_with_data (HD d, F f, typename F::result_type i)
	Apply functor F to each particle, traversing the hierarchy depth first. More...

Methods to get associated decorators
We provide a number of helper methods to get associated decorators for the current node in the hierarchy. As an example, if the particle decorated by this decorator is a Residue particle, then get_as_residue() return Residue(get_particle()), if not it returns Residue().
Atom	get_as_atom () const

Residue	get_as_residue () const

Chain	get_as_chain () const

Molecule	get_as_molecule () const

Domain	get_as_domain () const

Fragment	get_as_fragment () const

core::XYZ	get_as_xyz () const

core::XYZR	get_as_xyzr () const

Mass	get_as_mass () const

PDB Reading
The read PDB methods produce a hierarchy that looks as follows: One Atom per ATOM or HETATM record in the PDB. All Atom particles have a parent which is a Residue. All Residue particles have a parent which is a Chain. Waters are currently dropped if they are ATOM records. This can be fixed. The read_pdb() functions should successfully parse all valid pdb files. It can produce warnings on files which are not valid. It will attempt to read such files, but all bets are off. When reading PDBs, PDBSelector objects can be used to choose to only process certain record types. See the class documentation for more information. When no PDB selector is supplied for reading, the NonWaterPDBSelector is used. Set the IMP::LogLevel to VERBOSE to see details of parse errors.
Hierarchy	read_pdb (base::TextInput input, Model model, PDBSelector selector, bool select_first_model=true)

Additional Inherited Members
Public Types inherited from IMP::core::Hierarchy
typedef HierarchyTraits	DecoratorTraits

typedef Decorator	DecoratorTraitsBase

Protected Member Functions inherited from IMP::kernel::Decorator
	Decorator (Model *m, ParticleIndex pi)

	Decorator (Particle *p)

Detailed Description

IMP represents molecular structures using the Hierachy decorator. Molecules and collections of molecules each are stored as a hierarchy (or tree) where the resolution of the representation increases as you move further from the root. That is, if a parent has some particular property (eg, marks out a volume by having a x,y,z coordinates and a radius), then the children should have a higher resolution form of that information (eg, mark out a more detailed excluded volume by defining a set of balls which having approximately the same total volume).

Tree Basics

In a tree you have a set of nodes, represented by Hierarchy particles. Each node can have a node can have at most one parent. The node with no parent is known as the root of the tree.

Here is a simple example with a protein with three residues. Two of the residues have atoms, where as the third is coarse grained.

The nodes in the hierarchy can correspond to arbitrary bits of a molecule and do not need to have any biological significant. For example we could introduce a fragment containing residues 0 and 1:

A hierarchy can have any tree structure as long as:

the type of the parent makes sense for the child: eg a Residue cannot be the parent of a Chain.
the leaves always have coordinates, radius and mass
all particles in hierarchy are from the same model
all Atoms has a Residue for as parent
any Atom with a non-heterogen atom type is part of a protein, DNA or RNA molecule.
all Residue children of a particle appear in order based on their index
all Atom children in of a particle appear in order of their AtomType

The get_is_valid() method checks some of these properties. Any method taking a hierarchy as an argument should do

IMP_USAGE_CHECK(h.get_is_valid(), "Invalid hierarchy as input");

to make sure the hierarchy makes sense.

A number of decorator types are associated with the Hierarchy to store the information associated with that node in the hierarchy. Examples include Residue, Atom, XYZ, Chain, XYZR, Mass, Domain, Molecule etc. We provide a get_as_x() function for each such decorator which returns either X() (a null type) if the node is not a particle of type x, or an X decorator wrapping the current particle if it is.

See Also: Atom; Residue; Chain; Molecule; Domain; Fragment; Mass

Definition at line 209 of file atom/Hierarchy.h.

Member Function Documentation

void IMP::atom::Hierarchy::add_child ( Hierarchy o )

A child must have a type that is listed before the parent in the Type enum list.

Examples:: atom/dope_and_excluded_volume.cpp.

Definition at line 292 of file atom/Hierarchy.h.

Hierarchy IMP::atom::Hierarchy::get_child ( unsigned int i ) const

Get the ith child based on the order they were added.

Definition at line 298 of file atom/Hierarchy.h.

bool IMP::atom::Hierarchy::get_is_valid ( bool print_info ) const

Print information about the hierarchy if print_info is true and things are invalid.

Note: Returning true only means that no problems were found, it can't check everything.

Hierarchy IMP::atom::Hierarchy::get_parent ( ) const

Get the parent particle.

Definition at line 322 of file atom/Hierarchy.h.

static bool IMP::atom::Hierarchy::particle_is_instance ( Particle * p )

static

Check if the particle has the needed attributes for a cast to succeed

Definition at line 274 of file atom/Hierarchy.h.

static Hierarchy IMP::atom::Hierarchy::setup_particle	(	Model *	m,
		ParticleIndex	pi,
		const ParticlesTemp &	children = `ParticlesTemp()`
	)

static

Create a Hierarchy of level t by adding the needed attributes.

Definition at line 252 of file atom/Hierarchy.h.

Here is the call graph for this function:

Friends And Related Function Documentation

Hierarchy create_clone ( Hierarchy d )

Hierarchy create_clone_one ( Hierarchy d )

Restraint * create_excluded_volume_restraint	(	const Hierarchies &	hs,
		double	resolution = `-1`
	)

If one or more of the selections is a rigid body, this will be used to accelerate the computation.

Hierarchy create_protein	(	Model *	m,
		std::string	name,
		double	resolution,
		int	number_of_residues,
		int	first_residue_index = `0`,
		double	volume = `-1`
	)

The coarse grained model is created with a number of spheres based on the resolution and the volume. If the volume is not provided it is estimated based on the number of residues. The protein is created as a molecular hierarchy rooted at p. The leaves are Domain particles with appropriate residue indexes stored and are XYZR particles.

Volume is, as usual, in cubic anstroms.

Currently the function creates a set of balls with radii no greater than resolution which overlap by 20% and have a volume of their union equal to the passed volume.

The coordinates of the balls defining the protein are optimized by default, and have garbage coordinate values.

Warning: create_protein has not been well tested yet: Use with caution and please report any bugs found.

Warning: create_protein has not been stabilized and is likely to change without notice.

void destroy ( Hierarchy d )

Atom get_atom	(	Residue	rd,
		AtomType	at
	)

algebra::Sphere3D get_bounding_sphere ( const Hierarchy & h )

HierarchyTree get_hierarchy_tree ( Hierarchy h )

Hierarchies get_leaves ( const Selection & h )

Hierarchies get_leaves ( const Hierarchies & h )

Residue get_residue	(	Atom	d,
		bool	nothrow = `false`
	)

Exceptions

ValueException if no residue is found, unless nothrow is true.

Hierarchy get_root ( Hierarchy h )

void setup_as_approximation ( Hierarchy h )

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

Public Member Functions

Static Public Member Functions

Related Functions

Methods to get associated decorators

PDB Reading

Additional Inherited Members

Detailed Description

Tree Basics

Member Function Documentation

Friends And Related Function Documentation