IMP: Residue.h Source File

00001 /**
00002  *  \file Residue.h     \brief A decorator for Residues.
00003  *
00004  *  Copyright 2007-2010 IMP Inventors. All rights reserved.
00005  *
00006  */
00007 
00008 #ifndef IMPATOM_RESIDUE_H
00009 #define IMPATOM_RESIDUE_H
00010 
00011 #include "atom_config.h"
00012 #include "atom_macros.h"
00013 #include "Hierarchy.h"
00014 #include "Chain.h"
00015 
00016 #include <IMP/base_types.h>
00017 #include <IMP/Particle.h>
00018 #include <IMP/Model.h>
00019 #include <IMP/Decorator.h>
00020 
00021 IMPATOM_BEGIN_NAMESPACE
00022 
00023 /* each static must be on a separate line because of MSVC bug C2487:
00024    see http://support.microsoft.com/kb/127900/
00025 */
00026 
00027 IMP_DECLARE_KEY_TYPE(ResidueType, IMP_RESIDUE_TYPE_INDEX);
00028 /** \class ResidueType
00029     \brief The type for a residue.
00030 
00031     A given residue is either a Residue::LIGAND, Residue::AMINOACID,
00032     or Residue::NUCLEICACID.
00033 
00034     The standard residue types are provided with names like
00035     IMP::atom::GLY. New types can be added simply by creating an
00036     instance of ResidueType("my_residue_name"). All user-added
00037     residues are assumed to be ligands.
00038 
00039     \see Residue
00040 */
00041 
00042 /** Unknown residue */
00043 IMPATOMEXPORT extern const ResidueType UNK;
00044 /** \relatesalso ResidueType
00045     glycein G*/
00046 IMPATOMEXPORT extern const ResidueType GLY;
00047 #ifndef IMP_DOXYGEN
00048 /* Code currently assumes that all indices between GLY.get_index()
00049    and TRP.get_index() being amino acids */
00050 /** alanine A*/
00051 IMPATOMEXPORT extern const ResidueType ALA;
00052 /** valine V*/
00053 IMPATOMEXPORT extern const ResidueType VAL;
00054 /** leucine L*/
00055 IMPATOMEXPORT extern const ResidueType LEU;
00056 /** isoleucine I*/
00057 IMPATOMEXPORT extern const ResidueType ILE;
00058 /** serine S*/
00059 IMPATOMEXPORT extern const ResidueType SER;
00060 /** threonine T*/
00061 IMPATOMEXPORT extern const ResidueType THR;
00062 /** cystein C*/
00063 IMPATOMEXPORT extern const ResidueType CYS;
00064 /** metthionine M*/
00065 IMPATOMEXPORT extern const ResidueType MET;
00066 /** proline P*/
00067 IMPATOMEXPORT extern const ResidueType PRO;
00068 /** aspartic acid D*/
00069 IMPATOMEXPORT extern const ResidueType ASP;
00070 /** asparagine N*/
00071 IMPATOMEXPORT extern const ResidueType ASN;
00072 /** glutamine Q*/
00073 IMPATOMEXPORT extern const ResidueType GLU;
00074 /** glutamic acid E*/
00075 IMPATOMEXPORT extern const ResidueType GLN;
00076 /** lysine K*/
00077 IMPATOMEXPORT extern const ResidueType LYS;
00078 /** arginine N*/
00079 IMPATOMEXPORT extern const ResidueType ARG;
00080 /** histidine H*/
00081 IMPATOMEXPORT extern const ResidueType HIS;
00082 /** phynylaline F*/
00083 IMPATOMEXPORT extern const ResidueType PHE;
00084 /** tyrosine Y */
00085 IMPATOMEXPORT extern const ResidueType TYR;
00086 /** tryptophan W */
00087 IMPATOMEXPORT extern const ResidueType TRP;
00088 /** ACE */
00089 IMPATOMEXPORT extern const ResidueType ACE;
00090 /** end group */
00091 IMPATOMEXPORT extern const ResidueType NH2;
00092 /* Code currently assumes that all indices between ADE.get_index()
00093    and DTHY.get_index() being nucleic acid */
00094 /** adenine (RNA) */
00095 IMPATOMEXPORT extern const ResidueType ADE;
00096 /** uracil (RNA) */
00097 IMPATOMEXPORT extern const ResidueType URA;
00098 /** cytosine (RNA) */
00099 IMPATOMEXPORT extern const ResidueType CYT;
00100 /** guanine (RNA) */
00101 IMPATOMEXPORT extern const ResidueType GUA;
00102 /** thymine (RNA) */
00103 IMPATOMEXPORT extern const ResidueType THY;
00104 /** adenine (DNA) */
00105 IMPATOMEXPORT extern const ResidueType DADE;
00106 /** uracil (DNA) */
00107 IMPATOMEXPORT extern const ResidueType DURA;
00108 /** cytosine (DNA) */
00109 IMPATOMEXPORT extern const ResidueType DCYT;
00110 /** guanine (DNA) */
00111 IMPATOMEXPORT extern const ResidueType DGUA;
00112 /** thymine (DNA) */
00113 IMPATOMEXPORT extern const ResidueType DTHY;
00114 #endif
00115 /*@}*/
00116 
00117 
00118 //! A decorator for a residue.
00119 /**
00120    As with the Atom, the names of residues may be expanded
00121    dynamically. This can be easily done in an analogous manner when we
00122    need it.
00123    \ingroup hierarchy
00124    \ingroup decorators
00125  */
00126 class IMPATOMEXPORT Residue: public Hierarchy
00127 {
00128 public:
00129   IMP_DECORATOR(Residue, Hierarchy);
00130   //! Add the required attributes to the particle and create a Residue
00131   static Residue setup_particle(Particle *p, ResidueType t= UNK,
00132                                  int index=-1, int insertion_code = 32) {
00133     p->add_attribute(get_residue_type_key(), t.get_index());
00134     p->add_attribute(get_index_key(), index);
00135     p->add_attribute(get_insertion_code_key(), insertion_code);
00136     // insertion code 32 is for space
00137     if (!Hierarchy::particle_is_instance(p)) {
00138       Hierarchy::setup_particle(p);
00139     }
00140     Residue ret(p);
00141     ret.set_residue_type(t);
00142     return ret;
00143   }
00144 
00145   //! Copy data from the other Residue to the particle p
00146   static Residue setup_particle(Particle *p, Residue o) {
00147     return setup_particle(p, o.get_residue_type(),
00148                           o.get_index(),
00149                           o.get_insertion_code());
00150   }
00151 
00152   static bool particle_is_instance(Particle *p) {
00153     return p->has_attribute(get_residue_type_key())
00154       && p->has_attribute(get_index_key())
00155       && p->has_attribute(get_insertion_code_key())
00156       && Hierarchy::particle_is_instance(p);
00157   }
00158 
00159   ResidueType get_residue_type() const {
00160     return ResidueType(get_particle()->get_value(get_residue_type_key()));
00161   }
00162 
00163   //! Update the stored ResidueType and the atom::Hierarchy::Name.
00164   void set_residue_type(ResidueType t);
00165 
00166   bool get_is_protein() const {
00167     return get_residue_type().get_index() < ADE.get_index();
00168   }
00169 
00170   bool get_is_dna() const {
00171     return get_residue_type().get_index() >= DADE.get_index()
00172       && get_residue_type().get_index() <= DTHY.get_index();
00173   }
00174 
00175   bool get_is_rna() const {
00176     return get_residue_type().get_index() >= ADE.get_index()
00177       && get_residue_type().get_index() < DADE.get_index();
00178   }
00179 
00180   //! The residues index in the chain
00181   IMP_DECORATOR_GET_SET(index, get_index_key(),
00182                         Int, Int);
00183 
00184   char get_insertion_code() const {
00185     return char(get_particle()->get_value(get_insertion_code_key()));
00186   }
00187 
00188   void set_insertion_code(char insertion_code) {
00189     return get_particle()->set_value(get_insertion_code_key(), insertion_code);
00190   }
00191 
00192   static IntKey get_index_key();
00193 
00194   static IntKey get_residue_type_key();
00195 
00196   static IntKey get_insertion_code_key();
00197 };
00198 
00199 IMP_OUTPUT_OPERATOR(Residue);
00200 
00201 IMP_DECORATORS(Residue, Hierarchies);
00202 /** \decorators{Residue}
00203 */
00204 /** \decoratorstemp{Residue}
00205 */
00206 
00207 /** Return the chain containing the residue.
00208     \throw ValueException if no residue is found, unless
00209     nothrow is true.
00210     \relatesalso Residue */
00211 IMPATOMEXPORT Chain get_chain(Residue rd, bool nothrow=false);
00212 
00213 /** \relatesalso Residue
00214 
00215     Return the residue from the same chain with one
00216     higher index, or Residue().
00217 
00218     \note Currently, this function only works if
00219     the parent of rd is the chain. This should be fixed
00220     later. Ask if you need it.
00221 
00222     The return type is Hierarchy since the particle
00223     representing the next residue might not
00224     be a Residue particle.
00225  */
00226 IMPATOMEXPORT Hierarchy get_next_residue(Residue rd);
00227 
00228 IMPATOM_END_NAMESPACE
00229 
00230 #endif  /* IMPATOM_RESIDUE_H */