IMP  2.0.0
The Integrative Modeling Platform
Selection.h
Go to the documentation of this file.
1 /**
2  * \file IMP/atom/Selection.h
3  * \brief A set of useful functionality on IMP::atom::Hierarchy decorators
4  *
5  * Copyright 2007-2013 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPATOM_SELECTION_H
9 #define IMPATOM_SELECTION_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/base/InputAdaptor.h>
18 #include <IMP/core/Typed.h>
19 #include <IMP/core/XYZR.h>
20 
21 IMPATOM_BEGIN_NAMESPACE
22 
23 
24 
25 /** Select a part of an atom.Hiearchy or atom.Hierarchies that is identified
26  by the biological name.
27 
28 
29  For example (in python)
30  \code
31  Selection(hierarchy=h, molecule="myprotein", terminus=Selection.C)
32  Selection(hierarchy=h, molecule="myprotein", residue_index=133)
33  Selection(hierarchy=h, molecule="myprotein", residue_indexes=[(133,134)])
34  \endcode
35  each get the C-terminus of the protein "myprotein" (assuming the last
36  residue index is 133).
37 
38  \note Only representational particles are selected. That is, ones
39  with x,y,z coordinates. And the highest resolution representation
40  that fits is returned. If you want lower resolution, use the
41  target_radius parameter to select the desired radius (pass a very large
42  number to get the coarsest representation).
43 */
44 class IMPATOMEXPORT Selection: public base::InputAdaptor {
45  public:
46  enum Terminus {NONE, C,N};
47  private:
49  ParticleIndexes h_;
50  Strings molecules_;
51  Ints residue_indices_;
52  ResidueTypes residue_types_;
53  std::string chains_;
54  AtomTypes atom_types_;
55  Strings domains_;
56  double radius_;
57  Terminus terminus_;
58  Ints copies_;
59  core::ParticleTypes types_;
60  Ints htypes_;
61  bool check_nonradius(Hierarchy h) const;
62  bool operator()(Hierarchy h) const;
63  public:
64 #ifdef IMP_DOXYGEN
65  /** When using python, you have much more control over
66  construction due to the use of keyword arguments. You
67  can provide any subset of the arguments (although one
68  of hierarchy or hierarchies must be provided).
69  */
70  Selection(Hierarchy hierarchy=None,
71  Hierarchies hierarchies=[],
72  Strings molecules=[],
73  Ints residue_indexes=[],
74  Strings chains=[],
75  AtomTypes atom_types=[],
76  ResidueTypes residue_types=[],
77  Strings domains=[],
78  double target_radius=0,
79  std::string molecule=None,
80  int residue_index=None,
81  char chain=None,
82  AtomType atom_type=None,
83  ResidueType residue_type=None,
84  HierarchyType hierarchy_type=None,
85  Terminus terminus=None,
86  std::string domain=None,
87  core::ParticleType particle_type=None,
88  core::ParticleTypes particle_types=[],
89  int copy_index=-1,
90  Ints copy_indexs=[]
91  );
92 #endif
93  Selection();
95  Selection(Particle *h);
96  Selection(Model *m, const ParticleIndexes &pis);
97 #ifndef SWIG
98  Selection(const Hierarchies& h);
99 #endif
100  Selection(const ParticlesTemp& h);
101  // for C++
102 #if !defined(IMP_DOXYGEN) && !defined(SWIG)
104  std::string molname,
105  int residue_index);
106 #endif
107  //! Return the hierarchies that the Selection was constructed with
108  Hierarchies get_hierarchies() const ;
109  /** Select based on the molecule name.*/
110  void set_molecules(Strings mols) {
111  molecules_= mols;
112  std::sort(molecules_.begin(), molecules_.end());
113  }
114  /** Select particles whose radii are close to r.*/
115  void set_target_radius(double r) {
116  radius_=r;
117  }
118  /** Select the n or c terminus.*/
119  void set_terminus(Terminus t) {
120  terminus_=t;
121  }
122  /** Select particles in chains whose id is
123  in the passed string.*/
124  void set_chains(std::string chains) {
125  chains_= chains;
126  std::sort(chains_.begin(), chains_.end());
127  }
128  /** Select residues whose indexes are in the passed list.*/
129  void set_residue_indexes(Ints indexes) {
130  residue_indices_= indexes;
131  std::sort(residue_indices_.begin(), residue_indices_.end());
132  }
133  /** Select atoms whose types are in the list, eg AT_CA.*/
134  void set_atom_types(AtomTypes types) {
135  atom_types_= types;
136  std::sort(atom_types_.begin(), atom_types_.end());
137  }
138  /** Select residues whose types are in the list. Not sure
139  why you would do this.*/
141  residue_types_= types;
142  std::sort(residue_types_.begin(), residue_types_.end());
143  }
144  /** Select domains with the specificed names. */
145  void set_domains(Strings names) {
146  domains_= names;
147  std::sort(domains_.begin(), domains_.end());
148  }
149  /** Select a molecule with the passed name. */
150  void set_molecule(std::string mol) {
151  molecules_= Strings(1,mol);
152  }
153  /** Select a chain with the passed id*/
154  void set_chain(char c) {
155  chains_= std::string(1,c);
156  }
157  /** Select only residues with the passed index.*/
158  void set_residue_index(int i) {
159  residue_indices_= Ints(1,i);
160  }
161  /** Select atoms with only the passed type. */
162  void set_atom_type(AtomType types) {
163  atom_types_= AtomTypes(1,types);
164  }
165  /** Select only residues with the passed type.*/
167  residue_types_= ResidueTypes(1,type);
168  }
169  /** Select only the single domain with that name*/
170  void set_domain(std::string name) {
171  domains_= Strings(1, name);
172  }
173  /** Select elements with Copy::get_copy_index() that match.*/
174  void set_copy_index(unsigned int copy) {
175  copies_=Ints(1, copy);
176  }
177  /** Select elements with Copy::get_copy_index() that are in the list.*/
178  void set_copy_indexes(const Ints &copies) {
179  copies_=copies;
180  std::sort(copies_.begin(), copies_.end());
181  }
182  /** Select elements that match the core::ParticleType.*/
184  types_= core::ParticleTypes(1,t);
185  }
186  /** Select elements that match the core::ParticleType.*/
188  types_= t;
189  std::sort(types_.begin(), types_.end());
190  }
191  /** Select only particles whose type matches the passed type, eg
192  Molecule, Fragment, Residue etc. See GetByType for how to
193  specify the types. Ints are used to make swig happy.*/
194  void set_hierarchy_types(const Ints &types) {
195  htypes_= types;
196  }
197  //! Get the selected particles
198  ParticlesTemp get_selected_particles() const;
200 };
201 
203 
204 /** Create a distance restraint between the selections.
205 
206  This restraint applies a harmonic to the minimum distance
207  between a particle in selection n0 and a particle in selection
208  n1.
209 
210  If one or more of the selections is a rigid body, this will be used
211  to accelerate the computation.
212  \relatesalso Selection
213  */
214 IMPATOMEXPORT Restraint* create_distance_restraint(const Selection &n0,
215  const Selection &n1,
216  double x0, double k,
217  std::string name= "Distance%1%");
218 
219 
220 /** Create a restraint connecting the selections.
221 
222  If one or more of the selections is a rigid body, this will be used
223  to accelerate the computation.
224  \relatesalso Selection
225 */
226 IMPATOMEXPORT Restraint* create_connectivity_restraint(const Selections &s,
227  double k,
228  std::string name="Connectivity%1%");
229 
230 /** Create a restraint connecting the selections. The particles are
231  allowed to be appart by x0 and still count as connected.
232 
233  If one or more of the selections is a rigid body, this will be used
234  to accelerate the computation.
235  \relatesalso Selection
236 */
237 IMPATOMEXPORT Restraint* create_connectivity_restraint(const Selections &s,
238  double x0, double k,
239  std::string name="Connectivity%1%");
240 
241 /** Create a restraint connecting the selection.
242 
243  If one or more of the selections is a rigid body, this will be used
244  to accelerate the computation.
245 
246  \relatesalso Selection
247 */
248 IMPATOMEXPORT Restraint*
250  double k,
251  std::string name="Connectivity%1%");
252 
253 /** Create a restraint connecting the selection. The particles are
254  allowed to be appart by x0 and still count as connected.
255 
256  If one or more of the selections is a rigid body, this will be used
257  to accelerate the computation.
258 
259  \relatesalso Selection
260 */
261 IMPATOMEXPORT Restraint*
263  double x0, double k,
264  std::string name="Connectivity%1%");
265 
266 
267 
268 
269 /** Create an XYZR particle which always includes the particles
270  in the selection in its bounding volume. If all the particles
271  in the selection are part of the same rigid body, then the
272  created particle is added as part of that rigid body. Otherwise
273  it uses an IMP::core::Cover to maintain the cover property.
274 
275  Doing this can be a useful way to accelerate computations
276  when it is OK to replace a potential complicated set of
277  geometry represented by the selection with a much simpler
278  one.
279 
280  \relatesalso Selection
281 */
282 IMPATOMEXPORT core::XYZR create_cover(const Selection &s,
283  std::string name=std::string());
284 
285 
286 /** Get the total mass of a hierarchy. In daltons.
287  \relatesalso Selection
288  */
289 IMPATOMEXPORT double get_mass(const Selection &s);
290 
291 
292 #ifdef IMP_ALGEBRA_USE_IMP_CGAL
293 /** Get the total volume of a hierarchy. In cubic angstroms.
294  \requires{get_volume, CGAL}
295  \relatesalso Selection
296 */
297 IMPATOMEXPORT double get_volume(const Selection &s);
298 
299 /** Get the total surface area of a hierarchy. In square angstroms.
300  \requires{get_surface_area, CGAL}
301  \relatesalso Selection
302 */
303 IMPATOMEXPORT double get_surface_area(const Selection &s);
304 #endif
305 
306 /** \relatesalso Selection
307  */
308 IMPATOMEXPORT double get_radius_of_gyration(const Selection &s);
309 
310 /** Create an excluded volume restraint for a list of selections.*/
311 IMPATOMEXPORT Restraint*
313 
314 
315 /** \relatesalso Hierarchy */
316 IMPATOMEXPORT Hierarchies get_leaves(const Selection &h);
317 
318 
319 
320 /** \class SelectionGeometry
321  \brief Display a Selection.
322 */
323 class IMPATOMEXPORT SelectionGeometry: public display::Geometry {
324  atom::Selection res_;
325  mutable IMP::base::map<Particle*, Pointer<Geometry> > components_;
326 public:
328  std::string name="Selection"):
329  display::Geometry(name), res_(d) {}
332 };
333 
334 
335 
336 IMPATOM_END_NAMESPACE
337 
338 #endif /* IMPATOM_SELECTION_H */