DIAQCMetrics Class Reference

Quality metrics for data-independent acquisition (DIA) runs, per run and per isolation window. More...

#include <DIAuditor/include/DIAQCMetrics.h>

Classes
struct	GroupStatistics
struct	Options
	Options. More...
struct	RunMetrics
	Metrics of one run, including its isolation windows. More...
struct	SpectrumRecord
	The per-spectrum data the metrics need. More...
struct	WindowMetrics
	Metrics of one isolation window. More...

Public Types
enum class	TICSource { AUTO , FILE , COMPUTED }
	Where the total ion current of a spectrum comes from. More...
enum class	PeakCountMode { ALL , NONZERO }
	How peaks of a spectrum are counted. More...
enum class	IonMobilityKey { AUTO , FAIMS , NONE }
	Which ion mobility separates isolation windows with the same m/z range. More...
using	PeakCountSummary = std::array< double, 5 >
	Minimum, first quartile, median, third quartile and maximum of peak counts.
using	TICQuantileRTs = std::array< double, 3 >
	Retention times (seconds) at which 25%, 50% and 75% of the TIC have been accumulated.

Public Member Functions
	DIAQCMetrics ()
	Default options.
	DIAQCMetrics (const Options &options)
void	setExperimentalSettings (const ExperimentalSettings &settings)
	Take instrument, serial number and start time from the run's settings.
void	addSpectrum (const MSSpectrum &spectrum)
	Record one spectrum; spectra can come in any order.
Size	size () const
	Number of spectra recorded so far.
RunMetrics	compute () const
	Compute the metrics of the recorded run.
void	clear ()
	Forget all recorded spectra and settings.

Static Public Member Functions
static void	writeRunTable (const std::vector< RunMetrics > &runs, std::ostream &os)
	Write one row per run (DIAuditor's "byRun" table) as tab-separated values.
static void	writeWindowTable (const std::vector< RunMetrics > &runs, std::ostream &os)
static void	writeMzQC (const std::vector< RunMetrics > &runs, std::ostream &os, const std::string &software_version, const std::string &creation_date)
	Write an mzQC 1.0 file with one runQuality per run.

Private Attributes
Options	options_
std::vector< SpectrumRecord >	records_
std::string	instrument_
std::string	serial_number_
std::string	start_time_stamp_

Detailed Description

Quality metrics for data-independent acquisition (DIA) runs, per run and per isolation window.

Re-implements the metrics of DIAuditor by David L. Tabb (https://github.com/dtabb73/DIAuditor) on top of the OpenMS mzML reader. Only a small record per spectrum is kept, so a run can be streamed:

DIAQCMetrics metrics;
MSDataTransformingConsumer consumer;
consumer.setExperimentalSettingsFunc([&](const ExperimentalSettings& s) { metrics.setExperimentalSettings(s); });
consumer.setSpectraProcessingFunc([&](MSSpectrum& s) { metrics.addSpectrum(s); });
MzMLFile().transform(file, &consumer, true);
DIAQCMetrics::RunMetrics run = metrics.compute();

MS2 spectra are grouped into isolation windows. Two spectra belong to the same window if their first precursor has the same isolation window (target m/z, lower and upper offset) and, depending on Options::ion_mobility, the same FAIMS compensation voltage and ion mobility range. Values are compared with an absolute tolerance of 1e-6 (as in OpenSWATH), since converters may write them with different last digits. Windows are reported in the order in which they are first acquired. MS2 spectra without an isolation window (no precursor, or no isolation window offsets) are not a DIA isolation window: they are collected in RunMetrics::without_isolation_window and left out of the window count and the window statistics. Spectra of MS level 3 and higher are counted, but not assigned to windows. Spectra without a retention time (no scan start time) are counted, but not used for any other metric.

Conventions (retention times are kept in seconds; the table writers convert them to minutes like DIAuditor):

• Medians of times are the usual median (mean of the two middle values for an even count).
• Peak count quartiles, including their median, are observed values taken as in DIAuditor: the values at positions n/4, n/2 and n/4 + n/2 (integer division) of the n sorted counts.
• A "TIC quantile RT" is the retention time of the first spectrum at which the cumulative TIC reaches the quantile.
• Cycle times are medians of the time between consecutive spectra of the same kind (MS1, or one isolation window).
• Undefined values (e.g. a cycle time from a single spectrum, TIC quantiles when the TIC is zero) are NaN.

---

Class Documentation

OpenMS::DIAQCMetrics::Options

struct OpenMS::DIAQCMetrics::Options

Options.

Class Members
IonMobilityKey	ion_mobility = IonMobilityKey::AUTO
PeakCountMode	peak_count = PeakCountMode::ALL
TICSource	tic_source = TICSource::AUTO

OpenMS::DIAQCMetrics::SpectrumRecord

struct OpenMS::DIAQCMetrics::SpectrumRecord

The per-spectrum data the metrics need.

Class Members
double	faims_cv = 0.0
bool	has_isolation_window = false
bool	im_array_without_range = false
double	ion_mobility_lower = 0.0
double	ion_mobility_upper = 0.0
double	lower_offset = 0.0
double	mass_resolving_power = 0.0
UInt	ms_level = 0
Size	peak_count = 0
Size	precursor_count = 0
double	precursor_mz = 0.0
double	rt = 0.0
bool	scan_ion_mobility = false
double	target_mz = 0.0
double	tic = 0.0
double	upper_offset = 0.0

Member Typedef Documentation

PeakCountSummary

using PeakCountSummary = std::array<double, 5>

Minimum, first quartile, median, third quartile and maximum of peak counts.

TICQuantileRTs

using TICQuantileRTs = std::array<double, 3>

Retention times (seconds) at which 25%, 50% and 75% of the TIC have been accumulated.

Member Enumeration Documentation

IonMobilityKey

enum class IonMobilityKey

strong

Which ion mobility separates isolation windows with the same m/z range.

Enumerator
AUTO	FAIMS compensation voltage and the ion mobility range of the window ('ion mobility lower/upper limit' of e.g. diaPASEF frames). An ion mobility of a single spectrum (e.g. one TIMS scan) is a position, not a window.
FAIMS	only the FAIMS compensation voltage (like DIAuditor)
NONE	none: windows are defined by their m/z range alone

PeakCountMode

enum class PeakCountMode

strong

How peaks of a spectrum are counted.

Enumerator
ALL	all data points (like DIAuditor's defaultArrayLength), including zero-intensity points of profile data
NONZERO	only data points with an intensity above zero

TICSource

enum class TICSource

strong

Where the total ion current of a spectrum comes from.

Enumerator
AUTO	the 'total ion current' value of the file (MS:1000285) if present, otherwise the sum of intensities
FILE	only the 'total ion current' value of the file; spectra without it count with a TIC of 0 (like DIAuditor)
COMPUTED	always the sum of intensities of the spectrum

Constructor & Destructor Documentation

DIAQCMetrics() [1/2]

DIAQCMetrics ( )

default

Default options.

DIAQCMetrics() [2/2]

DIAQCMetrics ( const Options &  options )

explicit

Member Function Documentation

addSpectrum()

void addSpectrum

(

const MSSpectrum &

spectrum

)

Record one spectrum; spectra can come in any order.

References DIAQCMetrics::ALL, DIAQCMetrics::AUTO, DIAQCMetrics::COMPUTED, MSSpectrum::containsIMData(), IMTypes::DRIFTTIME_NOT_SET, OpenMS::FAIMS_COMPENSATION_VOLTAGE, DIAQCMetrics::SpectrumRecord::faims_cv, DIAQCMetrics::FILE, MSSpectrum::getDriftTime(), MSSpectrum::getDriftTimeUnit(), Precursor::getIsolationWindowLowerOffset(), Precursor::getIsolationWindowUpperOffset(), MSSpectrum::getMSLevel(), Peak1D::getMZ(), SpectrumSettings::getPrecursors(), MSSpectrum::getRT(), DIAQCMetrics::SpectrumRecord::has_isolation_window, DIAQCMetrics::SpectrumRecord::im_array_without_range, DIAQCMetrics::Options::ion_mobility, DIAQCMetrics::SpectrumRecord::ion_mobility_lower, DIAQCMetrics::SpectrumRecord::ion_mobility_upper, DIAQCMetrics::SpectrumRecord::lower_offset, DIAQCMetrics::SpectrumRecord::mass_resolving_power, DIAQCMetrics::SpectrumRecord::ms_level, OpenMS::NONE, DIAQCMetrics::NONE, DIAQCMetrics::options_, DIAQCMetrics::Options::peak_count, DIAQCMetrics::SpectrumRecord::peak_count, DIAQCMetrics::SpectrumRecord::precursor_count, DIAQCMetrics::SpectrumRecord::precursor_mz, DIAQCMetrics::records_, DIAQCMetrics::SpectrumRecord::rt, DIAQCMetrics::SpectrumRecord::scan_ion_mobility, DIAQCMetrics::SpectrumRecord::target_mz, DIAQCMetrics::SpectrumRecord::tic, DIAQCMetrics::Options::tic_source, and DIAQCMetrics::SpectrumRecord::upper_offset.

clear()

void clear

(

)

Forget all recorded spectra and settings.

References DIAQCMetrics::instrument_, DIAQCMetrics::records_, DIAQCMetrics::serial_number_, and DIAQCMetrics::start_time_stamp_.

compute()

DIAQCMetrics::RunMetrics compute

(

)

const

Compute the metrics of the recorded run.

References DIAQCMetrics::WindowMetrics::cycle_time_median, DIAQCMetrics::GroupStatistics::cycle_time_median, DIAQCMetrics::WindowMetrics::faims_cv, DIAQCMetrics::SpectrumRecord::faims_cv, first, DIAQCMetrics::WindowMetrics::has_isolation_window, DIAQCMetrics::RunMetrics::instrument, DIAQCMetrics::instrument_, DIAQCMetrics::WindowMetrics::ion_mobility_lower, DIAQCMetrics::SpectrumRecord::ion_mobility_lower, DIAQCMetrics::WindowMetrics::ion_mobility_upper, DIAQCMetrics::SpectrumRecord::ion_mobility_upper, DIAQCMetrics::WindowMetrics::lower_mz, DIAQCMetrics::SpectrumRecord::lower_offset, DIAQCMetrics::WindowMetrics::mass_resolving_power, DIAQCMetrics::GroupStatistics::mass_resolving_power, DIAQCMetrics::RunMetrics::ms1_count, DIAQCMetrics::RunMetrics::ms1_cycle_time_median, DIAQCMetrics::RunMetrics::ms1_mass_resolving_power, DIAQCMetrics::RunMetrics::ms1_peak_count, DIAQCMetrics::RunMetrics::ms1_tic_quantile_rt, DIAQCMetrics::RunMetrics::ms1_total_tic, DIAQCMetrics::RunMetrics::ms2_count, DIAQCMetrics::RunMetrics::ms2_im_array_without_range, DIAQCMetrics::RunMetrics::ms2_multiple_precursors, DIAQCMetrics::RunMetrics::ms2_peak_count, DIAQCMetrics::RunMetrics::ms2_scan_ion_mobility, DIAQCMetrics::RunMetrics::ms2_tic_quantile_rt, DIAQCMetrics::RunMetrics::ms2_total_tic, DIAQCMetrics::RunMetrics::msn_count, DIAQCMetrics::WindowMetrics::peak_count, DIAQCMetrics::GroupStatistics::peak_count, DIAQCMetrics::RunMetrics::precursor_mz_max, DIAQCMetrics::RunMetrics::precursor_mz_min, DIAQCMetrics::records_, DIAQCMetrics::SpectrumRecord::rt, DIAQCMetrics::GroupStatistics::rt_differences, DIAQCMetrics::WindowMetrics::rt_max, DIAQCMetrics::RunMetrics::rt_max, DIAQCMetrics::WindowMetrics::rt_min, DIAQCMetrics::RunMetrics::rt_min, DIAQCMetrics::RunMetrics::serial_number, DIAQCMetrics::serial_number_, DIAQCMetrics::RunMetrics::spectra_without_rt, DIAQCMetrics::WindowMetrics::spectrum_count, DIAQCMetrics::RunMetrics::start_time_stamp, DIAQCMetrics::start_time_stamp_, OpenMS::Math::sum(), DIAQCMetrics::WindowMetrics::target_mz, DIAQCMetrics::SpectrumRecord::target_mz, DIAQCMetrics::WindowMetrics::tic_quantile_rt, DIAQCMetrics::GroupStatistics::tic_quantile_rt, DIAQCMetrics::WindowMetrics::total_tic, DIAQCMetrics::GroupStatistics::total_tic, DIAQCMetrics::WindowMetrics::upper_mz, DIAQCMetrics::SpectrumRecord::upper_offset, DIAQCMetrics::WindowMetrics::width_mz, DIAQCMetrics::RunMetrics::window_count, DIAQCMetrics::RunMetrics::window_cycle_time_mean, DIAQCMetrics::RunMetrics::window_cycle_time_median, DIAQCMetrics::RunMetrics::window_half_tic_rt_max, DIAQCMetrics::RunMetrics::window_half_tic_rt_min, DIAQCMetrics::RunMetrics::window_mz_max, DIAQCMetrics::RunMetrics::window_mz_min, DIAQCMetrics::RunMetrics::window_peak_count_median_max, DIAQCMetrics::RunMetrics::window_peak_count_median_min, DIAQCMetrics::RunMetrics::window_spectra_max, DIAQCMetrics::RunMetrics::window_spectra_min, DIAQCMetrics::RunMetrics::window_total_tic_max, DIAQCMetrics::RunMetrics::window_total_tic_min, DIAQCMetrics::RunMetrics::window_width_max, DIAQCMetrics::RunMetrics::window_width_min, DIAQCMetrics::RunMetrics::windows, DIAQCMetrics::RunMetrics::windows_measured_once, and DIAQCMetrics::RunMetrics::without_isolation_window.

setExperimentalSettings()

void setExperimentalSettings

(

const ExperimentalSettings &

settings

)

Take instrument, serial number and start time from the run's settings.

References ExperimentalSettings::getDateTime(), ExperimentalSettings::getInstrument(), MetaInfoInterface::getMetaValue(), Instrument::getName(), DIAQCMetrics::instrument_, DateTime::isNull(), DateTime::isValid(), MetaInfoInterface::metaValueExists(), DIAQCMetrics::serial_number_, DIAQCMetrics::start_time_stamp_, DataValue::toString(), and DateTime::toString().

size()

Size size

(

)

const

Number of spectra recorded so far.

References DIAQCMetrics::records_.

writeMzQC()

void writeMzQC ( const std::vector< RunMetrics > &  runs, std::ostream &  os, const std::string &  software_version, const std::string &  creation_date  )

static

Write an mzQC 1.0 file with one runQuality per run.

Only metrics defined in the PSI-MS vocabulary are written, with the names and units the vocabulary defines. Terms missing from the installed vocabulary are skipped with a warning. Per-window values are not written, as the vocabulary has no term for them; see writeWindowTable(). The DIA isolation window metrics (MS:4000193 to MS:4000199) describe RunMetrics::windows only, and MS:4000069 'm/z acquisition range' is the range of the precursor m/z values (RunMetrics::precursor_mz_min/max), not the m/z range the isolation windows cover.

Parameters

[in]	runs	The runs
[in]	os	Output stream
[in]	software_version	Version string of the software written as analysisSoftware
[in]	creation_date	Creation date as RFC 3339 date-time, with time zone (e.g. "2026-01-02T03:04:05Z")

References File::basename(), ControlledVocabulary::CVTerm::description, ControlledVocabulary::exists(), File::find(), ControlledVocabulary::getPSIMSCV(), ControlledVocabulary::getTerm(), ControlledVocabulary::CVTerm::name, and OPENMS_LOG_WARN.

writeRunTable()

void writeRunTable ( const std::vector< RunMetrics > &  runs, std::ostream &  os  )

static

Write one row per run (DIAuditor's "byRun" table) as tab-separated values.

writeWindowTable()

void writeWindowTable ( const std::vector< RunMetrics > &  runs, std::ostream &  os  )

static

Write one row per isolation window (DIAuditor's "byIsolationWindow" table) as tab-separated values. MS2 spectra without an isolation window (RunMetrics::without_isolation_window) follow as the run's last row, without m/z values.

References DIAQCMetrics::WindowMetrics::cycle_time_median, DIAQCMetrics::WindowMetrics::faims_cv, DIAQCMetrics::WindowMetrics::ion_mobility_lower, DIAQCMetrics::WindowMetrics::ion_mobility_upper, DIAQCMetrics::WindowMetrics::lower_mz, DIAQCMetrics::WindowMetrics::mass_resolving_power, DIAQCMetrics::WindowMetrics::peak_count, DIAQCMetrics::WindowMetrics::rt_max, DIAQCMetrics::WindowMetrics::rt_min, DIAQCMetrics::WindowMetrics::spectrum_count, DIAQCMetrics::WindowMetrics::target_mz, DIAQCMetrics::WindowMetrics::tic_quantile_rt, DIAQCMetrics::WindowMetrics::total_tic, DIAQCMetrics::WindowMetrics::upper_mz, and DIAQCMetrics::WindowMetrics::width_mz.

Member Data Documentation

instrument_

std::string instrument_

private

Referenced by DIAQCMetrics::clear(), DIAQCMetrics::compute(), and DIAQCMetrics::setExperimentalSettings().

options_

Options options_

private

Referenced by DIAQCMetrics::addSpectrum().

records_

std::vector<SpectrumRecord> records_

private

Referenced by DIAQCMetrics::addSpectrum(), DIAQCMetrics::clear(), DIAQCMetrics::compute(), and DIAQCMetrics::size().

serial_number_

std::string serial_number_

private

Referenced by DIAQCMetrics::clear(), DIAQCMetrics::compute(), and DIAQCMetrics::setExperimentalSettings().

start_time_stamp_

std::string start_time_stamp_

private

Referenced by DIAQCMetrics::clear(), DIAQCMetrics::compute(), and DIAQCMetrics::setExperimentalSettings().