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