IMP  2.2.1
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-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 "Atom.h"
13 #include "Hierarchy.h"
14 #include "Residue.h"
15 #include <IMP/SingletonPredicate.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 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=range(133,138))
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  resolution parameter to select the desired resolution (pass a very large
42  number to get the coarsest representation).
43 */
44 class IMPATOMEXPORT Selection :
45 #ifdef SWIG
47 #else
48  public base::InputAdaptor
49 #endif
50  {
51  public:
52  enum Terminus {
53  NONE,
54  C,
55  N
56  };
57 
58  private:
59  SingletonPredicates predicates_;
60  kernel::Model *m_;
61  double resolution_;
62 
64  IMP_NAMED_TUPLE_2(SearchResult, SearchResults, bool, match,
65  kernel::ParticleIndexes, indexes, );
66  SearchResult search(kernel::Model *m, kernel::ParticleIndex pi,
67  boost::dynamic_bitset<> parent) const;
68  void set_hierarchies(kernel::Model *m, const kernel::ParticleIndexes &pis);
69 
70  public:
71 #ifdef IMP_DOXYGEN
72  /** When using python, you have much more control over
73  construction due to the use of keyword arguments. You
74  can provide any subset of the arguments (although one
75  of hierarchy or hierarchies must be provided).
76  */
77  Selection(Hierarchy hierarchy = None, Hierarchies hierarchies = [],
78  Strings molecules = [], Ints residue_indexes = [],
79  Strings chains = [], AtomTypes atom_types = [],
80  ResidueTypes residue_types = [], Strings domains = [],
81  double resolution = 0, std::string molecule = None,
82  int residue_index = None, std::string chain = None,
83  AtomType atom_type = None, ResidueType residue_type = None,
84  HierarchyType hierarchy_type = None, Terminus terminus = None,
85  std::string domain = None, core::ParticleType particle_type = None,
86  core::ParticleTypes particle_types = [], int copy_index = -1,
87  Ints copy_indexs = [], int state_index = -1,
88  Ints state_indexes = []);
89 #endif
90  Selection();
94 #ifndef SWIG
95  Selection(const Hierarchies &h);
96 #endif
98 // for C++
99 #if !defined(IMP_DOXYGEN) && !defined(SWIG)
100  Selection(Hierarchy h, std::string molname, int residue_index);
101 #endif
102  //! Return the hierarchies that the Selection was constructed with
103  Hierarchies get_hierarchies() const;
104  /** Select based on the molecule name.*/
105  void set_molecules(Strings mols);
106 
107  /** Select at a Representation node with a resolution close to r.*/
108  void set_resolution(double r) { resolution_ = r; }
109  /** Select State with the passed index.*/
110  void set_state_index(int state) { set_state_indexes(Ints(1, state)); }
111  /** Select State with the passed index.*/
112  void set_state_indexes(Ints states);
113  /** Select the n or c terminus.*/
114  void set_terminus(Terminus t);
115  /** Select particles in chains whose id is
116  in the passed string.*/
117  void set_chain_ids(Strings chains);
118 #ifndef IMP_DOXYGEN
119  void set_chains(Strings chains) { set_chain_ids(chains); }
120 #endif
121  /** Select residues whose indexes are in the passed list.*/
122  void set_residue_indexes(Ints indexes);
123  /** Select atoms whose types are in the list, eg AT_CA.*/
124  void set_atom_types(AtomTypes types);
125  /** Select residues whose types are in the list. Not sure
126  why you would do this.*/
127  void set_residue_types(ResidueTypes types);
128  /** Select domains with the specificed names. */
129  void set_domains(Strings names);
130  /** Select a molecule with the passed name. */
131  void set_molecule(std::string mol);
132  /** Select with the passed chain id. */
133  void set_chain_id(std::string c);
134 #ifndef IMP_DOXYGEN
135  /** Select a chain with the passed id*/
136  void set_chain(std::string c) { set_chain_id(c); }
137 #endif
138 #ifndef SWIG
139  /** \deprecated_at{2.2} Pass a string */
140  IMPATOM_DEPRECATED_FUNCTION_DECL(2.2)
141  void set_chain(char c) { set_chain(std::string(1, c)); }
142 #endif
143  /** Select only residues with the passed index.*/
144  void set_residue_index(int i);
145  /** Select atoms with only the passed type. */
146  void set_atom_type(AtomType types);
147  /** Select only residues with the passed type.*/
148  void set_residue_type(ResidueType type);
149  /** Select only the single domain with that name*/
150  void set_domain(std::string name);
151  /** Select elements with Copy::get_copy_index() that match.*/
152  void set_copy_index(unsigned int copy);
153  /** Select elements with Copy::get_copy_index() that are in the list.*/
154  void set_copy_indexes(Ints copies);
155  /** Select elements that match the core::ParticleType.*/
156  void set_particle_type(core::ParticleType t);
157  /** Select elements that match the core::ParticleType.*/
158  void set_particle_types(core::ParticleTypes t);
159  /** Select only particles whose type matches the passed type, eg
160  Molecule, Fragment, Residue etc. See GetByType for how to
161  specify the types. Ints are used to make swig happy.*/
162  void set_hierarchy_types(Ints types);
163  //! Get the selected particles
164  kernel::ParticlesTemp get_selected_particles() const;
165  //! Get the indexes of the selected particles
166  kernel::ParticleIndexes get_selected_particle_indexes() const;
167 
168 #ifndef SWIG
169  operator ParticleIndexes() const { return get_selected_particle_indexes(); }
170  operator ParticlesTemp() const { return get_selected_particles(); }
171 #endif
172 
173  IMP_SHOWABLE(Selection);
174 };
175 
177 
178 /** Create a distance restraint between the selections.
179 
180  This restraint applies a harmonic to the minimum distance
181  between a particle in selection n0 and a particle in selection
182  n1.
183 
184  If one or more of the selections is a rigid body, this will be used
185  to accelerate the computation.
186  See Selection
187  */
188 IMPATOMEXPORT kernel::Restraint *create_distance_restraint(const Selection &n0,
189  const Selection &n1,
190  double x0, double k,
191  std::string name =
192  "Distance%1%");
193 
194 /** Create a restraint connecting the selections.
195 
196  If one or more of the selections is a rigid body, this will be used
197  to accelerate the computation.
198  See Selection
199 */
201  const Selections &s, double k, std::string name = "Connectivity%1%");
202 
203 /** Create a restraint connecting the selections. The particles are
204  allowed to be appart by x0 and still count as connected.
205 
206  If one or more of the selections is a rigid body, this will be used
207  to accelerate the computation.
208  See Selection
209 */
211  const Selections &s, double x0, double k,
212  std::string name = "Connectivity%1%");
213 
214 /** Create a restraint connecting the selection.
215 
216  If one or more of the selections is a rigid body, this will be used
217  to accelerate the computation.
218 
219  See Selection
220 */
222  const Selection &s, double k, std::string name = "Connectivity%1%");
223 
224 /** Create a restraint connecting the selection. The particles are
225  allowed to be appart by x0 and still count as connected.
226 
227  If one or more of the selections is a rigid body, this will be used
228  to accelerate the computation.
229 
230  See Selection
231 */
233  const Selection &s, double x0, double k,
234  std::string name = "Connectivity%1%");
235 
236 /** Create an XYZR particle which always includes the particles
237  in the selection in its bounding volume. If all the particles
238  in the selection are part of the same rigid body, then the
239  created particle is added as part of that rigid body. Otherwise
240  it uses an IMP::core::Cover to maintain the cover property.
241 
242  Doing this can be a useful way to accelerate computations
243  when it is OK to replace a potential complicated set of
244  geometry represented by the selection with a much simpler
245  one.
246 
247  See Selection
248 */
249 IMPATOMEXPORT core::XYZR create_cover(const Selection &s,
250  std::string name = std::string());
251 
252 /** Get the total mass of a hierarchy. In daltons.
253  See Selection
254  */
255 IMPATOMEXPORT double get_mass(const Selection &s);
256 
257 #ifdef IMP_ALGEBRA_USE_IMP_CGAL
258 /** Get the total volume of a hierarchy. In cubic angstroms.
259  \requires{get_volume, CGAL}
260  See Selection
261 */
262 IMPATOMEXPORT double get_volume(const Selection &s);
263 
264 /** Get the total surface area of a hierarchy. In square angstroms.
265  \requires{get_surface_area, CGAL}
266  See Selection
267 */
268 IMPATOMEXPORT double get_surface_area(const Selection &s);
269 #endif
270 
271 /** See Selection
272  */
273 IMPATOMEXPORT double get_radius_of_gyration(const Selection &s);
274 
275 /** Create an excluded volume restraint for a list of selections.*/
277  const Selections &s);
278 
279 /** See Hierarchy */
280 IMPATOMEXPORT Hierarchies get_leaves(const Selection &h);
281 
282 /** \class SelectionGeometry
283  \brief Display a Selection.
284 */
285 class IMPATOMEXPORT SelectionGeometry : public display::Geometry {
286  atom::Selection res_;
287  mutable boost::unordered_map<kernel::Particle *, base::Pointer<Geometry> >
288  components_;
289 
290  public:
291  SelectionGeometry(atom::Selection d, std::string name = "Selection")
292  : display::Geometry(name), res_(d) {}
295 };
296 
297 IMPATOM_END_NAMESPACE
298 
299 #endif /* IMPATOM_SELECTION_H */
double get_volume(const Selection &s)
double get_mass(const Selection &s)
IMP::kernel::ParticleIndexes ParticleIndexes
The base class for geometry.
Display a Selection.
Definition: Selection.h:285
IMP::base::Vector< AtomType > AtomTypes
Definition: atom/Atom.h:29
Simple atom decorator.
#define IMP_VALUES(Name, PluralName)
Define the type for storing sets of values.
void set_resolution(double r)
Definition: Selection.h:108
The type of an atom.
double get_radius_of_gyration(const Selection &s)
void set_chain(char c)
Definition: Selection.h:141
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)
Definition: Selection.h:110
A particle with a user-defined type.
Import IMP/kernel/SingletonPredicate.h in the namespace.
kernel::Restraint * create_excluded_volume_restraint(const Selections &s)
Decorator for helping deal with a hierarchy of molecules.
core::XYZR create_cover(const Selection &s, std::string name=std::string())
IMP::base::Vector< IMP::base::Pointer< SingletonPredicate > > SingletonPredicates
#define IMP_SHOWABLE(Name)
The standard decorator for manipulating molecular structures.
Basic types used by IMP.
A decorator for Residues.
The type for a residue.
A restraint is a term in an IMP ScoringFunction.
kernel::Restraint * create_connectivity_restraint(const Selections &s, double x0, double k, std::string name="Connectivity%1%")
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
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.
double get_surface_area(const Selection &s)
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%")
Hierarchies get_leaves(const Selection &h)
Decorator for a sphere-like particle.
Class for storing model, its restraints, constraints, and particles.
Definition: kernel/Model.h:72
IMP::base::Vector< Int > Ints
Standard way to pass a bunch of Int values.
Definition: base/types.h:49
A decorator for a particle with x,y,z coordinates and a radius.
Definition: XYZR.h:27