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