IMP  2.3.1
The Integrative Modeling Platform
hierarchy_tools.h
Go to the documentation of this file.
1 /**
2  * \file IMP/atom/hierarchy_tools.h
3  * \brief A set of useful functionality on IMP::atom::Hierarchy decorators
4  *
5  * Copyright 2007-2014 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPATOM_HIERARCHY_TOOLS_H
9 #define IMPATOM_HIERARCHY_TOOLS_H
10 
11 #include <IMP/atom/atom_config.h>
12 #include <IMP/algebra/algebra_config.h>
13 #include "Hierarchy.h"
14 #include "Residue.h"
15 #include "Atom.h"
16 #include <IMP/core/Typed.h>
17 #include <IMP/core/XYZR.h>
18 #include "Selection.h"
19 #include <boost/graph/adjacency_list.hpp>
20 #include <boost/unordered_map.hpp>
21 
22 IMPATOM_BEGIN_NAMESPACE
23 
24 //! Create a coarse grained molecule
25 /** The coarse grained model is created with a number of spheres
26  based on the resolution and the volume. If the volume is not provided
27  it is estimated based on the number of residues. The protein is
28  created as a molecular hierarchy rooted at p. The leaves are Domain
29  particles with appropriate residue indexes stored and are XYZR
30  particles.
31 
32  Volume is, as usual, in cubic angstroms.
33 
34  Currently the function creates a set of balls with radii no greater
35  than target_radius which overlap by 20% and have a volume of their
36  union equal to the passed volume.
37 
38  The coordinates of the balls defining the protein are not optimized
39  by default, and have garbage coordinate values.
40  \untested{create_protein}
41  \unstable{create_protein}
42  \see Hierarchy
43  */
44 IMPATOMEXPORT Hierarchy
45  create_protein(kernel::Model *m, std::string name, double target_radius,
46  int number_of_residues, int first_residue_index = 0,
47  double volume = -1
48 #ifndef IMP_DOXYGEN
49  ,
50  bool ismol = true
51 #endif
52  );
53 /** Like the former create_protein(), but it enforces domain splits
54  at the provided domain boundaries. The domain boundaries should be
55  the start of the first domain, any boundaries, and then one past
56  the end of the last domain.
57  */
58 IMPATOMEXPORT Hierarchy create_protein(kernel::Model *m, std::string name,
59  double target_radius,
60  const Ints domain_boundaries);
61 
62 /** \name Simplification along backbone
63 
64  These two methods create a simplified version of a molecule by
65  merging residues sequentially. In one case every n residues are
66  merged, in the other, the intervals are passed manually. The
67  resulting molecule is not optimized by default and has no
68  restraints automatically created.
69 
70  At the moment, the calls only support unmodified hierarchies loaded
71  by read_pdb() which have only protein or DNA members.
72 
73  They return Hierarchy() if the input chain is empty.
74 
75  If keep_detailed is true, then the original high resolution structure
76  particles are added as children of the simplified structure.
77  @{
78 */
79 /** Simplify every num_res into one particle.*/
80 IMPATOMEXPORT Hierarchy
81  create_simplified_along_backbone(Hierarchy input, int num_res,
82  bool keep_detailed = false);
83 /** Simplify by breaking at the boundaries provided.*/
84 IMPATOMEXPORT Hierarchy
86  const IntRanges &residue_segments,
87  bool keep_detailed = false);
88 /** @} */
89 
90 /** Create a new hierarchy that approximates the volume occupied by the old one.
91 
92  The new hierarchy will contain a number of Fragment particles whose surface
93  (and hence volume) approximates the input hierarchy in the sense of
94  IMP::algebra::get_simplified_from_volume().
95 
96  The resulting representation has approximately the desired resolution in the
97  sense of get_resolution().
98 
99  Residue indexes are assigned to the created Fragments from the original
100  residue indexes, and particles containing adjacent residues are connected
101  by bonds. */
102 IMPATOMEXPORT Hierarchy
103  create_simplified_from_volume(Hierarchy h, double resolution);
104 
105 /** Create a new hierarchy that approximates the volume occupied by the old one.
106 
107  This function is like create_simplified_from_volume() except that the
108  result is divided into Chain and Molecule bits. It assumes that all
109  geometry is rooted under a chain or a molecule.
110  */
111 IMPATOMEXPORT Hierarchy
112  create_simplified_assembly_from_volume(Hierarchy h, double resolution);
113 
114 /** \name Finding information
115  Get the attribute of the given particle or throw a ValueException
116  if it is not applicable. The particle with the given information
117  must be above the passed node.
118  @{
119 */
120 IMPATOMEXPORT Ints get_residue_indexes(Hierarchy h);
121 IMPATOMEXPORT ResidueType get_residue_type(Hierarchy h);
122 /** \deprecated_at{2.2} Use the string version. */
123 IMPATOM_DEPRECATED_FUNCTION_DECL(2.2)
124 inline char get_chain_id_char(Hierarchy h) {
125  IMPATOM_DEPRECATED_FUNCTION_DEF(2.2, "Use string version");
126  return get_chain_id(h)[0];
127 }
128 IMPATOMEXPORT AtomType get_atom_type(Hierarchy h);
129 IMPATOMEXPORT std::string get_domain_name(Hierarchy h);
130 /** @} */
131 
132 /** Create an excluded volume restraint for the included molecules. If a
133  value is provided for resolution, then something less than the full
134  resolution representation will be used.
135 
136  If one or more of the selections is a rigid body, this will be used
137  to accelerate the computation.
138  \see Hierarchy
139  */
141  const Hierarchies &hs, double resolution = -1);
142 
143 /** Set the mass, radius, residues, and coordinates to approximate the passed
144  particles.
145  */
146 IMPATOMEXPORT void setup_as_approximation(kernel::Particle *h,
147  const kernel::ParticlesTemp &other
148 #ifndef IMP_DOXYGEN
149  ,
150  double resolution = -1
151 #endif
152  );
153 
154 /** Set the mass, radius, residues, and coordinates to approximate the passed
155  particle based on the leaves of h.
156  \see Hierarchy
157  */
158 IMPATOMEXPORT void setup_as_approximation(Hierarchy h
159 #ifndef IMP_DOXYGEN
160  ,
161  double resolution = -1
162 #endif
163  );
164 
165 //! Transform a hierarchy. This is aware of rigid bodies.
166 IMPATOMEXPORT void transform(Hierarchy h, const algebra::Transformation3D &tr);
167 
168 //! A graph for representing a Hierarchy so you can view it nicely.
169 IMP_GRAPH(HierarchyTree, bidirectional, Hierarchy, int,
170  vertex.show(out, "\\n"));
171 
172 //! Get a graph for the passed Hierarchy.
173 /** This can be used,
174  for example, to graphically display the hierarchy in 2D.
175  \see Hierarchy
176 */
178 
179 /** \class HierarchyGeometry
180  \brief Display an IMP::atom::Hierarchy particle as balls.
181 
182  \class HierarchiesGeometry
183  \brief Display an IMP::SingletonContainer of IMP::atom::Hierarchy particles
184  as balls.
185 */
187  double res_;
188  mutable boost::unordered_map<kernel::Particle *,
189  base::Pointer<display::Geometry> > components_;
190 
191  public:
192  HierarchyGeometry(core::Hierarchy d, double resolution = 0)
193  : SingletonGeometry(d), res_(resolution) {}
196  atom::Hierarchy d(get_particle());
197  atom::Selection sel(d);
198  sel.set_resolution(res_);
200  for (unsigned int i = 0; i < ps.size(); ++i) {
201  if (components_.find(ps[i]) == components_.end()) {
202  IMP_NEW(core::XYZRGeometry, g, (core::XYZR(ps[i])));
203  components_[ps[i]] = g;
204  }
205  ret.push_back(components_.find(ps[i])->second);
206  }
207  return ret;
208  }
210 };
212  double res_;
213  mutable boost::unordered_map<kernel::ParticleIndex,
214  base::Pointer<display::Geometry> > components_;
215 
216  public:
217  HierarchiesGeometry(SingletonContainer *sc, double resolution = -1)
218  : SingletonsGeometry(sc), res_(resolution) {}
221  IMP_FOREACH(kernel::ParticleIndex pi, get_container()->get_contents()) {
222  kernel::Model *m = get_container()->get_model();
223  if (components_.find(pi) == components_.end()) {
224  IMP_NEW(HierarchyGeometry, g, (atom::Hierarchy(m, pi), res_));
225  components_[pi] = g;
226  }
227  ret.push_back(components_.find(pi)->second);
228  }
229  return ret;
230  }
232 };
233 
234 /** Transform a hierarchy, being aware of rigid bodies and intermediate nodes
235  * with coordinates. Rigid bodies must either be completely contained within the
236  * hierarchy or completely disjoint (no rigid bodies that contain particles in
237  * the hierarchy and other particles not in it are allowed). */
238 IMPATOMEXPORT void transform(atom::Hierarchy h,
239  const algebra::Transformation3D &tr);
240 
241 IMPATOM_END_NAMESPACE
242 
243 #endif /* IMPATOM_HIERARCHY_TOOLS_H */
A base class for geometry contained in particles.
display::Geometries get_components() const
Return a set of geometry composing this one.
Simple 3D transformation class.
Hierarchy create_simplified_from_volume(Hierarchy h, double resolution)
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
#define IMP_GRAPH(Name, directionality, VertexData, EdgeData, ShowVertex)
Define a graph object in IMP.
Definition: graph_macros.h:29
A base class for geometry from a set of particles.
Simple atom decorator.
void setup_as_approximation(Hierarchy h)
void set_resolution(double r)
Select at a Representation node with a resolution close to r.
Definition: Selection.h:136
A smart pointer to a reference counted object.
Definition: Pointer.h:87
HierarchyTree get_hierarchy_tree(Hierarchy h)
Get a graph for the passed Hierarchy.
A particle with a user-defined type.
#define IMP_NEW(Typename, varname, args)
Declare a ref counted pointer to a new object.
Definition: object_macros.h:72
Decorator for helping deal with a hierarchy of molecules.
Hierarchy create_protein(kernel::Model *m, std::string name, double target_radius, const Ints domain_boundaries)
void transform(Hierarchy h, const algebra::Transformation3D &tr)
Transform a hierarchy. This is aware of rigid bodies.
The standard decorator for manipulating molecular structures.
Display an IMP::SingletonContainer of IMP::atom::Hierarchy particles as balls.
IMP::kernel::Model Model
A decorator for Residues.
A restraint is a term in an IMP ScoringFunction.
boost::graph HierarchyTree
A graph for representing a Hierarchy so you can view it nicely.
IMP::base::Vector< IntRange > IntRanges
Definition: types.h:38
Class to handle individual model particles.
base::Index< ParticleIndexTag > ParticleIndex
Hierarchy create_simplified_along_backbone(Chain input, const IntRanges &residue_segments, bool keep_detailed=false)
kernel::Restraint * create_excluded_volume_restraint(const Hierarchies &hs, double resolution=-1)
A decorator for helping deal with a hierarchy.
char get_chain_id_char(Hierarchy h)
Hierarchy create_simplified_assembly_from_volume(Hierarchy h, double resolution)
std::string get_chain_id(Hierarchy h)
Select hierarchy particles identified by the biological name.
Definition: Selection.h:62
Decorator for a sphere-like particle.
Select a subset of a hierarchy.
A shared container for Singletons.
display::Geometries get_components() const
Return a set of geometry composing this one.
kernel::ParticlesTemp get_selected_particles() const
Get the selected particles.
Display an IMP::atom::Hierarchy particle as balls.
Class for storing model, its restraints, constraints, and particles.
Definition: kernel/Model.h:73
Display an IMP::core::XYZR particle as a ball.
Definition: XYZR.h:149
IMP::base::Vector< Int > Ints
Standard way to pass a bunch of Int values.
Definition: types.h:49
A decorator for a particle with x,y,z coordinates and a radius.
Definition: XYZR.h:27