MzMLHandler.h

Go to the documentation of this file.

// --------------------------------------------------------------------------
//                   OpenMS -- Open-Source Mass Spectrometry
// --------------------------------------------------------------------------
// Copyright The OpenMS Team -- Eberhard Karls University Tuebingen,
// ETH Zurich, and Freie Universitaet Berlin 2002-2023.
//
// This software is released under a three-clause BSD license:
//  * Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//  * Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//  * Neither the name of any author or any participating institution
//    may be used to endorse or promote products derived from this software
//    without specific prior written permission.
// For a full list of authors, refer to the file AUTHORS.
// --------------------------------------------------------------------------
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL ANY OF THE AUTHORS OR THE CONTRIBUTING
// INSTITUTIONS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
// OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
// OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
// ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// --------------------------------------------------------------------------
// $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)
// - instrumentConfigurationRef attribute for scan (why should the instrument change between scans? - warning if used)
// - 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 String& filename, const String& version, const ProgressLogger& logger);
 
      MzMLHandler(const MapType& exp, const String& filename, const String& version, const ProgressLogger& logger);
 
      ~MzMLHandler() override;
 
 
      void endElement(const XMLCh* const /*uri*/, const XMLCh* const /*local_name*/, const XMLCh* const qname) override;
 
      void startElement(const XMLCh* const /*uri*/, const XMLCh* const /*local_name*/, const XMLCh* const qname, const xercesc::Attributes& attributes) override;
 
      void characters(const XMLCh* const chars, const XMLSize_t length) override;
 
      void writeTo(std::ostream& os) override;
 
 
 
      void setOptions(const PeakFileOptions& opt);
 
      PeakFileOptions& getOptions();
 
 
      void getCounts(Size& spectra_counts, Size& chromatogram_counts);
 
 
      void setMSDataConsumer(Interfaces::IMSDataConsumer* consumer);
 
      LOADDETAIL getLoadDetail() const override;
 
      void setLoadDetail(const LOADDETAIL d) override;
 
protected:
 
      MzMLHandler(const String& filename, const String& version, const ProgressLogger& logger);
 
      typedef MapType::PeakType PeakType;
      typedef MapType::ChromatogramPeakType ChromatogramPeakType;
      typedef MSSpectrum SpectrumType;
      typedef MSChromatogram ChromatogramType;
 
      typedef MzMLHandlerHelper::BinaryData BinaryData;
 
 
      void populateSpectraWithData_();
 
      void populateChromatogramsWithData_();
 
      void addSpectrumMetaData_(const std::vector<MzMLHandlerHelper::BinaryData>& input_data,
                                const Size n,
                                SpectrumType& spectrum) const;
 
      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 String& parent_parent_tag,
                          const String& parent_tag,
                          const String& accession,
                          const String& name,
                          const String& value,
                          const String& unit_accession = "");
 
      void handleUserParam_(const String& parent_parent_tag,
                            const String& parent_tag,
                            const String& name,
                            const String& type,
                            const String& value,
                            const 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 String& array_type);
 
      template <typename DataType>
      void writeBinaryDataArray_(std::ostream& os,
                                 const PeakFileOptions& options,
                                 std::vector<DataType>& data,
                                 bool is32bit,
                                 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 String& path, const Internal::MzMLValidator& validator, const std::set<String>& exclude = {}) const;
 
      void writeSoftware_(std::ostream& os, const String& id, const Software& software, const Internal::MzMLValidator& validator);
 
      void writeSourceFile_(std::ostream& os, const String& id, const SourceFile& software, const Internal::MzMLValidator& validator);
 
      void writeDataProcessing_(std::ostream& os, const 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);
 
      String writeCV_(const ControlledVocabulary::CVTerm& c, const DataValue& metaValue) const;
 
      bool validateCV_(const ControlledVocabulary::CVTerm& c, const String& path, const Internal::MzMLValidator& validator) const;
 
      ControlledVocabulary::CVTerm getChildWithName_(const String& parent_accession, const 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 };
      bool skip_chromatogram_{ false };
      bool rt_set_{ false };
      String current_id_;
      std::map<String, std::vector<SemanticValidator::CVTerm> > ref_param_;
      std::map<String, SourceFile> source_files_;
      std::map<String, Sample> samples_;
      std::map<String, Software> software_;
      std::map<String, Instrument> instruments_;
      mutable std::map<std::pair<String, String>, bool> cached_terms_;
      std::map<String, std::vector< DataProcessingPtr > > processing_;
      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