MzMLHandler.h

Go to the documentation of this file.

// Copyright (c) 2002-present, OpenMS Inc. -- EKU Tuebingen, ETH Zurich, and FU Berlin
// SPDX-License-Identifier: BSD-3-Clause
//
// --------------------------------------------------------------------------
// $Maintainer: Timo Sachsenberg $
// $Authors: Marc Sturm, Chris Bielow, Hannes Roest $
// --------------------------------------------------------------------------
 
#pragma once
 
#include <OpenMS/CONCEPT/Helpers.h>
#include <OpenMS/CONCEPT/ProgressLogger.h>
 
#include <OpenMS/DATASTRUCTURES/CVMappings.h>
 
#include <OpenMS/KERNEL/StandardTypes.h>
#include <OpenMS/KERNEL/MSExperiment.h>
 
#include <OpenMS/FORMAT/HANDLERS/XMLHandler.h>
#include <OpenMS/FORMAT/HANDLERS/MzMLHandlerHelper.h>
 
#include <OpenMS/FORMAT/OPTIONS/PeakFileOptions.h>
#include <OpenMS/FORMAT/ControlledVocabulary.h>
#include <OpenMS/FORMAT/VALIDATORS/SemanticValidator.h>
 
#include <map>
 
 
//MISSING:
// - more than one selected ion per precursor (warning if more than one)
// - scanWindowList for each acquisition separately (currently for the whole spectrum only)
// - scanSettingsRef attribute for instrumentConfiguration tag (currently no information there because of missing mapping file entry - warning if used)
 
// xs:id/xs:idref prefix list
// - sf_ru : sourceFile (run)
// - sf_sp : sourceFile (spectrum)
// - sf_pr : sourceFile (precursor)
// - sf_ac : sourceFile (acquisition)
// - sa    : sample
// - ic    : instrumentConfiguration
// - so_dp : software (data processing)
// - so_in : software (instrument)
// - dp_sp : dataProcessing (spectrum)
// - dp_bi : dataProcessing (binary data array)
// - dp_ch : dataProcessing (chromatogram)
 
namespace OpenMS
{
  namespace Interfaces
  {
    class IMSDataConsumer;
  }
 
  namespace Internal
  {
    class MzMLValidator;
 
    typedef PeakMap MapType;
    typedef MSSpectrum SpectrumType;
    typedef MSChromatogram ChromatogramType;
 
    class OPENMS_DLLAPI MzMLHandler :
      public XMLHandler
    {
public:
 
 
      MzMLHandler(MapType& exp, const std::string& filename, const std::string& version, const ProgressLogger& logger);
 
      MzMLHandler(const MapType& exp, const std::string& filename, const std::string& version, const ProgressLogger& logger);
 
      ~MzMLHandler() override;
 
 
      void onEndElement(const char16_t* qname) override;
 
      void onStartElement(const char16_t* qname, const XMLAttributes& attributes) override;
 
      void onCharacters(const char16_t* chars, Size length) override;
 
      bool tryOnCharactersUTF8(const char* chars, Size length) override;
 
      bool tryOnStartElementUTF8(std::string_view qname, const XMLAttributes& attributes) override;
 
      bool tryOnEndElementUTF8(std::string_view qname) override;
 
      void writeTo(std::ostream& os) override;
 
 
 
      void setOptions(const PeakFileOptions& opt);
 
      PeakFileOptions& getOptions();
 
 
      void getCounts(Size& spectra_counts, Size& chromatogram_counts);
 
      Size getSpectraRead() const;
 
 
      void setMSDataConsumer(Interfaces::IMSDataConsumer* consumer);
 
      LOADDETAIL getLoadDetail() const override;
 
      void setLoadDetail(const LOADDETAIL d) override;
 
protected:
 
      MzMLHandler(const std::string& filename, const std::string& version, const ProgressLogger& logger);
 
      typedef MapType::PeakType PeakType;
      typedef MapType::ChromatogramPeakType ChromatogramPeakType;
      typedef MSSpectrum SpectrumType;
      typedef MSChromatogram ChromatogramType;
 
      typedef MzMLHandlerHelper::BinaryData BinaryData;
 
 
      void requiredAttributeAsString_(std::string& value, const XMLAttributes& attributes, const char16_t* name) const;
 
      struct ParamBuffers_
      {
        std::string accession, name, value, unit_accession, type;
      };
      ParamBuffers_ param_buffers_;
 
      void startElement_(std::string_view tag_name, const XMLAttributes& attributes);
 
      void endElement_(std::string_view tag_name);
 
      void populateSpectraWithData_();
 
      void populateChromatogramsWithData_();
 
      void populateSpectraWithData_(std::vector<MzMLHandlerHelper::BinaryData>& input_data,
                                    Size& length,
                                    const PeakFileOptions& peak_file_options,
                                    SpectrumType& spectrum);
 
      void populateChromatogramsWithData_(std::vector<MzMLHandlerHelper::BinaryData>& input_data,
                                          Size& length,
                                          const PeakFileOptions& peak_file_options,
                                          ChromatogramType& chromatogram);
 
      void fillChromatogramData_();
 
      void handleCVParam_(const std::string& parent_parent_tag,
                          const std::string& parent_tag,
                          const std::string& accession,
                          const std::string& name,
                          const std::string& value,
                          const std::string& unit_accession = "");
 
      void handleUserParam_(const std::string& parent_parent_tag,
                            const std::string& parent_tag,
                            const std::string& name,
                            const std::string& type,
                            const std::string& value,
                            const std::string& unit_accession = "");
 
 
      void writeHeader_(std::ostream& os,
                        const MapType& exp,
                        std::vector<std::vector< ConstDataProcessingPtr > >& dps,
                        const Internal::MzMLValidator& validator);
 
 
      void writeSpectrum_(std::ostream& os,
                          const SpectrumType& spec,
                          Size spec_idx,
                          const Internal::MzMLValidator& validator,
                          bool renew_native_ids,
                          std::vector<std::vector< ConstDataProcessingPtr > >& dps);
 
      void writeChromatogram_(std::ostream& os,
                              const ChromatogramType& chromatogram,
                              Size chrom_idx,
                              const Internal::MzMLValidator& validator);
 
      template <typename ContainerT>
      void writeContainerData_(std::ostream& os, const PeakFileOptions& pf_options_, const ContainerT& container, const std::string& array_type);
 
      template <typename DataType>
      void writeBinaryDataArray_(std::ostream& os,
                                 const PeakFileOptions& options,
                                 std::vector<DataType>& data,
                                 bool is32bit,
                                 std::string array_type);
 
      void writeBinaryFloatDataArray_(std::ostream& os,
                                      const PeakFileOptions& options,
                                      const OpenMS::DataArrays::FloatDataArray& array,
                                      const Size spec_chrom_idx,
                                      const Size array_idx,
                                      bool is_spectrum,
                                      const Internal::MzMLValidator& validator);
 
      void writeUserParam_(std::ostream& os, const MetaInfoInterface& meta, UInt indent, const std::string& path, const Internal::MzMLValidator& validator, const std::set<std::string>& exclude = {}) const;
 
      void writeSoftware_(std::ostream& os, const std::string& id, const Software& software, const Internal::MzMLValidator& validator);
 
      void writeInstrument_(std::ostream& os, const std::string& id, const Instrument& instrument,
                            const std::string& software_id, const Internal::MzMLValidator& validator);
 
      void writeSourceFile_(std::ostream& os, const std::string& id, const SourceFile& software, const Internal::MzMLValidator& validator);
 
      void writeDataProcessing_(std::ostream& os, const std::string& id, const std::vector< ConstDataProcessingPtr >& dps, const Internal::MzMLValidator& validator);
 
      void writePrecursor_(std::ostream& os, const Precursor& precursor, const Internal::MzMLValidator& validator);
 
      void writeProduct_(std::ostream& os, const Product& product, const Internal::MzMLValidator& validator);
 
      std::string writeCV_(const ControlledVocabulary::CVTerm& c, const DataValue& metaValue) const;
 
      bool validateCV_(const ControlledVocabulary::CVTerm& c, const std::string& path, const Internal::MzMLValidator& validator) const;
 
      ControlledVocabulary::CVTerm getChildWithName_(const std::string& parent_accession, const std::string& name) const;
 
 
      // MEMBERS
 
      MapType* exp_{ nullptr };
 
      const MapType* cexp_{ nullptr };
 
      PeakFileOptions options_;
 
      SpectrumType spec_;
      ChromatogramType chromatogram_;
      std::vector<BinaryData> bin_data_;
      Size default_array_length_;
      bool in_spectrum_list_{ false };
      bool skip_spectrum_{ false };
      Size spectra_read_{ 0 };
      bool skip_chromatogram_{ false };
      bool rt_set_{ false };
      std::string current_id_;
      std::map<std::string, std::vector<SemanticValidator::CVTerm> > ref_param_;
      std::map<std::string, SourceFile> source_files_;
      std::map<std::string, Sample> samples_;
      std::map<std::string, Software> software_;
      std::map<std::string, Instrument> instruments_;
      std::string default_instrument_configuration_ref_;
      mutable std::map<std::pair<std::string, std::string>, bool> cached_terms_;
      std::map<std::string, std::vector< DataProcessingPtr > > processing_;
      std::string default_processing_;
      UInt selected_ion_count_{ 0 };
 
      struct SpectrumData
      {
        std::vector<BinaryData> data;
        Size default_array_length;
        SpectrumType spectrum;
      };
 
      std::vector<SpectrumData> spectrum_data_;
 
      struct ChromatogramData
      {
        std::vector<BinaryData> data;
        Size default_array_length;
        ChromatogramType chromatogram;
      };
 
      std::vector<ChromatogramData> chromatogram_data_;
 
      
      std::vector<std::pair<std::string, Int64> > spectra_offsets_; 
      std::vector<std::pair<std::string, Int64> > chromatograms_offsets_; 
 
      const ProgressLogger& logger_;
 
      Interfaces::IMSDataConsumer* consumer_{ nullptr };
 
      UInt scan_count_{ 0 };  
      UInt chromatogram_count_{ 0 }; 
      Int scan_count_total_{ -1 }; 
      Int chrom_count_total_{ -1 }; 
 
      const ControlledVocabulary& cv_;
      CVMappings mapping_;
 
    };
 
    //--------------------------------------------------------------------------------
 
  } // namespace Internal
} // namespace OpenMS