IMP logo
IMP Reference Guide  2.5.0
The Integrative Modeling Platform
Selection.h
Go to the documentation of this file.
1 /**
2  * \file IMP/atom/Selection.h
3  * \brief Select a subset of a hierarchy.
4  *
5  * Copyright 2007-2015 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/atom/internal/SelectionPredicate.h>
13 #include "Atom.h"
14 #include "Hierarchy.h"
15 #include "Residue.h"
16 #include "Representation.h"
17 #include <IMP/algebra/algebra_config.h>
18 #include <IMP/InputAdaptor.h>
19 #include <IMP/core/Typed.h>
20 #include <IMP/core/XYZR.h>
22 #include <boost/unordered_map.hpp>
23 
24 IMPATOM_BEGIN_NAMESPACE
25 
26 //! Select hierarchy particles identified by the biological name.
27 /** Given an atom.Hierarchy (or atom.Hierarchies) this will select a subset
28  of the child particles by the biological name.
29 
30 
31  For example (in Python)
32  \code
33  Selection(hierarchy=h, molecule="myprotein", terminus=Selection.C)
34  Selection(hierarchy=h, molecule="myprotein", residue_index=133)
35  Selection(hierarchy=h, molecule="myprotein", residue_indexes=range(133,138))
36  \endcode
37  each select the C-terminus of the protein "myprotein" (assuming the last
38  residue index is 133, and the residues are leaves, containing no atoms).
39  (In C++, use one of the other constructors, then call one or more of the
40  `set_*` methods.)
41 
42  Selection objects can be combined using basic set operations (union,
43  intersection, difference, symmetric difference). In Python the equivalent
44  operators (|, &, -, ^ respectively) can be used (the similar in-place
45  |=, &=, -= and ^= operators also work). This requires that all
46  of the objects being combined use the same hierarchy or hierarchies. For
47  example (in Python)
48  \code
49  Selection(hierarchy=h, residue_type=IMP.atom.ASP) \
50  - (Selection(hierarchy=h, atom_type=IMP.atom.AT_CG)
51  | Selection(hierarchy=h, terminus=Selection.C))
52  \endcode
53  selects all atoms in ASP residues except for CG or at the C-terminus.
54  The resulting Selection makes a copy of the Selections it was combined from,
55  so changing the original Selections does not change that Selection.
56 
57  To actually get the selected particles, call get_selected_particle_indexes()
58  or get_selected_particles().
59 
60  \note The highest resolution representation
61  that fits is returned. If you want lower resolution, use the
62  resolution parameter to select the desired resolution (pass a very large
63  number to get the coarsest representation).
64 */
65 class IMPATOMEXPORT Selection :
66 #ifdef SWIG
68 #else
69  public InputAdaptor
70 #endif
71  {
72  public:
73  enum Terminus {
74  NONE,
75  C,
76  N
77  };
78 
79  private:
80  Model *m_;
81  double resolution_;
82  RepresentationType representation_type_;
83  Pointer<internal::ListSelectionPredicate> predicate_, and_predicate_;
84 
85  ParticleIndexes h_;
86  IMP_NAMED_TUPLE_2(SearchResult, SearchResults, bool, match,
87  ParticleIndexes, indexes, );
88  SearchResult search(Model *m, ParticleIndex pi,
89  boost::dynamic_bitset<> parent,
90  bool include_children) const;
91  void set_hierarchies(Model *m, const ParticleIndexes &pis);
92  void add_predicate(internal::SelectionPredicate *p);
93  void init_predicate();
94 
95  public:
96 #ifdef IMP_DOXYGEN
97  /** When using Python, you have much more control over
98  construction due to the use of keyword arguments. You
99  can provide any subset of the arguments (although one
100  of hierarchy or hierarchies must be provided).
101  */
102  Selection(Hierarchy hierarchy = None, Hierarchies hierarchies = [],
103  Strings molecules = [], Ints residue_indexes = [],
104  Strings chain_ids = [], AtomTypes atom_types = [],
105  ResidueTypes residue_types = [], Strings domains = [],
106  double resolution = 0,
107  RepresentationType representation_type = IMP.atom.BALLS,
108  std::string molecule = None,
109  int residue_index = None, std::string chain_id = None,
110  AtomType atom_type = None, ResidueType residue_type = None,
111  Ints hierarchy_types = None, Terminus terminus = None,
112  std::string domain = None, core::ParticleType particle_type = None,
113  core::ParticleTypes particle_types = [], int copy_index = -1,
114  Ints copy_indexes = [], int state_index = -1,
115  Ints state_indexes = []);
116 #endif
117  Selection();
118  Selection(Hierarchy h);
119  Selection(Particle *h);
120  Selection(Model *m, const ParticleIndexes &pis);
121 #ifndef SWIG
122  Selection(const Hierarchies &h);
123 #endif
124  Selection(const ParticlesTemp &h);
125 // for C++
126 #if !defined(IMP_DOXYGEN) && !defined(SWIG)
127  Selection(Hierarchy h, std::string molname, int residue_index);
128 #endif
129 
130  //! Make a clone of this Selection.
131  /** The clone will initially contain the same predicates as the original,
132  but adding new predicates to either Selection will not affect the
133  other (as opposed to simply copy the Selection object, where both copies
134  share the same list of predicates). */
136 
137  //! Return the hierarchies that the Selection was constructed with
138  Hierarchies get_hierarchies() const;
139  //! Select based on the molecule name.
140  void set_molecules(Strings mols);
141 
142  //! Select at a Representation node with a resolution close to r.
143  void set_resolution(double r) { resolution_ = r; }
144  //! Try to find this representation type
146  { representation_type_ = t; }
147  //! Select State with the passed index.
148  void set_state_index(int state) { set_state_indexes(Ints(1, state)); }
149  //! Select State with the passed indexes.
150  void set_state_indexes(Ints states);
151  //! Select the leaf particles at the N or C terminus.
152  /** If the leaf particles are atoms, a terminus is simply an N or C atom
153  where its parent is also a terminus particle. Otherwise, a terminus
154  particle is the first (for N) or last (for C) child of its parent. */
155  void set_terminus(Terminus t);
156  //! Select particles in chains with the given ids.
157  void set_chain_ids(Strings chains);
158 #ifndef IMP_DOXYGEN
159  void set_chains(Strings chains) { set_chain_ids(chains); }
160 #endif
161  //! Select residues whose indexes are in the passed list.
162  void set_residue_indexes(Ints indexes);
163  //! Select atoms whose types are in the list, eg AT_CA.
164  void set_atom_types(AtomTypes types);
165  //! Select residues whose types are in the list.
166  void set_residue_types(ResidueTypes types);
167  //! Select domains with the specified names.
168  void set_domains(Strings names);
169  //! Select a molecule with the passed name.
170  void set_molecule(std::string mol);
171  //! Select with the passed chain id.
172  void set_chain_id(std::string c);
173 #ifndef IMP_DOXYGEN
174  //! Select a chain with the passed id.
175  void set_chain(std::string c) { set_chain_id(c); }
176 #endif
177  //! Select only residues with the passed index.
178  void set_residue_index(int i);
179  //! Select atoms with only the passed type.
180  void set_atom_type(AtomType types);
181  //! Select only residues with the passed type.
182  void set_residue_type(ResidueType type);
183  //! Select only the single domain with that name.
184  void set_domain(std::string name);
185  //! Select elements with Copy::get_copy_index() that match.
186  void set_copy_index(unsigned int copy);
187  //! Select elements with Copy::get_copy_index() that are in the list.
188  void set_copy_indexes(Ints copies);
189  //! Select elements that match the core::ParticleType.
190  void set_particle_type(core::ParticleType t);
191  //! Select elements that match the core::ParticleType.
192  void set_particle_types(core::ParticleTypes t);
193  /** Select only particles whose type matches the passed type, eg
194  Molecule, Fragment, Residue etc. See GetByType for how to
195  specify the types. Ints are used to make swig happy.*/
196  void set_hierarchy_types(Ints types);
197  //! Select elements that are in both this Selection and the passed one.
198  /** \note both Selections must be on the same Hierarchy or Hierarchies */
199  void set_intersection(const Selection &s);
200  //! Select elements that are in either this Selection or the passed one.
201  /** \note both Selections must be on the same Hierarchy or Hierarchies */
202  void set_union(const Selection &s);
203  //! Select elements that are in this Selection or the passed one but not both.
204  /** \note both Selections must be on the same Hierarchy or Hierarchies */
205  void set_symmetric_difference(const Selection &s);
206  //! Select elements that are in this Selection but not the passed one.
207  /** \note both Selections must be on the same Hierarchy or Hierarchies */
208  void set_difference(const Selection &s);
209  //! Get the selected particles
210  /** \see get_selected_particle_indexes().
211  */
212  ParticlesTemp get_selected_particles(bool with_representation=true) const;
213  //! Get the indexes of the selected particles
214  /** \note The particles are those selected at the time this method is called,
215  not when the Selection object was created.
216  \param with_representation If true (the default) then extend the search
217  down the hierarchy to find all representational particles that
218  match - that is, those with x,y,z coordinates. For example,
219  selecting a residue name will typically return all of the Atom
220  particles in that residue (not the Residue particle itself).
221  If false, stop the search at the highest level of the hierarchy
222  that matches (so, in the case above, return the Residue particle).
223  \return the indexes of the selected particles.
224  */
225  ParticleIndexes
226  get_selected_particle_indexes(bool with_representation=true) const;
227 
228 #ifndef SWIG
229  operator ParticleIndexes() const { return get_selected_particle_indexes(); }
230  operator ParticlesTemp() const { return get_selected_particles(); }
231 #endif
232 
233  IMP_SHOWABLE(Selection);
234 };
235 
237 
238 /** Create a distance restraint between the selections.
239 
240  This restraint applies a harmonic to the minimum distance
241  between a particle in selection n0 and a particle in selection
242  n1.
243 
244  If one or more of the selections is a rigid body, this will be used
245  to accelerate the computation.
246  \see Selection
247  */
248 IMPATOMEXPORT Restraint *create_distance_restraint(const Selection &n0,
249  const Selection &n1,
250  double x0, double k,
251  std::string name =
252  "Distance%1%");
253 
254 //! Create a restraint connecting the selections.
255 /** If one or more of the selections is a rigid body, this will be used
256  to accelerate the computation.
257  \see Selection
258 */
260  const Selections &s, double k, std::string name = "Connectivity%1%");
261 
262 //! Create a restraint connecting the selections.
263 /** The particles are allowed to be apart by x0 and still count as connected.
264 
265  If one or more of the selections is a rigid body, this will be used
266  to accelerate the computation.
267  \see Selection
268 */
270  const Selections &s, double x0, double k,
271  std::string name = "Connectivity%1%");
272 
273 //! Create a restraint connecting the selection.
274 /** If one or more of the selections is a rigid body, this will be used
275  to accelerate the computation.
276 
277  \see Selection
278 */
280  const Selection &s, double k, std::string name = "Connectivity%1%");
281 
282 //! Create a restraint connecting the selection.
283 /** The particles are allowed to be apart by x0 and still count as connected.
284 
285  If one or more of the selections is a rigid body, this will be used
286  to accelerate the computation.
287 
288  \see Selection
289 */
291  const Selection &s, double x0, double k,
292  std::string name = "Connectivity%1%");
293 
294 /** Create an XYZR particle which always includes the particles
295  in the selection in its bounding volume. If all the particles
296  in the selection are part of the same rigid body, then the
297  created particle is added as part of that rigid body. Otherwise
298  it uses an IMP::core::Cover to maintain the cover property.
299 
300  Doing this can be a useful way to accelerate computations
301  when it is OK to replace a potentially complicated set of
302  geometries represented by the selection with a much simpler
303  one.
304 
305  \see Selection
306 */
307 IMPATOMEXPORT core::XYZR create_cover(const Selection &s,
308  std::string name = std::string());
309 
310 //! Get the total mass of a hierarchy, in Daltons.
311 /** \see Selection
312  */
313 IMPATOMEXPORT double get_mass(const Selection &s);
314 
315 #ifdef IMP_ALGEBRA_USE_IMP_CGAL
316 //! Get the total volume of a hierarchy, in cubic angstroms.
317 /** \requires{get_volume, CGAL}
318  \see Selection
319 */
320 IMPATOMEXPORT double get_volume(const Selection &s);
321 
322 //! Get the total surface area of a hierarchy, in square angstroms.
323 /** \requires{get_surface_area, CGAL}
324  \see Selection
325 */
326 IMPATOMEXPORT double get_surface_area(const Selection &s);
327 #endif
328 
329 /** \see Selection
330  */
331 IMPATOMEXPORT double get_radius_of_gyration(const Selection &s);
332 
333 //! Create an excluded volume restraint for a list of selections.
335  const Selections &s);
336 
337 /** \see Hierarchy */
338 IMPATOMEXPORT Hierarchies get_leaves(const Selection &h);
339 
340 /** \class SelectionGeometry
341  \brief Display a Selection.
342 */
343 class IMPATOMEXPORT SelectionGeometry : public display::Geometry {
344  atom::Selection res_;
345  mutable boost::unordered_map<Particle *, Pointer<Geometry> >
346  components_;
347 
348  public:
349  SelectionGeometry(atom::Selection d, std::string name = "Selection")
350  : display::Geometry(name), res_(d) {}
353 };
354 
355 IMPATOM_END_NAMESPACE
356 
357 #endif /* IMPATOM_SELECTION_H */
A decorator for Representations.
IMP::Vector< ParticleType > ParticleTypes
Definition: Typed.h:31
void set_representation_type(RepresentationType t)
Try to find this representation type.
Definition: Selection.h:145
double get_mass(const Selection &s)
Get the total mass of a hierarchy, in Daltons.
The base class for geometry.
Hierarchy create_clone(Hierarchy d)
Clone the Hierarchy.
Display a Selection.
Definition: Selection.h:343
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
Simple atom decorator.
double get_volume(const Cone3D &g)
Definition: Cone3D.h:64
void set_resolution(double r)
Select at a Representation node with a resolution close to r.
Definition: Selection.h:143
IMP::Vector< AtomType > AtomTypes
Definition: atom/Atom.h:29
#define IMP_SHOWABLE(Name)
The type of an atom.
double get_radius_of_gyration(const Selection &s)
Implement geometry for the basic shapes from IMP.algebra.
void set_state_index(int state)
Select State with the passed index.
Definition: Selection.h:148
A particle with a user-defined type.
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:72
Decorator for helping deal with a hierarchy of molecules.
#define IMP_VALUES(Name, PluralName)
Define the type for storing sets of values.
Definition: value_macros.h:23
Basic types used by IMP.
Restraint * create_internal_connectivity_restraint(const Selection &s, double x0, double k, std::string name="Connectivity%1%")
Create a restraint connecting the selection.
core::XYZR create_cover(const Selection &s, std::string name=std::string())
The standard decorator for manipulating molecular structures.
A decorator for Residues.
The type for a residue.
double get_surface_area(const Cone3D &g)
Definition: Cone3D.h:64
A base class for Keys.
Definition: Key.h:46
IMP::Vector< ResidueType > ResidueTypes
Definition: Residue.h:27
Key< 34897493, true > ParticleType
Definition: Typed.h:30
virtual Geometries get_components() const
Return a set of geometry composing this one.
Class to handle individual model particles.
Definition: Particle.h:37
Restraint * create_distance_restraint(const Selection &n0, const Selection &n1, double x0, double k, std::string name="Distance%1%")
IMP::Vector< Int > Ints
Standard way to pass a bunch of Int values.
Definition: types.h:49
Restraint * create_connectivity_restraint(const Selections &s, double x0, double k, std::string name="Connectivity%1%")
Create a restraint connecting the selections.
Hierarchies get_leaves(const Selection &h)
Restraint * create_excluded_volume_restraint(const Selections &s)
Create an excluded volume restraint for a list of selections.
Select hierarchy particles identified by the biological name.
Definition: Selection.h:65
Decorator for a sphere-like particle.
A restraint is a term in an IMP ScoringFunction.
Definition: Restraint.h:52
A decorator for a particle with x,y,z coordinates and a radius.
Definition: XYZR.h:27