FragmentIonLikelihoodModel Class Reference

Per-run likelihood model of fragment ion presence, intensity rank and mass error, learned from confident PSMs. More...

#include <OpenMS/ANALYSIS/ID/FragmentIonLikelihoodModel.h>

Classes
struct	Features
	Features of one PSM. More...
struct	Ion
	One theoretical ion after matching. More...
class	PeakLists
	Compact peak lists of the spectra of one run: per peak only its m/z and its intensity-rank bin. More...

Public Types
enum class	ContextSet { BASIC , RICH }
	Ion contexts and outcomes the model distinguishes. More...

Public Member Functions
	FragmentIonLikelihoodModel (ContextSet context_set=ContextSet::RICH, double pseudo_count=20.0)
	Untrained model.
ContextSet	contextSet () const
	The context set of this model.
Size	contexts () const
	Number of ion contexts.
Size	outcomes () const
	Number of outcomes, absence included.
Size	absentOutcome () const
	Outcome of an unmatched ion.
void	matchIons (const PeakLists &peaks, Size index, const MSSpectrum &theoretical, const AASequence &peptide, int precursor_charge, double tolerance, bool ppm, std::vector< Ion > &ions) const
	Match the named ions of a theoretical spectrum against peak list index: one Ion per recognised ion.
void	matchIons (const PeakLists &peaks, Size index, const MSSpectrum &theoretical, const std::vector< Residue::ResidueType > &ion_types, const std::vector< UInt > &ion_ordinals, const std::vector< Int > &ion_charges, const AASequence &peptide, int precursor_charge, double tolerance, bool ppm, std::vector< Ion > &ions) const
	matchIons() with the ions given as codes instead of names: per peak of theoretical its ion type, ordinal and charge, as TheoreticalSpectrumGenerator::getIonSeriesSpectrum() writes them. The same ions as matchIons() on the spectrum of getSpectrum() with the names.
void	addObservations (const std::vector< Ion > &ions, bool noise)
	Add the matched ions of one PSM to the signal (noise false) or noise counts.
void	finalize ()
	Turn the counts into smoothed log-probabilities. Required before scoring; observations added later need another call.
bool	isTrained () const
	Whether finalize() was called after the last observation.
Size	signalPsms () const
	Number of confident PSMs added.
Size	noisePsms () const
	Number of reversed PSMs added.
double	pseudoCount () const
	Pseudo-count of the back-off smoothing.
double	logLikelihoodRatio (Size context, Size outcome) const
	ln P(outcome | signal, context) - ln P(outcome | noise, context)
double	presenceProbability (Size context) const
	Probability that an ion of this context is present in the spectrum of its peptide.
Features	score (const std::vector< Ion > &ions, Size top_k=6) const
	Features of one PSM from its matched ions (see matchIons()); top_k bounds top_predicted_observed.

Static Public Member Functions
static Size	rankBin (Size rank)
	Rank bin (0 .. RANK_BINS - 1) of a matched peak with the given 1-based intensity rank.
static Size	errorBin (double relative_error)
	Error bin (0 .. ERROR_BINS - 1) of a match with the given |mass error| / tolerance (at most 1)
static bool	parseIonName (const std::string &name, bool &prefix, Size &ordinal)
	Terminus and ordinal of an ion name as written by TheoreticalSpectrumGenerator, e.g. "b5+", "y3++", "z.4+".
static bool	parseIonSeries (const std::string &name, Size &series, Size &ordinal)
	parseIonName() that returns the ion series (see SERIES) instead of the terminus, e.g. 2 for "c7+" and 3 for "z.4+".
static Size	seriesOf (Residue::ResidueType type)
	Ion series (see SERIES) of an ion type (Residue::AIon ... Residue::Zp2Ion); SERIES for any other type.

Static Public Attributes
static constexpr Size	SERIES = 4
static constexpr Size	PRECURSOR_BUCKETS = 3
	precursor charge 1-2, 3, at least 4
static constexpr Size	FRAGMENT_CHARGES = 2
	fragment charge 1, at least 2
static constexpr Size	POSITION_BINS = 10
	fragment length / peptide length
static constexpr Size	CLEAVAGE_SITES = 3
	RICH: bond before P, bond after D or E, any other bond.
static constexpr Size	COMPLEMENT_STATES = 2
	RICH: complementary singly charged ion not matched / matched.
static constexpr Size	RANK_BINS = 7
	matched peak intensity rank bins
static constexpr Size	ERROR_BINS = 3
	RICH: |mass error| / tolerance below 0.25, below 0.5, up to 1.

Private Member Functions
template<typename IonOf , typename ChargeOf >
void	matchIons_ (const PeakLists &peaks, Size index, const MSSpectrum &theoretical, IonOf &&ion_of, ChargeOf &&charge_of, const AASequence &peptide, int precursor_charge, double tolerance, bool ppm, std::vector< Ion > &ions) const
	matchIons() for ion(i, series, ordinal) (false: not an ion of a series) and charge(i) of the peaks
Size	level1Context_ (Size context) const
	Contexts of the coarser back-off levels: level 1 is the coarsest above the flat prior.
Size	level2Context_ (Size context) const
std::vector< double >	smooth_ (const std::vector< double > &counts) const
	Smoothed log-probabilities of one count table, backing off over the context hierarchy.
void	requireTrained_ () const
	Throws unless finalize() was called after the last observation.

Private Attributes
ContextSet	context_set_
Size	sites_
	cleavage-site classes of the context set (1 for BASIC)
Size	complement_
	complement states of the context set (1 for BASIC)
Size	errors_
	error bins of the context set (1 for BASIC)
Size	contexts_
Size	outcomes_
std::vector< double >	signal_counts_
	contexts_ * outcomes_ counts of confident ions
std::vector< double >	noise_counts_
	contexts_ * outcomes_ counts of reversed ions
std::vector< double >	signal_logp_
	smoothed ln P(outcome | signal, context)
std::vector< double >	noise_logp_
	smoothed ln P(outcome | noise, context)
Size	signal_psms_ = 0
Size	noise_psms_ = 0
double	pseudo_count_ = 20.0
bool	finalized_ = false

Detailed Description

Per-run likelihood model of fragment ion presence, intensity rank and mass error, learned from confident PSMs.

Every theoretical ion of a peptide-spectrum match is placed in a context and gets an outcome. Two context sets are available (see ContextSet):

• BASIC: ion series (see SERIES: a/b, x/y, c, or z with z+1 and z+2), precursor charge (1-2, 3, at least 4), fragment charge (1 or higher) and relative position of the cleavage along the backbone (10 bins of fragment length / peptide length). Outcome: absent, or the intensity rank of the matched peak within the spectrum (7 rank bins: 1-2, 3-5, 6-10, 11-20, 21-40, 41-80, above 80).
• RICH: BASIC plus the residues at the cleavage site (bond X|P, bond D/E|X, any other bond) and whether the complementary singly charged ion (b for y, c for z and so on) was matched. Outcome: absent, or rank bin x mass-error bin (|error| / tolerance below 0.25, below 0.5, up to 1). This is a self-trained surrogate of the model-free part of the rich-ion likelihood of ANDES (ion context, complementary-ion coherence, matched rank and mass error).

The c and z ions of electron-based activation (ETD, ECD, EThcD, ETciD) are series of their own, apart from the b and y ions: their presence and intensity differ from those of b and y ions, also in the same spectrum (EThcD), and depend on the cleavage site in other ways (the N-Calpha bond of proline does not break, so c and z ions at a bond X|P are missing where b and y ions are often enhanced). Spectra with b and y ions only use the a/b and x/y series, whose contexts are the same whether or not other spectra of the run have c and z ions.

Two sets of counts are kept: the ions of confident peptides ("signal") and the ions of their reversed sequences matched against the same spectra ("noise"). finalize() turns both into smoothed probabilities with pseudo-count back-off over a context hierarchy (BASIC: full context -> series, precursor and fragment charge -> series -> flat prior; RICH: full context -> series, precursor and fragment charge, cleavage site, complement -> series and fragment charge -> flat prior), so that a few thousand PSMs suffice and unseen contexts stay finite.

A scored PSM yields three additive features: the summed log-likelihood ratio of its outcomes (present ions are credited, absent ions debited by what the run has taught about them), the fraction of the predicted ion presence that was observed, and the fraction of the ions most likely to be present that were observed. The model carries no pre-trained tables; it is meant to be trained on the run it scores, with the PSMs it scores held out from its training data (see ProSEAlgorithm, annotate:self_trained_ion_priors, which trains one model per half of the spectra and scores each half with the model of the other half).

The peaks are read from PeakLists, a compact copy of the spectra (m/z and intensity-rank bin per peak). Matching is closest-peak within the tolerance, as in HyperScore.

---

Class Documentation

OpenMS::FragmentIonLikelihoodModel::Features

struct OpenMS::FragmentIonLikelihoodModel::Features

Features of one PSM.

Class Members
double	explained_presence = 0.0	sum of P(present) over matched ions / sum of P(present) over all ions
double	log_likelihood_ratio = 0.0	sum over all theoretical ions of ln P(outcome | signal) / P(outcome | noise)
Size	matched_ions = 0	theoretical ions with a peak within tolerance
Size	theoretical_ions = 0	theoretical ions with a recognised ion name
double	top_predicted_observed = 0.0	fraction of the top_k ions with the highest P(present) that matched

OpenMS::FragmentIonLikelihoodModel::Ion

struct OpenMS::FragmentIonLikelihoodModel::Ion

One theoretical ion after matching.

Class Members
UInt32	context	flat context index, below contexts()
UInt32	outcome	outcome index, below outcomes(); absentOutcome() if unmatched

Member Enumeration Documentation

ContextSet

enum class ContextSet

strong

Ion contexts and outcomes the model distinguishes.

Enumerator
BASIC	series, precursor charge, fragment charge, position; outcome: intensity rank
RICH	BASIC plus cleavage-site residues and complementary-ion presence; outcome: intensity rank x mass error.

Constructor & Destructor Documentation

FragmentIonLikelihoodModel()

FragmentIonLikelihoodModel ( ContextSet  context_set = ContextSet::RICH, double  pseudo_count = 20.0  )

explicit

Untrained model.

Parameters

context_set	Contexts and outcomes to distinguish.
pseudo_count	Pseudo-count of the back-off smoothing (must be finite and positive).

Exceptions

Exception::InvalidParameter

if the pseudo-count is not finite and positive

Member Function Documentation

absentOutcome()

Size absentOutcome ( ) const

inline

Outcome of an unmatched ion.

addObservations()

void addObservations	(	const std::vector< Ion > &	ions,
		bool	noise
	)

Add the matched ions of one PSM to the signal (noise false) or noise counts.

contexts()

Size contexts ( ) const

inline

Number of ion contexts.

contextSet()

ContextSet contextSet ( ) const

inline

The context set of this model.

errorBin()

static Size errorBin ( double  relative_error )

static

Error bin (0 .. ERROR_BINS - 1) of a match with the given |mass error| / tolerance (at most 1)

finalize()

void finalize

(

)

Turn the counts into smoothed log-probabilities. Required before scoring; observations added later need another call.

isTrained()

bool isTrained ( ) const

inline

Whether finalize() was called after the last observation.

level1Context_()

Size level1Context_ ( Size  context ) const

private

Contexts of the coarser back-off levels: level 1 is the coarsest above the flat prior.

level2Context_()

Size level2Context_ ( Size  context ) const

private

logLikelihoodRatio()

double logLikelihoodRatio	(	Size	context,
		Size	outcome
	)		const

ln P(outcome | signal, context) - ln P(outcome | noise, context)

Exceptions

Exception::Precondition

if the model is not finalized.

Referenced by NuXLIonLikelihood::score().

matchIons() [1/2]

void matchIons	(	const PeakLists &	peaks,
		Size	index,
		const MSSpectrum &	theoretical,
		const AASequence &	peptide,
		int	precursor_charge,
		double	tolerance,
		bool	ppm,
		std::vector< Ion > &	ions
	)		const

Match the named ions of a theoretical spectrum against peak list index: one Ion per recognised ion.

Parameters

	peaks	Peak lists of the run.
	index	Peak list of the PSM's spectrum.
	theoretical	Sorted theoretical spectrum with ion names (first StringDataArray) and charges (first IntegerDataArray), as TheoreticalSpectrumGenerator writes them with add_metainfo. Without charges every ion counts as singly charged.
	peptide	The peptide of the theoretical spectrum (length; residues at the cleavage sites for RICH).
	precursor_charge	Precursor charge of the PSM.
	tolerance	Positive finite matching tolerance.
	ppm	Whether the tolerance is in ppm rather than Da.
[out]	ions	The matched ions, in the order of the theoretical spectrum.

Exceptions

Exception::InvalidValue	if the theoretical spectrum lacks ion names
Exception::InvalidParameter	if the tolerance is not finite and positive

Referenced by NuXLIonLikelihood::matchHypothesis_().

matchIons() [2/2]

void matchIons	(	const PeakLists &	peaks,
		Size	index,
		const MSSpectrum &	theoretical,
		const std::vector< Residue::ResidueType > &	ion_types,
		const std::vector< UInt > &	ion_ordinals,
		const std::vector< Int > &	ion_charges,
		const AASequence &	peptide,
		int	precursor_charge,
		double	tolerance,
		bool	ppm,
		std::vector< Ion > &	ions
	)		const

matchIons() with the ions given as codes instead of names: per peak of theoretical its ion type, ordinal and charge, as TheoreticalSpectrumGenerator::getIonSeriesSpectrum() writes them. The same ions as matchIons() on the spectrum of getSpectrum() with the names.

Exceptions

Exception::InvalidValue	if the codes do not have one entry per peak
Exception::InvalidParameter	if the tolerance is not finite and positive

matchIons_()

template<typename IonOf , typename ChargeOf >

void matchIons_ ( const PeakLists &  peaks, Size  index, const MSSpectrum &  theoretical, IonOf &&  ion_of, ChargeOf &&  charge_of, const AASequence &  peptide, int  precursor_charge, double  tolerance, bool  ppm, std::vector< Ion > &  ions  ) const

private

matchIons() for ion(i, series, ordinal) (false: not an ion of a series) and charge(i) of the peaks

noisePsms()

Size noisePsms ( ) const

inline

Number of reversed PSMs added.

outcomes()

Size outcomes ( ) const

inline

Number of outcomes, absence included.

parseIonName()

static bool parseIonName ( const std::string &  name, bool &  prefix, Size &  ordinal  )

static

Terminus and ordinal of an ion name as written by TheoreticalSpectrumGenerator, e.g. "b5+", "y3++", "z.4+".

Names carrying the ion type after a '$' (cross-link annotations) are supported. Returns false for names without a terminal series letter or ordinal.

Referenced by NuXLIonLikelihood::matchHypothesis_().

parseIonSeries()

static bool parseIonSeries ( const std::string &  name, Size &  series, Size &  ordinal  )

static

parseIonName() that returns the ion series (see SERIES) instead of the terminus, e.g. 2 for "c7+" and 3 for "z.4+".

presenceProbability()

double presenceProbability

(

Size

context

)

const

Probability that an ion of this context is present in the spectrum of its peptide.

Exceptions

Exception::Precondition

if the model is not finalized.

Referenced by NuXLIonLikelihood::score().

pseudoCount()

double pseudoCount ( ) const

inline

Pseudo-count of the back-off smoothing.

rankBin()

static Size rankBin ( Size  rank )

static

Rank bin (0 .. RANK_BINS - 1) of a matched peak with the given 1-based intensity rank.

requireTrained_()

void requireTrained_ ( ) const

private

Throws unless finalize() was called after the last observation.

score()

Features score	(	const std::vector< Ion > &	ions,
		Size	top_k = 6
	)		const

Features of one PSM from its matched ions (see matchIons()); top_k bounds top_predicted_observed.

Exceptions

Exception::Precondition

if the model is not finalized.

seriesOf()

static Size seriesOf ( Residue::ResidueType  type )

static

Ion series (see SERIES) of an ion type (Residue::AIon ... Residue::Zp2Ion); SERIES for any other type.

signalPsms()

Size signalPsms ( ) const

inline

Number of confident PSMs added.

smooth_()

std::vector< double > smooth_ ( const std::vector< double > &  counts ) const

private

Smoothed log-probabilities of one count table, backing off over the context hierarchy.

Member Data Documentation

CLEAVAGE_SITES

constexpr Size CLEAVAGE_SITES = 3

staticconstexpr

RICH: bond before P, bond after D or E, any other bond.

complement_

Size complement_

private

complement states of the context set (1 for BASIC)

COMPLEMENT_STATES

constexpr Size COMPLEMENT_STATES = 2

staticconstexpr

RICH: complementary singly charged ion not matched / matched.

Referenced by NuXLIonLikelihood::matchHypothesis_().

context_set_

ContextSet context_set_

private

contexts_

Size contexts_

private

ERROR_BINS

constexpr Size ERROR_BINS = 3

staticconstexpr

RICH: |mass error| / tolerance below 0.25, below 0.5, up to 1.

errors_

Size errors_

private

error bins of the context set (1 for BASIC)

finalized_

bool finalized_ = false

private

FRAGMENT_CHARGES

constexpr Size FRAGMENT_CHARGES = 2

staticconstexpr

fragment charge 1, at least 2

noise_counts_

std::vector<double> noise_counts_

private

contexts_ * outcomes_ counts of reversed ions

noise_logp_

std::vector<double> noise_logp_

private

smoothed ln P(outcome | noise, context)

noise_psms_

Size noise_psms_ = 0

private

outcomes_

Size outcomes_

private

POSITION_BINS

constexpr Size POSITION_BINS = 10

staticconstexpr

fragment length / peptide length

PRECURSOR_BUCKETS

constexpr Size PRECURSOR_BUCKETS = 3

staticconstexpr

precursor charge 1-2, 3, at least 4

pseudo_count_

double pseudo_count_ = 20.0

private

RANK_BINS

constexpr Size RANK_BINS = 7

staticconstexpr

matched peak intensity rank bins

SERIES

constexpr Size SERIES = 4

staticconstexpr

Ion series: a/b (0), x/y (1), c (2), and z, z+1, z+2 (3). Even series are N-terminal (prefix) ions, odd series C-terminal (suffix) ions; series s and s ^ 1 are complementary (b and y, c and z).

signal_counts_

std::vector<double> signal_counts_

private

contexts_ * outcomes_ counts of confident ions

signal_logp_

std::vector<double> signal_logp_

private

smoothed ln P(outcome | signal, context)

signal_psms_

Size signal_psms_ = 0

private

sites_

Size sites_

private

cleavage-site classes of the context set (1 for BASIC)