AdductInfo Class Reference

Mass-arithmetic helper for ionizing adducts (e.g. [M+H]+, [2M-H]-, [M+2K-H]+). More...

#include <OpenMS/CHEMISTRY/AdductInfo.h>

Collaboration diagram for AdductInfo:

Public Member Functions
	AdductInfo (const std::string &name, const EmpiricalFormula &adduct, int charge, UInt mol_multiplier=1)
	Construct an AdductInfo from already-parsed parts.
double	getNeutralMass (double observed_mz) const
	Compute the neutral monomer mass M from an observed m/z.
double	getMZ (double neutral_mass) const
	Compute the observed m/z of [nM+Adduct]^(charge) from a candidate neutral monomer mass.
double	getMassShift (bool use_avg_mass=false) const
	Net mass shift introduced by this adduct relative to the neutral monomer.
bool	isCompatible (const EmpiricalFormula &db_entry) const
	Check whether this adduct is physically compatible with a candidate compound.
int	getCharge () const
	Signed ion charge.
const std::string &	getName () const
	Original textual identifier supplied to the constructor (or the parsed source string, when constructed via parseAdductString).
const EmpiricalFormula &	getEmpiricalFormula () const
	Neutral EmpiricalFormula of the adduct part alone (no M, no n-mer multiplier).
UInt	getMolMultiplier () const
	N-mer multiplier (1 for monomers, 2 for dimers, ...).
bool	operator== (const AdductInfo &other) const
	Equality on all four fields (name, formula, charge, n-mer multiplier). Two AdductInfos parsed from the same canonical string compare equal; two AdductInfos describing the same physical adduct but with different names do not.

Static Public Member Functions
static AdductInfo	parseAdductString (const std::string &adduct)
	Parse an adduct string into an AdductInfo.

Private Attributes
std::string	name_
	original adduct string, kept for diagnostics
EmpiricalFormula	ef_
	neutral formula of the adduct part (no M, no n-mer multiplier)
double	mass_
	cached monoisotopic mass of ef_ (avoids recomputation)
int	charge_
	signed ion charge; non-zero (positive = cation, negative = anion)
UInt	mol_multiplier_
	n-mer multiplier (1 = monomer, 2 = dimer, ...)

Detailed Description

Mass-arithmetic helper for ionizing adducts (e.g. [M+H]+, [2M-H]-, [M+2K-H]+).

An AdductInfo describes how a neutral compound M is observed as an ion in a mass spectrum: which atoms are added or lost, how many copies of M are clustered (n-mer multiplier), and what net charge state the resulting ion carries. The class provides:

• parsing of the textual adduct notation used throughout OpenMS (see Adduct string grammar below),
• forward conversion M (neutral mass) → observed m/z (getMZ), and the inverse m/z → M (getNeutralMass),
• the bare mass shift contributed by the adduct alone (getMassShift, useful for charge/adduct grouping in feature deconvolution),
• compatibility checks against a candidate database compound (isCompatible).

All conversions correctly account for electron mass: a positive charge means the ion is missing |charge| electrons relative to the neutral form, a negative charge means it carries |charge| extra electrons. The EmpiricalFormula stored internally is always the neutral atomic composition of the adduct part — the charge is tracked separately.

Adduct string grammar

Adduct strings are parsed by parseAdductString and follow the form

  [<n>]M[<sign><k><Formula>...]; <charge_magnitude><sign>

where

• [<n>]M is the molecular ion ("M" optionally prefixed by a small integer multiplier for n-mers, e.g. 2M for dimers),
• each <sign><k><Formula> term adds (+) or subtracts (-) a stoichiometric amount of a neutral fragment, with optional integer coefficient <k> (default 1),
• the trailing ;<n><sign> gives the absolute charge value followed by a + or - sign for the polarity.

Examples (all valid):

  M+H;1+              ; [M+H]+
  M-H;1-              ; [M-H]-
  M+Na;1+             ; sodium adduct
  M+2K-H;1+           ; potassium adduct with proton loss
  2M+H;1+             ; protonated dimer
  2M+CH3CN+Na;1+      ; sodiated acetonitrile dimer adduct
  M;1+                ; bare positive molecular ion (rare)

Whitespace is allowed and stripped during parsing. Mixed double signs such as ++ or +- inside the formula part are rejected. The semicolon between formula and charge is mandatory.

Invariants

• charge is non-zero (a charge of 0 throws on construction).
• mol_multiplier is at least 1.
• The stored EmpiricalFormula has getCharge() == 0; charge is held separately because EmpiricalFormula's own (de)protonation accounting is unsuitable for non-protic adducts like sodium or potassium.

Example

AdductInfo a = AdductInfo::parseAdductString("M+H;1+");
double mz = a.getMZ(180.0634);   // glucose [M+H]+: ~181.0707
double m  = a.getNeutralMass(mz); // round-trips to ~180.0634
 
AdductInfo dimer = AdductInfo::parseAdductString("2M+Na;1+");
double dimer_mz  = dimer.getMZ(180.0634); // sodiated glucose dimer

Constructor & Destructor Documentation

AdductInfo()

AdductInfo	(	const std::string &	name,
		const EmpiricalFormula &	adduct,
		int	charge,
		UInt	mol_multiplier = 1
	)

Construct an AdductInfo from already-parsed parts.

Use parseAdductString if you have the textual notation; this constructor is for callers that already have the components on hand (e.g. when building an adduct programmatically or restoring from a database).

Parameters

[in]	name	Textual identifier (typically the original adduct string, used for diagnostics).
[in]	adduct	Neutral EmpiricalFormula of the adduct part alone (e.g. "H" for [M+H]+, or the empty formula for the bare [M]+). Must have getCharge() == 0; the charge of the ion is given separately via charge.
[in]	charge	Signed ion charge. Must be non-zero; positive for cations, negative for anions.
[in]	mol_multiplier	N-mer multiplier (1 = monomer, 2 = dimer, ...). Must be at least 1.

Exceptions

Exception::InvalidParameter

if charge is 0, mol_multiplier is 0, or adduct already carries a non-zero charge.

Member Function Documentation

getCharge()

int getCharge

(

)

const

Signed ion charge.

Returns

Non-zero integer; positive for cations, negative for anions.

Referenced by AdductCompare::operator()().

getEmpiricalFormula()

const EmpiricalFormula & getEmpiricalFormula

(

)

const

Neutral EmpiricalFormula of the adduct part alone (no M, no n-mer multiplier).

Useful when comparing against per-feature adduct annotations. Charge is not encoded in the returned formula (it always has getCharge() == 0); use getCharge for the ion's charge state.

Returns

Const reference to the stored EmpiricalFormula.

Referenced by AdductCompare::operator()().

getMassShift()

double getMassShift

(

bool

use_avg_mass = false

)

const

Net mass shift introduced by this adduct relative to the neutral monomer.

Returns the mass difference between an observed ion [nM+Adduct] and n*M when expressed in proton-compensated form: a singly charged proton-adduct [M+H]+ yields a mass shift of zero (the "added" proton and the missing electron net out to one proton mass compensated by adding a hydrogen). Other adducts give a non-trivial shift; for example [M+Na]+ shifts by mass(Na) − mass(H).

Primarily used by feature/charge deconvolution algorithms that group features by their mass differences.

Parameters

[in]

use_avg_mass

If true, use average atomic weights rather than monoisotopic ones. Useful when comparing against centroided low-resolution data.

Returns

Mass shift in Dalton.

Referenced by NucleicAcidSearchEngine::main_().

getMolMultiplier()

UInt getMolMultiplier

(

)

const

N-mer multiplier (1 for monomers, 2 for dimers, ...).

getMZ()

double getMZ

(

double

neutral_mass

)

const

Compute the observed m/z of [nM+Adduct]^(charge) from a candidate neutral monomer mass.

Forward direction; inverse of getNeutralMass. Useful when scoring a database candidate against an observed peak.

Parameters

[in]

neutral_mass

Neutral mass of one monomer M in Dalton.

Returns

Predicted m/z of the adduct ion.

getName()

const std::string & getName

(

)

const

Original textual identifier supplied to the constructor (or the parsed source string, when constructed via parseAdductString).

Returns

Const reference to the stored name; mainly for diagnostics.

getNeutralMass()

double getNeutralMass

(

double

observed_mz

)

const

Compute the neutral monomer mass M from an observed m/z.

Inverse of getMZ. Given an observed m/z assumed to come from this adduct, returns the neutral mass of one molecule M (i.e. with the n-mer collapsed and the adduct composition removed). The computation accounts for the electron mass that distinguishes a neutral atom from its ionized form.

Parameters

[in]

observed_mz

Observed m/z (must be > 0).

Returns

Neutral monomer mass of M in Dalton.

isCompatible()

bool isCompatible

(

const EmpiricalFormula &

db_entry

)

const

Check whether this adduct is physically compatible with a candidate compound.

An adduct that removes atoms from the molecule (e.g. -H in [M-H]-) can only be observed if the candidate actually contains those atoms. This method returns true when every element subtracted by the adduct is present in sufficient quantity in db_entry.

Plus-only adducts (no atoms subtracted) are trivially compatible with any compound and always return true.

Parameters

[in]

db_entry

EmpiricalFormula of the candidate compound to test against.

Returns

True iff db_entry could plausibly produce this adduct.

operator==()

bool operator==

(

const AdductInfo &

other

)

const

Equality on all four fields (name, formula, charge, n-mer multiplier). Two AdductInfos parsed from the same canonical string compare equal; two AdductInfos describing the same physical adduct but with different names do not.

parseAdductString()

static AdductInfo parseAdductString ( const std::string &  adduct )

static

Parse an adduct string into an AdductInfo.

The accepted notation is described in Adduct string grammar. The original string (after whitespace stripping) is stored as the AdductInfo's name and retrievable via getName.

Parameters

[in]

adduct

Adduct string, e.g. "M+H;1+" or "2M+CH3CN+Na;1+".

Returns

Parsed AdductInfo.

Exceptions

Exception::InvalidValue	if the string is malformed (missing semicolon, missing charge sign, invalid operators, missing M, unexpected character).
Exception::ConversionError	if a numeric component (charge, stoichiometric coefficient, n-mer multiplier) cannot be parsed as an integer.
Exception::ParseError	if an adduct fragment formula cannot be parsed as an EmpiricalFormula.
Exception::InvalidParameter	if the parsed adduct violates the constructor invariants (e.g. zero charge or a zero n-mer multiplier).

Member Data Documentation

charge_

int charge_

private

signed ion charge; non-zero (positive = cation, negative = anion)

ef_

EmpiricalFormula ef_

private

neutral formula of the adduct part (no M, no n-mer multiplier)

mass_

double mass_

private

cached monoisotopic mass of ef_ (avoids recomputation)

mol_multiplier_

UInt mol_multiplier_

private

n-mer multiplier (1 = monomer, 2 = dimer, ...)

name_

std::string name_

private

original adduct string, kept for diagnostics