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_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;

          bool hasType(String type) {return values.has(type);}
          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 // _Saveframe_category  assigned_chemical_shifts

      {
        public:
          NMRAtomDataSet(NMRStarFile* parent);

          String                     name;
          String                     label;
          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;
          String   submission_date;

      };

      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();

          ChemicalUnit const&  getChemicalUnit(Position i) const { return chemical_units[i]; }
          ChemicalUnit&  getChemicalUnit(Position i) { return chemical_units[i]; }

          Size getNumberOfChemicalUnits() const {return chemical_units.size(); }

          // 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, const String& chemical_unit);

          virtual ~BALLToBMRBMapper() {}



          const Chain* getChain() const {return chain_;}

          void setChain(Chain const& chain) { chain_ = &chain;
                                              num_mismatches_ = -1;
                                              num_gaps_ = -1;}

          void setNMRStarFile(NMRStarFile const& nmrfile) {nmr_data_ = &nmrfile;
                                                           num_mismatches_ = -1;
                                                           num_gaps_ = -1;}

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

          void setNMRAtomDataSet(NMRAtomDataSet const& nmr_atom_data_set){nmr_atom_data_set_= &nmr_atom_data_set;}

          bool setNMRAtomDataSetByName(String const& chemical_unit_name);

          // Get the NMRAtomDataSet 
          const NMRAtomDataSet* getNMRAtomDataSet() const{return nmr_atom_data_set_;}

          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 getNumberOfGaps(){return num_gaps_;}

          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_;
          const NMRAtomDataSet*   nmr_atom_data_set_;
          Position                nmr_atom_data_set_index_;
          int                     num_mismatches_;
          int                     num_gaps_;
          bool                    valid_;

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

      };



      NMRStarFile();

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

      ~NMRStarFile();



      bool read();

      /*  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& chemical_unit,
                        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_;};

      MolecularSystem& getMolecularInformation() {return molecular_system_;};


      const MolecularSystem::ChemicalUnit& getChemicalUnitByLabel(String const& label) const;

      MolecularSystem::ChemicalUnit& getChemicalUnitByLabel(String const& label);


      bool hasSampleCondition(String name);

      bool hasSampleCondition(String name) const;

      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();};

      bool hasShiftReferenceSet(String name);

      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(Position i);

      const NMRStarFile::MonomericPolymer& getMonomericPolymer(Position i) const;

      NMRStarFile::MonomericPolymer& getMonomericPolymer(const String& name);

      const NMRStarFile::MonomericPolymer& getMonomericPolymer(const String& name) const;

      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) const;

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

      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);

      float valueToFloat_(String value);

      int valueToInt_(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