NMRStarFile.h

Go to the documentation of this file.

// -*- Mode: C++; tab-width: 2; -*-
// vi: set ts=2:
//

#ifndef BALL_FORMAT_NMRSTARFILE_H
#define BALL_FORMAT_NMRSTARFILE_H

#ifndef BALL_FORMAT_CIFFILE_H
# include <BALL/FORMAT/CIFFile.h>
#endif

#ifndef BALL_COMMON_LIMITS_H
# include <BALL/COMMON/limits.h>
#endif

#ifndef BALL_KERNEL_PROTEIN_H
# include <BALL/KERNEL/protein.h>
#endif

#ifndef BALL_STRUCTURE_PEPTIDES_H
# include <BALL/STRUCTURE/peptides.h>
#endif

#include <vector>

namespace BALL 
{
  class BALL_EXPORT NMRStarFile
    : public CIFFile
  {
    public:

      // constant variables to denote unknown values
      static const float    FLOAT_VALUE_NA;
      static const int      INT_VALUE_NA;

      static const Position POSITION_VALUE_NA;
      

      class BALL_EXPORT SampleCondition
      {
        public:
          SampleCondition();
  
          // saveframe name -- referenced in the sample_condition_label 
          // of  the saveframe "assigned_chemical_shifts"   
          String               name;
          // Accoring to the NMRStarFile 2.1 documentation 
          // the first entry MUST BE "_Variable_type".
          // This is why we are allowed to map per type :-)
          vector<String>        types;
          StringHashMap<float>  values;
          StringHashMap<float>  errors;
          StringHashMap<String> units;
        
          std::ostream& operator >> (std::ostream& s);
      };
  
      class BALL_EXPORT Sample
      {
        public:
        
          class BALL_EXPORT Component
          {
            public:
              Component();
              void clear(); 
              
              String   label;
              float    concentration_value;
              String   value_unit;
              float    concentration_min;
              float    concentration_max;
              String   isotopic_labeling;

              std::ostream& operator >> (std::ostream& s);
          };

          Sample(); 
          void clear(); 

          String label;
          String type;
          String details;
          vector <Component> components;

          std::ostream& operator >> (std::ostream& s);
      };

      class BALL_EXPORT ShiftReferenceElement
      {
        public:
          ShiftReferenceElement();

          String    mol_common_name;
          String    atom_type;
          Position  isotope_number;
          String    atom_group;
          String    shift_units;
          float     shift_value;
          String    reference_method;
          String    reference_type;
          float     indirect_shift_ratio;

          std::ostream& operator >> (std::ostream& s);
      };

      class BALL_EXPORT ShiftReferenceSet
      {
        public: 
          ShiftReferenceSet();
        
          // The saveframe's name = set name
          // can be referenced in the saveframe "assigned_chemical_shifts"
          String                             name;  
          std::vector<ShiftReferenceElement> elements;

          std::ostream& operator >> (std::ostream& s);
      };

      class BALL_EXPORT NMRAtomData
      {
        public:
          NMRAtomData();

          Position  atom_ID;
          Position  residue_seq_code;
          String    residue_label;
          String    atom_name;
          char      atom_type;
          float     shift_value;
          float     error_value;
          Position  ambiguity_code;
          
          bool operator == (const NMRAtomData& atom) const;
          std::ostream& operator >> (std::ostream& s);
      };

            
      class BALL_EXPORT NMRAtomDataSet
      {
        public:
          NMRAtomDataSet(NMRStarFile* parent);

          String                    name; 
          std::vector<NMRAtomData>  atom_data;
          String                    condition;  
          String                    reference;  
          std::vector<String>       samples;   

          std::ostream& operator >> (std::ostream& s);
  
        protected: 
          NMRStarFile*              parent_;
      };

      class BALL_EXPORT EntryInformation
      {
        public:
          EntryInformation();
          ~EntryInformation();

          std::ostream& operator >> (std::ostream& s);
          void clear(); 

          String   entry_type;
          String   BMRB_accession_code;
          String   NMR_STAR_version;
          String   experimental_method;
      };
      
      class BALL_EXPORT MonomericPolymer
      {
        public:
          class BALL_EXPORT HomologDB 
          {
            public:
              HomologDB();
              
              std::ostream& operator >> (std::ostream& s); 
              void clear(); 

              String  name;
              String  accession_code;
              String  entry_mol_name;
              float   seq_to_submitted_percentage;
              float   subject_length;
              float   seq_identity;
              float   seq_positive;
              float   homology_expectation_value;  
          };


          MonomericPolymer(); 

          String   label_name;
          String   type;
          String   polymer_class;
          String   common_name;
          String   name_variant;
          float    molecular_mass;
          String   details;   
          //  polymer residue sequence information
          int      number_of_residues;
          String   residue_sequence; 
          // we want to allow things like resid 137A, so we cannot use Index
          // key: index -- value: aminoacidname
          StringHashMap<String>   residues_by_index;
          vector<HomologDB>       homolog_database_entries;   
          
          std::ostream& operator >> (std::ostream& s); 
          void clear(); 
      };


      class BALL_EXPORT MolecularSystem
      { 
        // System related information
        public:
          class BALL_EXPORT RelatedDB
          {
            public:
              RelatedDB();

              std::ostream& operator >> (std::ostream& s); 
              void clear(); 

              String    name;
              String    accession_code;
              String    entry_mol_name;
              String    relation_type;
              String    details;
          };
          
                          
          // Central class for convenience
          class BALL_EXPORT ChemicalUnit
          {
            public:
              ChemicalUnit();  
              std::ostream& operator >> (std::ostream& s); 
              void clear();  

              String            component_name;
              String            label;
              MonomericPolymer* monomeric_polymer; 
              NMRAtomDataSet*   shifts;             
          };


          MolecularSystem(); 
          ~MolecularSystem(); 

          // Name of the molecular system
          String                system_name;
          String                abbreviation_common;
          vector<ChemicalUnit>  chemical_units;  
          String                system_physical_state;
          String                system_oligomer_state;
          String                system_paramagnetic;
          String                system_thiol_state;
          float                 system_molecular_weight;  
          // related entries in various DB's
          vector<RelatedDB>     related_database_entries;
          

          std::ostream& operator >> (std::ostream& s); 
          void clear(); 
      };


      class BALL_EXPORT NMRSpectrometer
      {
        public:
          String    name;
          String    manufacturer;
          String    model;
          float     field_strength;

          std::ostream& operator >> (std::ostream& s);
      };

      
      class BALL_EXPORT BALLToBMRBMapper
      {
        public:
          
          //<saveframe_id, atom_id_in_nmr_atom_data_set>
          typedef std::pair<Position, Position>             BMRBIndex;
          typedef std::map<Atom const* , BMRBIndex>         BALLToBMRBMapping; 
          typedef std::map<const NMRAtomData*, Atom const*> BMRBToBALLMapping;
          //TODO: Dont use pointer but something more sophisticated!


          BALLToBMRBMapper();
                  
          BALLToBMRBMapper(Chain const& chain, const NMRStarFile& nmr_data);  
          
          virtual ~BALLToBMRBMapper() {}
          


          const Chain* getChain() const {return chain_;}
          
          void setChain(Chain const& chain) { chain_ = &chain; 
                                              num_mismatches_ = -1; 
                                              num_gabs_ = -1;}
          
          void setNMRStarFile(NMRStarFile const& nmrfile) {nmr_data_ = &nmrfile;
                                                           num_mismatches_ = -1; 
                                                           num_gabs_ = -1;}

          const NMRStarFile* getNMRStarFile() const {return nmr_data_;} 

          BALLToBMRBMapping& getBALLToBMRBMapping() {return ball_to_bmrb_map_;}

          const BALLToBMRBMapping& getBALLToBMRBMapping() const {return ball_to_bmrb_map_;}
          
          BMRBToBALLMapping& getBMRBToBALLMapping() {return bmrb_to_ball_map_;}

          const BMRBToBALLMapping& getBMRBToBALLMapping() const {return bmrb_to_ball_map_;}

          int getNumberOfMismatches(){return num_mismatches_;}
          
          int getNumberOfGabs(){return num_gabs_;}

          bool isMapped(const NMRAtomData& nmr_atom) const;
          
          const Atom* getBALLAtom(const NMRAtomData& nmr_atom) const;

          bool isMapped(Atom const* atom) const;
          
          BMRBIndex operator () (const Atom* atom);
          
          bool createTrivialMapping();
          
          bool createMapping(const String& aligned_ball_sequence,
                             const String& aligned_nmrstar_sequence);

          void clear();


        protected:  
          
          Peptides::NameConverter name_converter_;

          
          BALLToBMRBMapping       ball_to_bmrb_map_;

          BMRBToBALLMapping       bmrb_to_ball_map_;

          // NOTE: do *not* attempt to delete these pointers!
          const Chain*            chain_;
          const NMRStarFile*      nmr_data_;
          int                     num_mismatches_; 
          int                     num_gabs_; 


        private:
          const Atom* findNMRAtom_(const NMRAtomData& atom) const;

      };
      


      NMRStarFile();
      
      NMRStarFile(const String& file_name, File::OpenMode open_mode = std::ios::in)
        throw(Exception::FileNotFound);
      
      ~NMRStarFile();
  


      bool read()
        throw(Exception::ParseError);

      /*  Read an NMRStarFile and assign the shifts to the
          given AtomContainer using a trivial standard mapping.
          If the AtomContainer is a system, the first chain in chosen.  
       
          @param  ac AtomContainer to which the NMRStarfile's shift should be assigned.
          @return bool - <tt>true</tt> if reading the file was successful 
       */
      //TODO to be able to use this function, further functions getMapping() and assign() are needed.
      bool read(AtomContainer& ac);

      bool assignShifts(BALLToBMRBMapper& ball_to_bmrb_mapping); 

      bool assignShifts(AtomContainer& ac, const String& aligned_ball_sequence,
                        const String& aligned_nmrstar_sequence);  

      Size getNumberOfAtoms() const;

      Size getNumberOfShiftsAssigned() const {return number_of_assigned_shifts_;};

      const std::vector<NMRAtomDataSet>& getNMRData() const;
      
      const EntryInformation& getEntryInformation() const {return entry_information_;};

      const MolecularSystem& getMolecularInformation() const {return molecular_system_;};

      SampleCondition& getSampleConditionByName(String name);

      const SampleCondition& getSampleConditionByName(String name) const;

      SampleCondition& getSampleCondition(Position i) {return sample_conditions_[i];};

      const SampleCondition& getSampleCondition(Position i) const {return sample_conditions_[i];};

      Size getNumberOfSampleConditions() const {return sample_conditions_.size();};

      const std::vector<SampleCondition>& getSampleConditions() const {return sample_conditions_;};

      std::vector<SampleCondition>& getSampleConditions() {return sample_conditions_;};

      // addSampleCondition TODO!!
    
      std::vector<Sample> getSamples()  const {return samples_;};
      //const std::vector<Sample>& getSamples() const {return samples_;};
      
      Size getNumberOfSamples() const {return samples_.size();};
      
      bool hasSample(String label) const;
      
      Sample getSample(Position i) const;

      Sample getSample(String label) const;

      std::vector<ShiftReferenceSet>& getShiftReferenceSets() {return shift_references_;}; 
      const std::vector<ShiftReferenceSet>& getShiftReferenceSets() const  {return shift_references_;}; 

      Size getNumberOfShiftReferenceSets() const {return shift_references_.size();};
  
      ShiftReferenceSet& getShiftReferenceSet(Position i) {return shift_references_[i];};   
      const ShiftReferenceSet& getShiftReferenceSet(Position i) const {return shift_references_[i];}; 
    
      const ShiftReferenceSet& getShiftReferenceSetByName(String name) const; 
      ShiftReferenceSet& getShiftReferenceSetByName(String name);
      

      std::vector<NMRSpectrometer>& getNMRSpectrometers() {return nmr_spectrometers_;};
      const std::vector<NMRSpectrometer>& getNMRSpectrometers() const {return nmr_spectrometers_;};
    
      Size getNumberOfNMRSpectrometers() const  {return nmr_spectrometers_.size();};

      NMRSpectrometer& getNMRSpectrometer(Position i);
      const NMRSpectrometer& getNMRSpectrometer(Position i) const;
      
      NMRSpectrometer& getNMRSpectrometerByName(String name);
      const NMRSpectrometer& getNMRSpectrometerByName(String name) const;

      String getNMRSpectrometerManufacturer(Position i) const;
    
      float getNMRSpectrometerFieldStrength(Position i) const;
    

      NMRStarFile::MonomericPolymer& getMonomericPolymer(const String& name) throw(Exception::OutOfRange);
      const NMRStarFile::MonomericPolymer& getMonomericPolymer(const String& name) const throw(Exception::OutOfRange);
      
      Size getNumberOfMonomericPolymers() const {return monomeric_polymers_.size();};
    
      vector<MonomericPolymer> getMonomericPolymers() const {return monomeric_polymers_;};

      bool hasMonomericPolymer(String name) const; 

      bool isMonomericPolymer(String chemical_unit_label); 

      //TODO: Store changes/additions as Saveframes also in CIFFile
      void addMonomericPolymer(MonomericPolymer mp);
    

      String getResidueSequence(Position i=0) const;
      
      bool hasHshifts() const {return has_H_shifts_;};
      
      bool hasCshifts() const {return has_C_shifts_;};
      
      bool hasNshifts() const {return has_N_shifts_;};




      bool operator == (const NMRStarFile& f);

      bool operator != (const NMRStarFile& f);
  
      void clear();

      
    private:

      /*_ @name NMRStar file specific Help-Methods
       */
      //_@{

  
      void readEntryInformation_();

      void readMolSystem_();
      
      void readMonomericPolymers_();
      
      void readSampleConditions_();

      void readShiftReferences_();

      void readShifts_();
    
      void readSamples_();

      void readNMRSpectrometer_();
      
      void findDependiencies_();

      void setSpecialCharacters_(String characters);

      bool isValidSingleValue_(String value);
      
      bool assignShifts_(BALLToBMRBMapper& pdb_to_bmrb_mapping);

      //_@}
      /*_ @name NMRStar file specific attributes
      */
      //_@{

      /*_ A flag indicating validity of this instance. A sole NMRStarFile
        instance cannot be valid, because it does not have any information.
      */
      bool valid_;

      Size number_of_shift_sets_; 

      Size number_of_assigned_shifts_;

      EntryInformation entry_information_;
      
      MolecularSystem molecular_system_;

      std::vector<NMRAtomDataSet> atom_data_sets_;

      std::vector<SampleCondition> sample_conditions_;
  
      std::vector<Sample> samples_;

      std::vector<ShiftReferenceSet> shift_references_;

      std::vector<NMRSpectrometer> nmr_spectrometers_; 

      vector<MonomericPolymer> monomeric_polymers_; 
      
      bool has_H_shifts_;
      bool has_C_shifts_;
      bool has_N_shifts_;

      // a dummy saveframe
      SaveFrame dummy_saveframe_; 
    
      // a dummy sample condition
      SampleCondition dummy_sample_condition_;
      
      // a dummy sample
      Sample dummy_sample_;

      // a dummy shift reference set
      ShiftReferenceSet dummy_shift_reference_set_; 
    
      // a dummy nmr spectrometer
      NMRSpectrometer dummy_NMR_spectrometer_; 

      // a dummy nmr spectrometer
      MonomericPolymer dummy_monomeric_polymer_; 

      String special_characters_;
      //_@}
  };

} // Namespace BALL

#endif // BALL_FORMAT_NMRSTARFILE_H

---