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