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-2018.
//
// 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>


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


      // Docu in base class
      void endElement(const XMLCh* const /*uri*/, const XMLCh* const /*local_name*/, const XMLCh* const qname) override;

      // Docu in base class
      void startElement(const XMLCh* const /*uri*/, const XMLCh* const /*local_name*/, const XMLCh* const qname, const xercesc::Attributes& attributes) override;

      // Docu in base class
      void characters(const XMLCh* const chars, const XMLSize_t length) override;

      //Docu in base class
      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);

      virtual LOADDETAIL getLoadDetail() const override;

      virtual 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 writeSpectrum_(std::ostream& os, const SpectrumType& spec, Size s,
                          Internal::MzMLValidator& validator, bool renew_native_ids,
                          std::vector<std::vector< ConstDataProcessingPtr > >& dps);

      void writeChromatogram_(std::ostream& os, const ChromatogramType& chromatogram, Size c, Internal::MzMLValidator& validator);

      template <typename ContainerT>
      void writeContainerData_(std::ostream& os, const PeakFileOptions& pf_options_, const ContainerT& container, String array_type);

      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& default_arr_length, const PeakFileOptions& peak_file_options,
                                    SpectrumType& spectrum);

      void populateChromatogramsWithData_(std::vector<MzMLHandlerHelper::BinaryData>& input_data,
                                          Size& default_arr_length, const PeakFileOptions& peak_file_options,
                                          ChromatogramType& inp_chromatogram);

      template <typename DataType>
      void writeBinaryDataArray_(std::ostream& os, const PeakFileOptions& pf_options_, std::vector<DataType> data_to_encode, bool is32bit, String array_type);

      void writeHeader_(std::ostream& os, const MapType& exp, std::vector<std::vector< ConstDataProcessingPtr > >& dps, Internal::MzMLValidator& validator);

      void fillChromatogramData_();

      void handleCVParam_(const String& parent_parent_tag, const String& parent_tag, /*  const String & cvref, */ 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);

      void writeUserParam_(std::ostream& os, const MetaInfoInterface& meta, UInt indent, String path, Internal::MzMLValidator& validator) const;

      ControlledVocabulary::CVTerm getChildWithName_(const String& parent_accession, const String& name) const;

      void writeSoftware_(std::ostream& os, const String& id, const Software& software, Internal::MzMLValidator& validator);

      void writeSourceFile_(std::ostream& os, const String& id, const SourceFile& software, Internal::MzMLValidator& validator);

      void writeDataProcessing_(std::ostream& os, const String& id, const std::vector< ConstDataProcessingPtr >& dps, Internal::MzMLValidator& validator);

      void writePrecursor_(std::ostream& os, const Precursor& precursor, Internal::MzMLValidator& validator);

      void writeProduct_(std::ostream& os, const Product& product, 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;


      // 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_;
      Map<String, std::vector<SemanticValidator::CVTerm> > ref_param_;
      Map<String, SourceFile> source_files_;
      Map<String, Sample> samples_;
      Map<String, Software> software_;
      Map<String, Instrument> instruments_;
      Map<String, std::vector< DataProcessingPtr > > processing_;
      String default_processing_;

      struct SpectrumData
      {
        std::vector<BinaryData> data;
        Size default_array_length;
        SpectrumType spectrum;
        bool skip_data;
      };

      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, long> > spectra_offsets_;
      std::vector<std::pair<std::string, long> > chromatograms_offsets_;

      const ProgressLogger& logger_;

      Interfaces::IMSDataConsumer* consumer_{ nullptr };

      UInt scan_count_{ 0 };  //< number of scans which pass the options-filter
      UInt chromatogram_count_{ 0 }; //< number of chromatograms which pass the options-filter
      Int scan_count_total_{ -1 }; //< total number of scans in mzML file (according to 'count' attribute)
      Int chrom_count_total_{ -1 }; //< total number of chromatograms in mzML file (according to 'count' attribute)

      ControlledVocabulary cv_;
      CVMappings mapping_;

      UInt selected_ion_count_{ 0 };
    };

    //--------------------------------------------------------------------------------

  } // namespace Internal
} // namespace OpenMS