| <large>libXpertMassCore and libXpertMassGui Developer Documentation</large>

- libXpertMassCore
- FragmentationPathway

# MsXpS::libXpertMassCore::FragmentationPathway Class

class MsXpS::libXpertMassCore::FragmentationPathway

The FragmentationPathway class provides a model for specifying gas phase fragmentation pathways of Oligomer Sequences. More...

Header: | `#include <MsXpS/libXpertMassCore/FragmentationPathway.hpp>`
Inherited By: | MsXpS::libXpertMassCore::FragmentationConfig

- List of all members, including inherited members
- FragmentationPathway is part of Gas-phase chemical reactions.

## Public Functions

| FragmentationPathway(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QDomElement &element, int version)
| FragmentationPathway(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp = nullptr, const QString &name = QString(), const QString &formula_string = QString(), MsXpS::libXpertMassCore::Enums::FragEnd frag_end = Enums::FragEnd::NE, const QString &comment = QString())
| FragmentationPathway(const MsXpS::libXpertMassCore::FragmentationPathway &other)
virtual | ~FragmentationPathway()
void | addRule(MsXpS::libXpertMassCore::FragmentationRuleSPtr frag_rule_sp)
QString | formatXmlFgpElement(int offset, const QString &indent = Utils::xmlIndentationToken) const
QString | getComment() const
const MsXpS::libXpertMassCore::Formula & | getFormulaCstRef() const
MsXpS::libXpertMassCore::Formula & | getFormulaRef()
MsXpS::libXpertMassCore::Enums::FragEnd | getFragEnd() const
MsXpS::libXpertMassCore::FragmentationPathwayCstSPtr | getFromPolChemDefByName() const
int | getMonomerContribution() const
const QString & | getName() const
MsXpS::libXpertMassCore::PolChemDefCstSPtr | getPolchemDefCstSPtr() const
const std::vector<MsXpS::libXpertMassCore::FragmentationRuleSPtr> & | getRulesCstRef() const
std::vector<MsXpS::libXpertMassCore::FragmentationRuleSPtr> & | getRulesRef()
void | insertRuleAt(MsXpS::libXpertMassCore::FragmentationRuleSPtr frag_rule_sp, std::size_t index)
MsXpS::libXpertMassCore::Enums::PolChemDefEntityStatus | isKnownByNameInPolChemDef() const
bool | isValid() const
void | removeRuleAt(int index)
bool | renderXmlFgpElement(const QDomElement &element, int version = 2)
bool | renderXmlFgsElement(const QDomElement &element, int version = 1)
void | setComment(const QString &comment)
void | setFormula(const MsXpS::libXpertMassCore::Formula &formula)
void | setFormula(const QString &formula_string)
void | setFragEnd(MsXpS::libXpertMassCore::Enums::FragEnd frag_end)
void | setMonomerContribution(int monomer_contribution)
void | setName(const QString &name)
void | setPolchemDefCstSPtr(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp)
QString | toString() const
bool | validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | operator!=(const MsXpS::libXpertMassCore::FragmentationPathway &other) const
MsXpS::libXpertMassCore::FragmentationPathway & | operator=(const MsXpS::libXpertMassCore::FragmentationPathway &other)
bool | operator==(const MsXpS::libXpertMassCore::FragmentationPathway &other) const

## Protected Variables

QString | m_comment
MsXpS::libXpertMassCore::Formula | m_formula
MsXpS::libXpertMassCore::Enums::FragEnd | m_fragEnd
bool | m_isValid
int | m_monomerContribution
QString | m_name
std::vector<MsXpS::libXpertMassCore::FragmentationRuleSPtr> | m_rules
MsXpS::libXpertMassCore::PolChemDefCstSPtr | mcsp_polChemDef

## Detailed Description

The FragmentationPathway class provides the specification of a fragmentation pathway. Fragmentation pathways determine the chemical reaction that governs the fragmentation of the polymer in the gas-phase. The chemical reaction is embodied by a formula. The side of the polymer (left or right) that makes the fragment after the fragmentation has occurred is described by an Enums::FragEnd value.

A fragmentation pathway specification might not be enough information to determine the manner in which a polymer fragments in the gas-phase. Fragmentation rules (FragmentationRules) might be required to refine the specification. A fragmentation pathway specification might hold as many FragmentationRules as necessary to fully model it.

## Member Function Documentation

### FragmentationPathway::FragmentationPathway(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QDomElement &element, int version)

Constructs a FragmentationPathway instance starting from an XML <fgp> element according to version and using a reference pol_chem_def_csp polymer chemistry definition.

This is the current format (the fgr rule is FAKE):

    <fgp>
    <name>c</name>
    <end>LE</end>
    <formula>+N1H2</formula>
    <sidechaincontrib>0</sidechaincontrib>
    <comment>thefragmentationpathwaycomment</comment>
    <fgr>
    <name>a-fgr-2</name>
    <formula>+H100</formula>
    <prev-mnm-code>F</prev-mnm-code>
    <curr-mnm-code>D</curr-mnm-code>
    <next-mnm-code>E</next-mnm-code>
    <comment>therulecomment</comment>
    </fgr>
    </fgp>

The rendering of the FragmentationPathway instances requires that the PolChemDef be available.

Depending on version, two different functions are used to actually render the XML element. Before version 2, the XML element was named <fgs> (FragSpec class) and starting with version 2, the XML element is named <fgp> (FragmentationPathway class).

See also renderXmlFgpElement() and renderXmlFgsElement().

### FragmentationPathway::FragmentationPathway(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp = nullptr, const QString &name = QString(), const QString &formula_string = QString(), MsXpS::libXpertMassCore::Enums::FragEnd frag_end = Enums::FragEnd::NE, const QString &comment = QString())

Constructs a FragmentationPathway instance initialized with a number of parameters.

- pol_chem_def_csp: initializes mcsp_polChemDef, the polymer chemistry definition (PolChemDef)
- name: initializes m_name, the name of the fragmentation pathway (like 'y' for protein gas phase chemistry)
- formula_string: initializes m_formula, the formula that describes the gas phase reaction
- frag_end: initializes m_fragEnd, the end of the Oligomer sequence being fragmented that is kept in the product ions (a, b, c ions keep the left end of the Oligomer, while x, y, z ions keep the right end of the Oligomer)
- comment: initializes m_comment, a comment associated to the fragmentation pathway ("Observed with high energy collisions", for example)

Validation of this instance occurs after member data initialization and the result of the validation process is set to member m_isValid datum.

See also validate().

### FragmentationPathway::FragmentationPathway(const MsXpS::libXpertMassCore::FragmentationPathway &other)

Constructs a FragmentationPathway instance as a copy of other.

Validation of this instance occurs after member data initialization and the result of the validation process is set to member m_isValid datum.

See also validate().

### `[virtual noexcept]` FragmentationPathway::~FragmentationPathway()

Destructs this FragmentationPathway instance.

### void FragmentationPathway::addRule(MsXpS::libXpertMassCore::FragmentationRuleSPtr frag_rule_sp)

Adds the frag_rule_sp FragmentationRule instance to the member m_rules container of FragmentationRule instances.

Validation of this instance occurs after member data initialization and the result of the validation process is set to member m_isValid datum.

### QString FragmentationPathway::formatXmlFgpElement(int offset, const QString &indent = Utils::xmlIndentationToken) const

Formats a string representing this FragmentationPathway instance suitable to use as an XML element.

The typical fragmentation pathway element that is generated in this function looks like this:

    <fgp>
    <name>a</name>
    <end>LE</end>
    <formula>-C1O1</formula>
    <sidechaincontrib>0</sidechaincontrib>
    <comment>opt_comment</comment>
    <fgr>
    <name>a-fgr-1</name>
    <formula>+H200</formula>
    <prev-mnm-code>E</prev-mnm-code>
    <curr-mnm-code>D</curr-mnm-code>
    <next-mnm-code>F</next-mnm-code>
    <comment>opt_comment</comment>
    </fgr>
    <fgr>
    <name>a-fgr-2</name>
    <formula>+H100</formula>
    <prev-mnm-code>F</prev-mnm-code>
    <curr-mnm-code>D</curr-mnm-code>
    <next-mnm-code>E</next-mnm-code>
    <comment>opt_comment</comment>
    </fgr>
    </fgp>

The formatting of the XML element takes into account offset and indent by prepending the string with [offset * indent string] substring.

indent defaults to two spaces.

### QString FragmentationPathway::getComment() const

Returns the comment.

### const MsXpS::libXpertMassCore::Formula &FragmentationPathway::getFormulaCstRef() const

Returns a const reference to the member m_formula Formula.

### MsXpS::libXpertMassCore::Formula &FragmentationPathway::getFormulaRef()

Returns a reference to the member m_formula Formula.

### MsXpS::libXpertMassCore::Enums::FragEnd FragmentationPathway::getFragEnd() const

Returns the Enums::FragEnd.

### MsXpS::libXpertMassCore::FragmentationPathwayCstSPtr FragmentationPathway::getFromPolChemDefByName() const

Returns the FragmentationPathway instance from the polymer chemistry definition registered in this instance.

The key to search for the FragmentationPathway is this instance's name member.

If there is no PolChemDef available, or if no FragmentationPathway instance is found by this instance's name, nullptr is returned.

### int FragmentationPathway::getMonomerContribution() const

Returns the Monomer contribution.

### const QString &FragmentationPathway::getName() const

Returns the name.

### MsXpS::libXpertMassCore::PolChemDefCstSPtr FragmentationPathway::getPolchemDefCstSPtr() const

Returns the PolChemDef (polymer chemistry definition).

### const std::vector<MsXpS::libXpertMassCore::FragmentationRuleSPtr> &FragmentationPathway::getRulesCstRef() const

Returns a const reference to the member m_rules container of FragmentationRule instances.

### std::vector<MsXpS::libXpertMassCore::FragmentationRuleSPtr> &FragmentationPathway::getRulesRef()

Returns a reference to the member m_rules container of FragmentationRule instances.

### void FragmentationPathway::insertRuleAt(MsXpS::libXpertMassCore::FragmentationRuleSPtr frag_rule_sp, std::size_t index)

Inserts in the container of FragmentationRule instances at index the frag_rule_sp FragmentationRule instance. If index is the container size, the FragmentationRule is added at the end of the container.

Validation of this instance occurs after member data initialization and the result of the validation process is set to member m_isValid datum.

### MsXpS::libXpertMassCore::Enums::PolChemDefEntityStatus FragmentationPathway::isKnownByNameInPolChemDef() const

Returns the status of this FragmentationPathway instance in the polymer chemistry definition registered in this instance.

The key to search the FragmentationPathway is this instance's name member.

If there is no PolChemDef available, Enums::PolChemDefEntityStatus::POL_CHEM_DEF_NOT_AVAILABLE is returned.

If no FragmentationPathway instance is found by this instance's name, Enums::PolChemDefEntityStatus::ENTITY_NOT_KNOWN is returned, otherwise Enums::PolChemDefEntityStatus::ENTITY_KNOWN is returned.

### bool FragmentationPathway::isValid() const

Returns the validity status of this FragmentationPathway instance.

### void FragmentationPathway::removeRuleAt(int index)

Removes from the member m_rules container the item at index index.

### bool FragmentationPathway::renderXmlFgpElement(const QDomElement &element, int version = 2)

Parses a fragmentation pathway XML element using a versioned function.

This function is used for polymer chemistry definition documents of version greater or equal to 2 (the XML element tag is <fgp>, for FragmentationPathway class).

Upon parsing and validation of the parsed data, the member data are updated, thus essentially initializing this FragmentationPathway instance.

Validation of this instance occurs after member data initialization.

Returns true if parsing and validation were successful, false otherwise.

See also renderXmlFgsElement() and validate().

### bool FragmentationPathway::renderXmlFgsElement(const QDomElement &element, int version = 1)

Parses a fragmentation pathway XML element using a versioned function.

This function is used for polymer chemistry definition documents of version less than 2 (the XML element tag is <fgs>, for FragSpec class).

Upon parsing and validation of the parsed data, the member data are updated, thus essentially initializing this FragmentationPathway instance.

Validation of this instance occurs after member data initialization.

Returns true if parsing and validation were successful, false otherwise.

See also renderXmlFgpElement() and validate().

### void FragmentationPathway::setComment(const QString &comment)

Sets the member m_comment string to comment.

### void FragmentationPathway::setFormula(const MsXpS::libXpertMassCore::Formula &formula)

Sets the member m_formula Formula to formula.

Validation of this instance occurs after member data initialization and the result of the validation process is set to member m_isValid datum.

See also validate().

### void FragmentationPathway::setFormula(const QString &formula_string)

Sets the member m_formula Formula using formula_string.

Validation of this instance occurs after member data initialization and the result of the validation process is set to member m_isValid datum.

See also validate().

### void FragmentationPathway::setFragEnd(MsXpS::libXpertMassCore::Enums::FragEnd frag_end)

Sets the member m_fragEnd precursor end to frag_end.

Upon fragmentation, two fragments are generated, one holding the left end of the initial precursor ion and one holding the right end. frag_end indicates if the fragment (that is, the product ion) is a left end fragment or a right end fragment. For example, in protein gas phase chemistry, the ions of the series a, b and c hold the left end of the precursor ion, while the ions of the series x, y, and z hold the right end of the precursor ion.

### void FragmentationPathway::setMonomerContribution(int monomer_contribution)

Sets the Monomer contribution to monomer_contribution.

In certain fragmentation pathways, the monomer undergoing decomposition might lose a portion of its structure. This is the case in nucleic acids fragmentation, when the nucleic base might be detached from the monomer undergoing the fragmentation reaction.

This member allows to indicate if a part of the monomer is detaching upon decomposition. In this case, this value is negative (-1) and indicates that the mass of the Monomer is to be removed from the mass of the fragment. However, because it is not the full monomer that decomposes away, but only a part of it, then it is the responsibility of the polymer chemistry definition designer to add back the formula of the conserved monomer structure.

For example, in DNA fragmentation, the `abasic a` fragmentation pathway is defined with a monomer contribution of -1, with the `-HOH+C5H8O5P` formula to account for the remaining structure of the monomer (this combination has a net loss of the base only and does not account for loss of the phospho moiety of the monomer).

### void FragmentationPathway::setName(const QString &name)

Sets the member m_name string to name.

Validation of this instance occurs after member data initialization and the result of the validation process is set to member m_isValid datum.

See also validate().

### void FragmentationPathway::setPolchemDefCstSPtr(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp)

Sets the member mcsp_polChemDef PolChemDef (polymer chemistry definition) to pol_chem_def_csp.

Validation of this instance occurs after member data initialization and the result of the validation process is set to member m_isValid datum.

See also validate().

### QString FragmentationPathway::toString() const

Crafts a string documenting this FragmentationPathway instance and returns it.

### bool FragmentationPathway::validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Validates this FragmentationPathway instance, recording any error with a message in error_list_p if non-nullptr.

The validation involves the following checks:

- The member mcsp_polChemDef polymer chemistry definition is available (non-nullptr).
- The member m_name string is not empty.
- The member m_formula Formula is not empty and validates successfully against the IsotopicData in the PolChemDef.
- Any defined fragmentation rule validates successfully.

If the validation is successful, member m_isValid status is set to true, otherwise it is set to false.

Returns the outcome of the validation.

### bool FragmentationPathway::operator!=(const MsXpS::libXpertMassCore::FragmentationPathway &other) const

Returns true if `this` and other are different.

Returns the negated result of operator==().

See also operator==().

### MsXpS::libXpertMassCore::FragmentationPathway &FragmentationPathway::operator=(const MsXpS::libXpertMassCore::FragmentationPathway &other)

Assigns other to this FragmentationPathway instance and returns a reference to this instance.

Validation of this instance occurs after member data initialization and the result of the validation process is set to member m_isValid datum.

See also validate().

### bool FragmentationPathway::operator==(const MsXpS::libXpertMassCore::FragmentationPathway &other) const

Returns true if `this` and other are identical.

Because the FragmentationRule instances are not a reference to the PolChemDef, their comparison is deep.

See also operator!=().

## Member Variable Documentation

### QString FragmentationPathway::m_comment

This variable holds a comment associated to the FragmentationPathway.

### MsXpS::libXpertMassCore::Formula FragmentationPathway::m_formula

This variable holds a Formula instance describing the fragmentation reaction occurring on the Monomer at which the decomposition occurs.

### MsXpS::libXpertMassCore::Enums::FragEnd FragmentationPathway::m_fragEnd

This variable holds the end of the Oligomer precursor ion that is found in the product ion.

This member datum defines what is the end of the Oligomer sequence that is kept in the product ions (a, b, c ions keep the Enums::FragEnd::LE, left end, of the Oligomer, while x, y, z ions keep the Enums::FragEnd::RE, right end, of the Oligomer; instead in protein ammonium ions, Enums::FragEnd::NE, no end, is found in the product ions).

### bool FragmentationPathway::m_isValid

This variable holds the validity status of this FragmentationPathway instance.

### int FragmentationPathway::m_monomerContribution

Contribution of the Monomer skeleton when decomposition occurs.

In some situations (nucleic acids, for example), upon fragmentation, the Oligomer loses the nucleic base at the location of the backbone decomposition (which yields an abasic ion product). This member allows to indicate that the monomer (that is, the residue) is to be accounted for (by a -1 value, the program accounts that the monomer is lost during decomposition). But removing the whole Monomer is not correct because that removes too much material, so the member m_formula should account for the compensation of the removed Monomer.

### QString FragmentationPathway::m_name

This variable holds the name of the FragmentationPathway.

### std::vector<MsXpS::libXpertMassCore::FragmentationRuleSPtr> FragmentationPathway::m_rules

This variable holds the container of all the FragmentationRuleSPtr that allow refining how the fragmentation occurs at site depending on the identity of the Monomer occurring either at previous position or next position with respect to the position in the Oligomer undergoing fragmentation. The FragmentationRule instances are required in the gas phase chemistry of sugars where the way decomposition occurs at a given site depends on the identity of the immediate proximity of the decomposing backbone region.

### MsXpS::libXpertMassCore::PolChemDefCstSPtr FragmentationPathway::mcsp_polChemDef

This variable holds the PolChemDef (polymer chemistry definition) that is the context in which the Oligomer being fragmented exists.