One elementary adduct contribution to a feature's ionization state. More...

#include <OpenMS/DATASTRUCTURES/Adduct.h>

Collaboration diagram for Adduct:

Public Types
typedef std::vector< Adduct >	AdductsType
	Convenience typedef for a list of Adducts (used by feature deconvolution).

Public Member Functions
	Adduct ()
	Default constructor. All numeric fields zero-initialised; formula and label empty. Use this only as a placeholder; populate fields via setters before use.

	Adduct (Int charge)
	Construct with only the per-entity charge set.

	Adduct (Int charge, Int amount, double singleMass, const std::string &formula, double log_prob, double rt_shift, const std::string &label="")
	Construct with all fields populated.

Adduct	operator* (const Int m) const
	Multiply the stoichiometric `amount` by an integer factor.

Adduct	operator+ (const Adduct &rhs)
	Sum two Adducts that describe the same chemical entity.

void	operator+= (const Adduct &rhs)
	In-place version of `operator+`. Same precondition (matching formulas).

const Int &	getCharge () const
	Per-entity charge; `+1` for typical cation adducts (Na+, H+).

void	setCharge (const Int &charge)
	Set the per-entity charge.

const Int &	getAmount () const
	Stoichiometric count of this adduct in the ion.

void	setAmount (const Int &amount)
	Set the stoichiometric count. Logs a warning on negative values but accepts them.

const double &	getSingleMass () const
	Monoisotopic mass of one entity (Dalton).

void	setSingleMass (const double &singleMass)
	Set the monoisotopic mass of one entity.

const double &	getLogProb () const
	Log-prior on observing this adduct.

void	setLogProb (const double &log_prob)
	Set the log-prior on observing this adduct.

const std::string &	getFormula () const
	Chemical formula of one entity (canonicalised by EmpiricalFormula, e.g. `"H2O"` — not `"OH2"`).

void	setFormula (const std::string &formula)
	Set the chemical formula of one entity. The input is parsed as an EmpiricalFormula and re-emitted in canonical order; warnings are logged for empty, explicitly charged, or ambiguous-single- element formulas.

const double &	getRTShift () const
	RT shift induced by one entity (seconds). Non-zero only for adducts attached prior to ESI (e.g. covalent labels).

const std::string &	getLabel () const
	Free-form label (typically a heavy-isotope tag).

std::string	toAdductString (const std::string &ion_string, const Int &charge)
	Render `ion_string` + `charge` as a canonical adduct string, assuming a monomer (n=1).

Static Public Member Functions
static std::string	toAdductString (const std::string &ion_string, const Int &charge, Int mol_multiplier)
	Render `ion_string` + `charge` as a canonical adduct string, with an explicit n-mer multiplier.

Private Member Functions
std::string	checkFormula_ (const std::string &formula)

Private Attributes
Int	charge_
	per-entity charge (e.g. +1 for Na+)

Int	amount_
	stoichiometric count of this entity

double	singleMass_
	monoisotopic mass of one entity (Da)

double	log_prob_
	log-prior on observing this adduct

std::string	formula_
	chemical formula of one entity (EmpiricalFormula-parseable, canonicalised)

double	rt_shift_
	RT shift induced by one entity (s); non-zero only for pre-ESI labels.

std::string	label_
	free-form tag (e.g. heavy-isotope label name)

Friends
std::ostream &	operator<< (std::ostream &os, const Adduct &a)

bool	operator== (const Adduct &a, const Adduct &b)
	Equality on `charge`, `amount`, `singleMass`, `log_prob`, and `formula`. Deliberately ignores `rt_shift` and `label` so that adducts differing only in labeling tag still compare equal.

Detailed Description

One elementary adduct contribution to a feature's ionization state.

An Adduct describes a single chemical "piece" that can be added to (or removed from) a neutral molecule during ionization — for example one sodium cation, one ammonia adduct, or one lost proton. It is the building-block used by feature/charge deconvolution algorithms (FeatureDeconvolution, MetaboliteFeatureDeconvolution, Compomer, QTClusterFinder); several Adducts combine to describe the complete ion observed for one feature.

Fields

formula : chemical formula of one entity, e.g. "Na", "H", "NH3", "C2H3N". Must parse as a neutral EmpiricalFormula; explicit charge in the formula triggers a warning at construction.
amount : how many copies of formula contribute (stoichiometric count; e.g. 2 in "M+2K-H"). Negative amounts are accepted but emit a warning.
singleMass : monoisotopic mass of one entity (one copy of formula). The full mass contribution of this Adduct is amount * singleMass.
charge : per-entity charge of the adduct (e.g. +1 for Na+, -1 for a proton loss). The ion's total charge is amount * charge.
log_prob : log-prior on observing this adduct, used by deconvolution algorithms when scoring competing hypotheses.
rt_shift : optional retention-time shift induced by one entity (non-zero for adducts attached prior to ESI, e.g. covalent labels; zero for in-source adducts like Na or K that do not affect chromatographic behavior).
label : free-form label, typically used to mark heavy isotopic labels.

Relationship to AdductInfo

AdductInfo (in CHEMISTRY/) represents an entire adduct specification — the parsed form of a string such as "[M+2K-H]+" with the molecular entity M, an n-mer multiplier, and a net charge. Adduct represents only a single piece of that specification (e.g. just the "2K" part or the "-H" part). AdductInfo is used for matching observed m/z against database compounds; Adduct is used to build up hypotheses about which combinations of pieces might explain a feature.

Arithmetic

operator*(Int) scales the amount: a*3 returns a copy of a with amount tripled. operator+ and operator+= merge two Adducts that share the same formula, summing their amounts (used when accumulating identical pieces of an ion's adduct composition). Mixing adducts with different formulae throws.

Equality and hashing

Equality compares charge, amount, singleMass, log_prob, and formula. rt_shift and label are deliberately excluded so that two Adducts describing the same physical entity but tagged with different labels still compare equal — this matches the std::hash specialization for Adduct (see bottom of this header).

Member Typedef Documentation

◆ AdductsType

typedef std::vector<Adduct> AdductsType

Convenience typedef for a list of Adducts (used by feature deconvolution).

Constructor & Destructor Documentation

◆ Adduct() [1/3]

Adduct ( )

Default constructor. All numeric fields zero-initialised; formula and label empty. Use this only as a placeholder; populate fields via setters before use.

◆ Adduct() [2/3]

Adduct ( Int charge )

Construct with only the per-entity charge set.

All other fields are zero/empty. amount, singleMass, log_prob, and formula can be populated via setters; rt_shift and label can only be set via the full constructor.

Parameters

[in] charge Per-entity charge (e.g. +1 for Na+).

◆ Adduct() [3/3]

Adduct	(	Int	charge,
		Int	amount,
		double	singleMass,
		const std::string &	formula,
		double	log_prob,
		double	rt_shift,
		const std::string &	label = `""`
	)

Construct with all fields populated.

Parameters

[in]	charge	Per-entity charge (e.g. `+1` for Na+).
[in]	amount	Stoichiometric count of this adduct in the ion (e.g. `2` for `"2K"` in `"M+2K-H"`). A negative value is accepted but emits a warning.
[in]	singleMass	Monoisotopic mass of one entity in Dalton.
[in]	formula	Chemical formula of one entity (e.g. `"Na"`, `"NH3"`). Must parse as a neutral EmpiricalFormula; warnings are logged for empty, charged, or ambiguous single-element formulas (e.g. `"C2"` with no other element).
[in]	log_prob	Log-prior on observing this adduct (default 0).
[in]	rt_shift	RT shift contributed by one entity in seconds (default 0; non-zero for pre-ESI labels).
[in]	label	Free-form label, typically heavy-isotope tag.

Member Function Documentation

◆ checkFormula_()

std::string checkFormula_ ( const std::string & formula )

private

Validate and canonicalise formula. Warns on empty, charged, or ambiguous single-element inputs. Returns the canonical form.

◆ getAmount()

const Int & getAmount ( ) const

Stoichiometric count of this adduct in the ion.

◆ getCharge()

const Int & getCharge ( ) const

Per-entity charge; +1 for typical cation adducts (Na+, H+).

◆ getFormula()

const std::string & getFormula ( ) const

Chemical formula of one entity (canonicalised by EmpiricalFormula, e.g. "H2O" — not "OH2").

◆ getLabel()

const std::string & getLabel ( ) const

Free-form label (typically a heavy-isotope tag).

◆ getLogProb()

const double & getLogProb ( ) const

Log-prior on observing this adduct.

◆ getRTShift()

const double & getRTShift ( ) const

RT shift induced by one entity (seconds). Non-zero only for adducts attached prior to ESI (e.g. covalent labels).

◆ getSingleMass()

const double & getSingleMass ( ) const

Monoisotopic mass of one entity (Dalton).

◆ operator*()

Adduct operator* ( const Int m ) const

Multiply the stoichiometric amount by an integer factor.

Returns a copy with amount scaled; other fields unchanged. Used when expanding m*Adduct hypotheses (e.g. promoting one Na to 3 Na).

Parameters

[in] m Integer multiplier.

Returns: A new Adduct with the scaled amount.

◆ operator+()

Adduct operator+ ( const Adduct & rhs )

Sum two Adducts that describe the same chemical entity.

Both operands must share the same formula; only the amount fields are summed. Used when accumulating identical pieces of an ion's adduct composition.

Parameters

[in] rhs The other Adduct (must have identical formula).

Returns: A new Adduct with the summed amount.

Exceptions

const char* C-string literal when rhs has a different formula than *this.

◆ operator+=()

void operator+= ( const Adduct & rhs )

In-place version of operator+. Same precondition (matching formulas).

Parameters

[in] rhs The other Adduct (must have identical formula).

Exceptions

const char* C-string literal when rhs has a different formula than *this.

◆ setAmount()

void setAmount ( const Int & amount )

Set the stoichiometric count. Logs a warning on negative values but accepts them.

Parameters

[in] amount Stoichiometric count (typically >= 0).

◆ setCharge()

void setCharge ( const Int & charge )

Set the per-entity charge.

Parameters

[in] charge Per-entity charge.

◆ setFormula()

void setFormula ( const std::string & formula )

Set the chemical formula of one entity. The input is parsed as an EmpiricalFormula and re-emitted in canonical order; warnings are logged for empty, explicitly charged, or ambiguous-single- element formulas.

Parameters

[in] formula EmpiricalFormula-parseable string (e.g. "Na", "NH3", "C2H3N").

◆ setLogProb()

void setLogProb ( const double & log_prob )

Set the log-prior on observing this adduct.

Parameters

[in] log_prob Log-prior (negative for unlikely adducts; 0 for no prior preference).

◆ setSingleMass()

void setSingleMass ( const double & singleMass )

Set the monoisotopic mass of one entity.

Parameters

[in] singleMass Monoisotopic mass of one entity in Dalton.

◆ toAdductString() [1/2]

std::string toAdductString	(	const std::string &	ion_string,
		const Int &	charge
	)

Render ion_string + charge as a canonical adduct string, assuming a monomer (n=1).

Convenience overload that calls the three-argument version with mol_multiplier = 1.

Parameters

[in]	ion_string	Element/formula portion of the adduct, EmpiricalFormula-parseable (e.g. `"Na1"`, `"NH3"`).
[in]	charge	Signed net charge of the resulting ion.

Returns: Adduct string in the form "[M+Na]+", "[M-H]-", etc.

◆ toAdductString() [2/2]

static std::string toAdductString	(	const std::string &	ion_string,
		const Int &	charge,
		Int	mol_multiplier
	)

static

Render ion_string + charge as a canonical adduct string, with an explicit n-mer multiplier.

Element/coefficient terms are sorted alphabetically by element symbol so equivalent formulas always produce identical strings.

Examples:

  ("Na1", +1, 1) -> "[M+Na]+"
  ("Na1", +1, 2) -> "[2M+Na]+"
  ("H1",  -1, 1) -> "[M-H]-"
  ("NH3", +1, 1) -> "[M+3H+N]+"   (canonical sort of NH3)

Parameters

[in]	ion_string	EmpiricalFormula-parseable element string.
[in]	charge	Signed net charge of the resulting ion.
[in]	mol_multiplier	N-mer multiplier (`1` = monomer, `2` = dimer, ...).

Returns: Canonical adduct string.

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		const Adduct &	a
	)

friend

Print all fields except rt_shift and label to os (for diagnostics; not a parseable serialization).

◆ operator==

bool operator==	(	const Adduct &	a,
		const Adduct &	b
	)

friend

Equality on charge, amount, singleMass, log_prob, and formula. Deliberately ignores rt_shift and label so that adducts differing only in labeling tag still compare equal.

Member Data Documentation

◆ amount_

Int amount_

private

stoichiometric count of this entity

◆ charge_

Int charge_

private

per-entity charge (e.g. +1 for Na+)

◆ formula_

std::string formula_

private

chemical formula of one entity (EmpiricalFormula-parseable, canonicalised)

◆ label_

std::string label_

private

free-form tag (e.g. heavy-isotope label name)

◆ log_prob_

double log_prob_

private

log-prior on observing this adduct

◆ rt_shift_

double rt_shift_

private

RT shift induced by one entity (s); non-zero only for pre-ESI labels.

◆ singleMass_

double singleMass_

private

monoisotopic mass of one entity (Da)

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Fields

Relationship to AdductInfo

Arithmetic

Equality and hashing

Member Typedef Documentation

◆ AdductsType

Constructor & Destructor Documentation

◆ Adduct() [1/3]

◆ Adduct() [2/3]

◆ Adduct() [3/3]

Member Function Documentation

◆ checkFormula_()

◆ getAmount()

◆ getCharge()

◆ getFormula()

◆ getLabel()

◆ getLogProb()

◆ getRTShift()

◆ getSingleMass()

◆ operator*()

◆ operator+()

◆ operator+=()

◆ setAmount()

◆ setCharge()

◆ setFormula()

◆ setLogProb()

◆ setSingleMass()

◆ toAdductString() [1/2]

◆ toAdductString() [2/2]

Friends And Related Symbol Documentation

◆ operator<<

◆ operator==

Member Data Documentation

◆ amount_

◆ charge_

◆ formula_

◆ label_

◆ log_prob_

◆ rt_shift_

◆ singleMass_