IMP logo
IMP Reference Guide  develop.2de7fdb984,2019/11/19
The Integrative Modeling Platform
IMP::atom::Hierarchy Class Reference

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

#include <IMP/atom/Hierarchy.h>

+ Inheritance diagram for IMP::atom::Hierarchy:

Detailed Description

The standard decorator for manipulating molecular structures.

IMP represents molecular structures using the Hierarchy 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 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 have approximately the same total volume).

Tree Basics

In a tree you have a set of nodes, represented by Hierarchy particles. Each 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 significance. 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 the hierarchy are from the same model
  • all Atoms have a Residue as the 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 of a particle appear in order of their AtomType
  • if a node has residue indexes, all its descendants down to the residue level also do.

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.

Note
Deleting a Hierarchy, like deleting any decorator, will not delete the underlying Particle or remove any children. To do that, call destroy().
See Also
Atom
Residue
Chain
Molecule
Domain
Fragment
Mass
State
Representation

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

Public Member Functions

 Hierarchy (Model *m, ParticleIndex pi)
 
 Hierarchy (ParticleAdaptor pi)
 
 Hierarchy ()
 Null constructor. More...
 
 Hierarchy (IMP::core::Hierarchy h)
 The traits must match. More...
 
void add_child (Hierarchy o)
 Add a child and check that the types are appropriate. More...
 
Hierarchy get_child (unsigned int i) const
 Get the ith child based on the order they were added. More...
 
Hierarchies get_children () const
 Return the children in the order they were added. More...
 
template<class C >
get_children () const
 Get the children in a container of your choosing, eg ParticlesTemp. More...
 
bool get_is_valid (bool print_info=false) const
 Return true if the hierarchy is valid. More...
 
Hierarchy get_parent () const
 Get the parent particle. More...
 
void show (std::ostream &out=std::cout) const
 
- Public Member Functions inherited from IMP::core::Hierarchy
 Hierarchy (const IMP::ParticleAdaptor &d, const HierarchyTraits &tr=get_default_traits())
 
 Hierarchy (::IMP::Model *m,::IMP::ParticleIndex id, const HierarchyTraits &tr=get_default_traits())
 
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
 
ParticleIndex get_child_index (unsigned int i) const
 
int get_child_index () const
 Return i such that get_parent().get_child(i) == this More...
 
GenericHierarchies get_children () const
 
ParticleIndexes get_children_indexes () const
 
const DecoratorTraitsget_decorator_traits () const
 
unsigned int get_number_of_children () const
 
Hierarchy get_parent () const
 
HierarchyTraits get_traits ()
 
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::Decorator
bool get_is_valid () const
 Returns true if constructed with a non-default constructor. More...
 
Modelget_model () const
 Returns the Model containing the particle. More...
 
Particleget_particle () const
 Returns the particle decorated by this decorator. More...
 
ParticleIndex get_particle_index () const
 Returns the particle index decorated by this decorator. More...
 
 operator Particle * () const
 
 operator ParticleIndex () const
 
Particleoperator-> () const
 

Static Public Member Functions

static bool get_is_setup (Model *m, ParticleIndex p)
 Check if the particle has the needed attributes for a cast to succeed. More...
 
static const
IMP::core::HierarchyTraits
get_traits ()
 Get the molecular hierarchy HierarchyTraits. More...
 
static Hierarchy setup_particle (Model *m, ParticleIndex pi, ParticleIndexesAdaptor children=ParticleIndexesAdaptor())
 Create a Hierarchy of level t by adding the needed attributes. More...
 
- Static Public Member Functions inherited from IMP::core::Hierarchy
static const DecoratorTraitsget_default_decorator_traits ()
 
static const HierarchyTraitsget_default_traits ()
 Get the default hierarchy traits. More...
 
static bool get_is_setup (const IMP::ParticleAdaptor &p, const HierarchyTraits &tr=get_default_traits())
 
static bool get_is_setup (Model *, ParticleIndex, HierarchyTraits=Hierarchy::get_default_traits())
 
static Hierarchy setup_particle (IMP::ParticleAdaptor d, DecoratorTraits tr=get_default_decorator_traits())
 
static Hierarchy setup_particle (Model *m, ParticleIndex pi, DecoratorTraits tr=get_default_decorator_traits())
 
static Hierarchy setup_particle (Model *m, ParticleIndex pi, ParticleIndexes children, DecoratorTraits tr=get_default_decorator_traits())
 
static Hierarchy setup_particle (IMP::ParticleAdaptor d, ParticleIndexes children, DecoratorTraits tr=get_default_decorator_traits())
 
static Hierarchy setup_particle (IMP::ParticleAdaptor d, ParticlesTemp children, DecoratorTraits tr=get_default_decorator_traits())
 
static Hierarchy setup_particle (Model *m, ParticleIndex pi, ParticlesTemp children, DecoratorTraits tr=get_default_decorator_traits())
 

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...
 
Hierarchy create_fragment (const Hierarchies &ps)
 Create a fragment containing the specified nodes. More...
 
void destroy (Hierarchy d)
 Delete the Hierarchy. More...
 
algebra::BoundingBoxD< 3 > get_bounding_box (const Hierarchy &h)
 Get a bounding box for the Hierarchy. More...
 
algebra::Sphere3D get_bounding_sphere (const Hierarchy &h)
 
Hierarchies get_by_type (Hierarchy mhd, GetByType t)
 Gather all the molecular particles of a certain level in the hierarchy. More...
 
Bonds get_internal_bonds (Hierarchy mhd)
 Get the bonds internal to this tree. More...
 
bool get_is_heterogen (Hierarchy h)
 Return true if the piece of hierarchy should be classified as a heterogen. More...
 
Hierarchies get_leaves (Hierarchy h)
 
Hierarchies get_leaves (const Hierarchies &h)
 
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 show (Hierarchy h, std::ostream &out=std::cout)
 Print out a molecular hierarchy. More...
 

Additional Inherited Members

- Public Types inherited from IMP::core::Hierarchy
typedef HierarchyTraits DecoratorTraits
 
- Protected Member Functions inherited from IMP::Decorator
 Decorator (Model *m, ParticleIndex pi)
 
 Decorator (ParticleAdaptor p)
 

Constructor & Destructor Documentation

IMP::atom::Hierarchy::Hierarchy ( )

Null constructor.

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

IMP::atom::Hierarchy::Hierarchy ( IMP::core::Hierarchy  h)
explicit

The traits must match.

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

Member Function Documentation

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

Add a child and check that the types are appropriate.

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 270 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 280 of file atom/Hierarchy.h.

Hierarchies IMP::atom::Hierarchy::get_children ( ) const

Return the children in the order they were added.

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

template<class C >
C IMP::atom::Hierarchy::get_children ( ) const

Get the children in a container of your choosing, eg ParticlesTemp.

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

static bool IMP::atom::Hierarchy::get_is_setup ( Model m,
ParticleIndex  p 
)
static

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

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

+ Here is the call graph for this function:

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

Return true if the hierarchy is valid.

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 304 of file atom/Hierarchy.h.

static const IMP::core::HierarchyTraits& IMP::atom::Hierarchy::get_traits ( )
static

Get the molecular hierarchy HierarchyTraits.

static Hierarchy IMP::atom::Hierarchy::setup_particle ( Model m,
ParticleIndex  pi,
ParticleIndexesAdaptor  children = ParticleIndexesAdaptor() 
)
static

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

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

+ Here is the call graph for this function:

Friends And Related Function Documentation

Hierarchy create_clone ( Hierarchy  d)
related

Clone the Hierarchy.

This method copies the Bond, Bonded, Atom, Residue, Domain, Mass, and provenance data and the particle name to the new copies in addition to the Hierarchy relationships.

Hierarchy create_clone_one ( Hierarchy  d)
related

Clone the node in the Hierarchy.

This method copies the Atom, Residue, Chain, Domain, Mass, and provenance data and the particle name.

Hierarchy create_fragment ( const Hierarchies ps)
related

Create a fragment containing the specified nodes.

A particle representing the fragment is created and initialized.

The Fragment is inserted as a child of the parent (and the particles are removed). The particles become children of the fragment.

Exceptions
ValueExceptionIf all the particles do not have the same parent.
void destroy ( Hierarchy  d)
related

Delete the Hierarchy.

All bonds connecting to these atoms are destroyed as are hierarchy links in the Hierarchy and the particles are removed from the Model. If this particle has a parent, it is removed from the parent. Any provenance information for this Hierarchy is also removed.

algebra::BoundingBoxD< 3 > get_bounding_box ( const Hierarchy h)
related

Get a bounding box for the Hierarchy.

This bounding box is that of the highest (in the CS sense of a tree growing down from the root) cut through the tree where each node in the cut has x,y,z, and r. That is, if the root has x,y,z,r then it is the bounding box of that sphere. If only the leaves have radii, it is the bounding box of the leaves. If no such cut exists, the behavior is undefined.

See Also
IMP::algebra::BoundingBoxD
algebra::Sphere3D get_bounding_sphere ( const Hierarchy h)
related

See get_bounding_box() for more details.

Hierarchies get_by_type ( Hierarchy  mhd,
GetByType  t 
)
related

Gather all the molecular particles of a certain level in the hierarchy.

Bonds get_internal_bonds ( Hierarchy  mhd)
related

Get the bonds internal to this tree.

See Also
Bond
bool get_is_heterogen ( Hierarchy  h)
related

Return true if the piece of hierarchy should be classified as a heterogen.

For the purposes of classification, a heterogen is anything that

  • is a heterogen atom (one whose name starts with HET:)
  • is or is part of a Residue that is not a normal protein, rna or dna residue
  • or is not part of a Chain

For the moment, this can only be called on residues or atoms.

Hierarchies get_leaves ( Hierarchy  h)
related

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

+ Here is the call graph for this function:

Hierarchies get_leaves ( const Hierarchies h)
related

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

+ Here is the call graph for this function:

Hierarchy get_residue ( Hierarchy  mhd,
unsigned int  index 
)
related

Get the residue with the specified index.

Find the leaf containing the residue with the appropriate index. This is the PDB index, not the offset in the chain (if they are different).

The function returns a Hierarchy, rather than a Residue since the residue may not be explicitly represented and may just be part of some fragment.

Exceptions
ValueExceptionif mhd's type is not one of CHAIN, PROTEIN, NUCLEOTIDE
Returns
Hierarchy() if that residue is not found.
Hierarchy get_root ( Hierarchy  h)
related

Return the root of the hierarchy.

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

+ Here is the call graph for this function:

void show ( Hierarchy  h,
std::ostream &  out = std::cout 
)
related

Print out a molecular hierarchy.

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


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