OpenMS
MzMLHandler.h
Go to the documentation of this file.
1 // Copyright (c) 2002-2023, The OpenMS Team -- EKU Tuebingen, ETH Zurich, and FU Berlin
2 // SPDX-License-Identifier: BSD-3-Clause
3 //
4 // --------------------------------------------------------------------------
5 // $Maintainer: Timo Sachsenberg $
6 // $Authors: Marc Sturm, Chris Bielow, Hannes Roest $
7 // --------------------------------------------------------------------------
8 
9 #pragma once
10 
11 #include <OpenMS/CONCEPT/Helpers.h>
13 
15 
18 
21 
25 
26 #include <map>
27 
28 
29 //MISSING:
30 // - more than one selected ion per precursor (warning if more than one)
31 // - scanWindowList for each acquisition separately (currently for the whole spectrum only)
32 // - instrumentConfigurationRef attribute for scan (why should the instrument change between scans? - warning if used)
33 // - scanSettingsRef attribute for instrumentConfiguration tag (currently no information there because of missing mapping file entry - warning if used)
34 
35 // xs:id/xs:idref prefix list
36 // - sf_ru : sourceFile (run)
37 // - sf_sp : sourceFile (spectrum)
38 // - sf_pr : sourceFile (precursor)
39 // - sf_ac : sourceFile (acquisition)
40 // - sa : sample
41 // - ic : instrumentConfiguration
42 // - so_dp : software (data processing)
43 // - so_in : software (instrument)
44 // - dp_sp : dataProcessing (spectrum)
45 // - dp_bi : dataProcessing (binary data array)
46 // - dp_ch : dataProcessing (chromatogram)
47 
48 namespace OpenMS
49 {
50  namespace Interfaces
51  {
52  class IMSDataConsumer;
53  }
54 
55  namespace Internal
56  {
57  class MzMLValidator;
58 
59  typedef PeakMap MapType;
60  typedef MSSpectrum SpectrumType;
62 
92  class OPENMS_DLLAPI MzMLHandler :
93  public XMLHandler
94  {
95 public:
96 
99 
101  MzMLHandler(MapType& exp, const String& filename, const String& version, const ProgressLogger& logger);
102 
104  MzMLHandler(const MapType& exp, const String& filename, const String& version, const ProgressLogger& logger);
105 
107  ~MzMLHandler() override;
109 
115 
117  void endElement(const XMLCh* const /*uri*/, const XMLCh* const /*local_name*/, const XMLCh* const qname) override;
118 
120  void startElement(const XMLCh* const /*uri*/, const XMLCh* const /*local_name*/, const XMLCh* const qname, const xercesc::Attributes& attributes) override;
121 
123  void characters(const XMLCh* const chars, const XMLSize_t length) override;
124 
126  void writeTo(std::ostream& os) override;
127 
129 
140 
142  void setOptions(const PeakFileOptions& opt);
143 
146 
148 
150  void getCounts(Size& spectra_counts, Size& chromatogram_counts);
151 
161 
165 
167  LOADDETAIL getLoadDetail() const override;
168 
170  void setLoadDetail(const LOADDETAIL d) override;
171 
172 protected:
173 
175  MzMLHandler(const String& filename, const String& version, const ProgressLogger& logger);
176 
185 
187 
192 
200 
208 
214  void addSpectrumMetaData_(const std::vector<MzMLHandlerHelper::BinaryData>& input_data,
215  const Size n,
216  SpectrumType& spectrum) const;
217 
233  void populateSpectraWithData_(std::vector<MzMLHandlerHelper::BinaryData>& input_data,
234  Size& length,
235  const PeakFileOptions& peak_file_options,
236  SpectrumType& spectrum);
237 
250  void populateChromatogramsWithData_(std::vector<MzMLHandlerHelper::BinaryData>& input_data,
251  Size& length,
252  const PeakFileOptions& peak_file_options,
253  ChromatogramType& chromatogram);
254 
257 
259  void handleCVParam_(const String& parent_parent_tag,
260  const String& parent_tag,
261  const String& accession,
262  const String& name,
263  const String& value,
264  const String& unit_accession = "");
265 
267  void handleUserParam_(const String& parent_parent_tag,
268  const String& parent_tag,
269  const String& name,
270  const String& type,
271  const String& value,
272  const String& unit_accession = "");
274 
280 
282  void writeHeader_(std::ostream& os,
283  const MapType& exp,
284  std::vector<std::vector< ConstDataProcessingPtr > >& dps,
285  const Internal::MzMLValidator& validator);
286 
287 
289  void writeSpectrum_(std::ostream& os,
290  const SpectrumType& spec,
291  Size spec_idx,
292  const Internal::MzMLValidator& validator,
293  bool renew_native_ids,
294  std::vector<std::vector< ConstDataProcessingPtr > >& dps);
295 
297  void writeChromatogram_(std::ostream& os,
298  const ChromatogramType& chromatogram,
299  Size chrom_idx,
300  const Internal::MzMLValidator& validator);
301 
302  template <typename ContainerT>
303  void writeContainerData_(std::ostream& os, const PeakFileOptions& pf_options_, const ContainerT& container, const String& array_type);
304 
317  template <typename DataType>
318  void writeBinaryDataArray_(std::ostream& os,
319  const PeakFileOptions& options,
320  std::vector<DataType>& data,
321  bool is32bit,
322  String array_type);
323 
338  void writeBinaryFloatDataArray_(std::ostream& os,
339  const PeakFileOptions& options,
341  const Size spec_chrom_idx,
342  const Size array_idx,
343  bool is_spectrum,
344  const Internal::MzMLValidator& validator);
345 
347  void writeUserParam_(std::ostream& os, const MetaInfoInterface& meta, UInt indent, const String& path, const Internal::MzMLValidator& validator, const std::set<String>& exclude = {}) const;
348 
350  void writeSoftware_(std::ostream& os, const String& id, const Software& software, const Internal::MzMLValidator& validator);
351 
353  void writeSourceFile_(std::ostream& os, const String& id, const SourceFile& software, const Internal::MzMLValidator& validator);
354 
356  void writeDataProcessing_(std::ostream& os, const String& id, const std::vector< ConstDataProcessingPtr >& dps, const Internal::MzMLValidator& validator);
357 
359  void writePrecursor_(std::ostream& os, const Precursor& precursor, const Internal::MzMLValidator& validator);
360 
362  void writeProduct_(std::ostream& os, const Product& product, const Internal::MzMLValidator& validator);
363 
365  String writeCV_(const ControlledVocabulary::CVTerm& c, const DataValue& metaValue) const;
366 
368  bool validateCV_(const ControlledVocabulary::CVTerm& c, const String& path, const Internal::MzMLValidator& validator) const;
369 
371  ControlledVocabulary::CVTerm getChildWithName_(const String& parent_accession, const String& name) const;
372 
374 
375  // MEMBERS
376 
378  MapType* exp_{ nullptr };
379 
381  const MapType* cexp_{ nullptr };
382 
385 
393  std::vector<BinaryData> bin_data_;
397  bool in_spectrum_list_{ false };
399  bool skip_spectrum_{ false };
401  bool skip_chromatogram_{ false };
403  bool rt_set_{ false };
407  std::map<String, std::vector<SemanticValidator::CVTerm> > ref_param_;
409  std::map<String, SourceFile> source_files_;
411  std::map<String, Sample> samples_;
413  std::map<String, Software> software_;
415  std::map<String, Instrument> instruments_;
417  mutable std::map<std::pair<String, String>, bool> cached_terms_;
419  std::map<String, std::vector< DataProcessingPtr > > processing_;
423  UInt selected_ion_count_{ 0 };
424 
433  {
434  std::vector<BinaryData> data;
437  };
438 
440  std::vector<SpectrumData> spectrum_data_;
441 
450  {
451  std::vector<BinaryData> data;
454  };
455 
457  std::vector<ChromatogramData> chromatogram_data_;
458 
460 
468  std::vector<std::pair<std::string, Int64> > spectra_offsets_;
469  std::vector<std::pair<std::string, Int64> > chromatograms_offsets_;
471 
474 
476  Interfaces::IMSDataConsumer* consumer_{ nullptr };
477 
479  UInt scan_count_{ 0 };
480  UInt chromatogram_count_{ 0 };
481  Int scan_count_total_{ -1 };
482  Int chrom_count_total_{ -1 };
484 
488 
489  };
490 
491  //--------------------------------------------------------------------------------
492 
493  } // namespace Internal
494 } // namespace OpenMS
495 
Representation of controlled vocabulary mapping rules (for PSI formats)
Definition: CVMappings.h:31
A 1-dimensional raw data point or peak for chromatograms.
Definition: ChromatogramPeak.h:28
Representation of a controlled vocabulary.
Definition: ControlledVocabulary.h:29
Float data array class.
Definition: DataArrays.h:22
Class to hold strings, numeric values, lists of strings and lists of numeric values.
Definition: DataValue.h:33
The interface of a consumer of spectra and chromatograms.
Definition: IMSDataConsumer.h:44
Handler for mzML file format.
Definition: MzMLHandler.h:94
ControlledVocabulary::CVTerm getChildWithName_(const String &parent_accession, const String &name) const
Helper method to look up a child CV term of parent_accession with the name name. If no such term is f...
MzMLHandler(const String &filename, const String &version, const ProgressLogger &logger)
delegated constructor for the two public versions
Size default_array_length_
The default number of peaks in the current spectrum.
Definition: MzMLHandler.h:395
std::map< String, std::vector< DataProcessingPtr > > processing_
The data processing list: id => Instrument.
Definition: MzMLHandler.h:419
ChromatogramType chromatogram_
The current chromatogram.
Definition: MzMLHandler.h:391
MzMLHandler(const MapType &exp, const String &filename, const String &version, const ProgressLogger &logger)
Constructor for a write-only handler.
void writeProduct_(std::ostream &os, const Product &product, const Internal::MzMLValidator &validator)
Helper method that write precursor information from spectra and chromatograms.
ChromatogramType chromatogram
Definition: MzMLHandler.h:453
MSChromatogram ChromatogramType
Spectrum type.
Definition: MzMLHandler.h:184
LOADDETAIL getLoadDetail() const override
handler which support partial loading, implement this method
void writeBinaryDataArray_(std::ostream &os, const PeakFileOptions &options, std::vector< DataType > &data, bool is32bit, String array_type)
Write a single <binaryDataArray> element to the output.
std::vector< ChromatogramData > chromatogram_data_
Vector of chromatogram data stored for later parallel processing.
Definition: MzMLHandler.h:457
const ControlledVocabulary & cv_
Controlled vocabulary (psi-ms from OpenMS/share/OpenMS/CV/psi-ms.obo)
Definition: MzMLHandler.h:486
~MzMLHandler() override
Destructor.
void writeTo(std::ostream &os) override
Docu in base class XMLHandler::writeTo.
MzMLHandler(MapType &exp, const String &filename, const String &version, const ProgressLogger &logger)
Constructor for a read-only handler.
std::vector< std::pair< std::string, Int64 > > chromatograms_offsets_
Stores binary offsets for each <chromatogram> tag.
Definition: MzMLHandler.h:469
void writeHeader_(std::ostream &os, const MapType &exp, std::vector< std::vector< ConstDataProcessingPtr > > &dps, const Internal::MzMLValidator &validator)
Write out XML header including (everything up to spectrumList / chromatogramList.
void populateChromatogramsWithData_()
Populate all chromatograms on the stack with data from input.
std::vector< BinaryData > data
Definition: MzMLHandler.h:434
std::vector< std::pair< std::string, Int64 > > spectra_offsets_
Stores binary offsets for each <spectrum> tag.
Definition: MzMLHandler.h:468
CVMappings mapping_
Definition: MzMLHandler.h:487
std::map< String, Instrument > instruments_
The data processing list: id => Instrument.
Definition: MzMLHandler.h:415
std::map< String, Software > software_
The software list: id => Software.
Definition: MzMLHandler.h:413
const ProgressLogger & logger_
Progress logger.
Definition: MzMLHandler.h:473
SpectrumType spec_
The current spectrum.
Definition: MzMLHandler.h:389
String current_id_
Id of the current list. Used for referencing param group, source file, sample, software,...
Definition: MzMLHandler.h:405
void setLoadDetail(const LOADDETAIL d) override
handler which support partial loading, implement this method
MSSpectrum SpectrumType
Spectrum type.
Definition: MzMLHandler.h:182
void setMSDataConsumer(Interfaces::IMSDataConsumer *consumer)
Set the IMSDataConsumer consumer which will consume the read data.
PeakFileOptions options_
Options that can be set for loading/storing.
Definition: MzMLHandler.h:384
void getCounts(Size &spectra_counts, Size &chromatogram_counts)
Get the spectra and chromatogram counts of a file.
Size default_array_length
Definition: MzMLHandler.h:435
void handleUserParam_(const String &parent_parent_tag, const String &parent_tag, const String &name, const String &type, const String &value, const String &unit_accession="")
Handles user terms.
MapType::PeakType PeakType
Peak type.
Definition: MzMLHandler.h:178
std::map< std::pair< String, String >, bool > cached_terms_
CV terms-path-combinations that have been checked in validateCV_()
Definition: MzMLHandler.h:417
std::vector< SpectrumData > spectrum_data_
Vector of spectrum data stored for later parallel processing.
Definition: MzMLHandler.h:440
void populateSpectraWithData_()
Populate all spectra on the stack with data from input.
MzMLHandlerHelper::BinaryData BinaryData
Definition: MzMLHandler.h:186
void populateSpectraWithData_(std::vector< MzMLHandlerHelper::BinaryData > &input_data, Size &length, const PeakFileOptions &peak_file_options, SpectrumType &spectrum)
Fill a single spectrum with data from input.
PeakFileOptions & getOptions()
Get the peak file options.
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)
Write a single <binaryDataArray> element for a float data array to the output.
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)
Write out a single spectrum.
void writeSoftware_(std::ostream &os, const String &id, const Software &software, const Internal::MzMLValidator &validator)
Helper method that writes a software.
void fillChromatogramData_()
Fills the current chromatogram with data points and meta data.
void startElement(const XMLCh *const, const XMLCh *const, const XMLCh *const qname, const xercesc::Attributes &attributes) override
Docu in base class XMLHandler::startElelement.
void writeChromatogram_(std::ostream &os, const ChromatogramType &chromatogram, Size chrom_idx, const Internal::MzMLValidator &validator)
Write out a single chromatogram.
void handleCVParam_(const String &parent_parent_tag, const String &parent_tag, const String &accession, const String &name, const String &value, const String &unit_accession="")
Handles CV terms.
void writeUserParam_(std::ostream &os, const MetaInfoInterface &meta, UInt indent, const String &path, const Internal::MzMLValidator &validator, const std::set< String > &exclude={}) const
Writes user terms.
std::vector< BinaryData > bin_data_
The spectrum data (or chromatogram data)
Definition: MzMLHandler.h:393
void writeContainerData_(std::ostream &os, const PeakFileOptions &pf_options_, const ContainerT &container, const String &array_type)
String writeCV_(const ControlledVocabulary::CVTerm &c, const DataValue &metaValue) const
Helper method to write an CV based on a meta value.
bool validateCV_(const ControlledVocabulary::CVTerm &c, const String &path, const Internal::MzMLValidator &validator) const
Helper method to validate if the given CV is allowed in the current location (path)
String default_processing_
id of the default data processing (used when no processing is defined)
Definition: MzMLHandler.h:421
void writeSourceFile_(std::ostream &os, const String &id, const SourceFile &software, const Internal::MzMLValidator &validator)
Helper method that writes a source file.
void characters(const XMLCh *const chars, const XMLSize_t length) override
Docu in base class XMLHandler::characters.
void endElement(const XMLCh *const, const XMLCh *const, const XMLCh *const qname) override
Docu in base class XMLHandler::endElement.
std::map< String, Sample > samples_
The sample list: id => Sample.
Definition: MzMLHandler.h:411
void setOptions(const PeakFileOptions &opt)
Set the peak file options.
std::map< String, std::vector< SemanticValidator::CVTerm > > ref_param_
The referencing param groups: id => array (accession, value)
Definition: MzMLHandler.h:407
std::map< String, SourceFile > source_files_
The source files: id => SourceFile.
Definition: MzMLHandler.h:409
void addSpectrumMetaData_(const std::vector< MzMLHandlerHelper::BinaryData > &input_data, const Size n, SpectrumType &spectrum) const
Add extra data arrays to a spectrum.
void populateChromatogramsWithData_(std::vector< MzMLHandlerHelper::BinaryData > &input_data, Size &length, const PeakFileOptions &peak_file_options, ChromatogramType &chromatogram)
Fill a single chromatogram with data from input.
MapType::ChromatogramPeakType ChromatogramPeakType
Chromatogram peak type.
Definition: MzMLHandler.h:180
void writePrecursor_(std::ostream &os, const Precursor &precursor, const Internal::MzMLValidator &validator)
Helper method that write precursor information from spectra and chromatograms.
SpectrumType spectrum
Definition: MzMLHandler.h:436
void writeDataProcessing_(std::ostream &os, const String &id, const std::vector< ConstDataProcessingPtr > &dps, const Internal::MzMLValidator &validator)
Helper method that writes a data processing list.
Data necessary to generate a single chromatogram.
Definition: MzMLHandler.h:450
Data necessary to generate a single spectrum.
Definition: MzMLHandler.h:433
Semantically validates MzXML files.
Definition: MzMLValidator.h:25
Base class for XML handlers.
Definition: XMLHandler.h:300
LOADDETAIL
Definition: XMLHandler.h:323
The representation of a chromatogram.
Definition: MSChromatogram.h:31
In-Memory representation of a mass spectrometry run.
Definition: MSExperiment.h:46
The representation of a 1D spectrum.
Definition: MSSpectrum.h:44
Interface for classes that can store arbitrary meta information (Type-Name-Value tuples).
Definition: MetaInfoInterface.h:35
A 1-dimensional raw data point or peak.
Definition: Peak1D.h:28
Options for loading files containing peak data.
Definition: PeakFileOptions.h:22
Precursor meta information.
Definition: Precursor.h:35
Product meta information.
Definition: Product.h:24
Base class for all classes that want to report their progress.
Definition: ProgressLogger.h:27
Description of the software used for processing.
Definition: Software.h:24
Description of a file location, used to store the origin of (meta) data.
Definition: SourceFile.h:22
A more convenient string class.
Definition: String.h:34
int Int
Signed integer type.
Definition: Types.h:76
unsigned int UInt
Unsigned integer type.
Definition: Types.h:68
size_t Size
Size type e.g. used as variable which can hold result of size()
Definition: Types.h:101
const double c
Definition: Constants.h:188
MSChromatogram ChromatogramType
Definition: MzDataHandler.h:35
MSSpectrum SpectrumType
Definition: MzDataHandler.h:34
PeakMap MapType
XML handler for MzDataFile.
Definition: MzDataHandler.h:33
Main OpenMS namespace.
Definition: FeatureDeconvolution.h:22
Representation of a CV term.
Definition: ControlledVocabulary.h:35
Representation for binary data in mzML.
Definition: MzMLHandlerHelper.h:44