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

- libXpertMassCore
- FragmentationRule

# MsXpS::libXpertMassCore::FragmentationRule Class

class MsXpS::libXpertMassCore::FragmentationRule

The FragmentationRule class provides a model for specifying gas phase fragmentation rules for refining fragmentation pathway specifications (FragmentationPathway) of Oligomer Sequences. More...

Header: | `#include <MsXpS/libXpertMassCore/FragmentationRule.hpp>`

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

## Public Functions

| FragmentationRule(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QDomElement &element, int version)
| FragmentationRule(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp = nullptr, const QString &name = QString(), const QString &prev_code = QString(), const QString &current_code = QString(), const QString &next_code = QString(), const QString &comment = QString(), const QString &formula_string = QString())
| FragmentationRule(const MsXpS::libXpertMassCore::FragmentationRule &other)
virtual | ~FragmentationRule()
QString | formatXmlFgrElement(int offset, const QString &indent = Utils::xmlIndentationToken)
const QString & | getComment() const
const QString & | getCurrCode() const
const MsXpS::libXpertMassCore::Formula & | getFormulaCstRef() const
MsXpS::libXpertMassCore::Formula & | getFormulaRef()
const QString & | getName()
const QString & | getNextCode() const
MsXpS::libXpertMassCore::PolChemDefCstSPtr | getPolchemDefCstSPtr() const
const QString & | getPrevCode() const
bool | isValid() const
bool | renderXmlFgrElement(const QDomElement &element)
void | setComment(const QString &comment)
void | setCurrCode(const QString &code)
void | setFormula(const MsXpS::libXpertMassCore::Formula &formula)
void | setFormula(const QString &formula_string)
void | setName(const QString &name)
void | setNextCode(const QString &code)
void | setPolchemDefCstSPtr(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp)
void | setPrevCode(const QString &code)
QString | toString() const
bool | validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | operator!=(const MsXpS::libXpertMassCore::FragmentationRule &other) const
MsXpS::libXpertMassCore::FragmentationRule & | operator=(const MsXpS::libXpertMassCore::FragmentationRule &other)
bool | operator==(const MsXpS::libXpertMassCore::FragmentationRule &other) const

## Protected Variables

QString | m_comment
QString | m_currCode
MsXpS::libXpertMassCore::Formula | m_formula
bool | m_isValid
QString | m_name
QString | m_nextCode
QString | m_prevCode
MsXpS::libXpertMassCore::PolChemDefCstSPtr | mcsp_polChemDef

## Detailed Description

Fragmentation rules characterize in more detail the chemical reaction that governs the fragmentation of the polymer in the gas-phase. The rule is a conditional rule. Its logic is based on the presence of specified monomers right at the place of the fragmentation and before or after that precise location.

In saccharide chemistry, fragmentations are a very complex topic. This is because a given monomer will fragment according to a given chemistry if it is preceded in the sequence by a monomer of a given identity and according to another chemistry if its direct environment is different.

This paradigm is implemented using a sequence environment logic based on conditions that can be formulated thanks to three monomer codes:

- The monomer at which the fragmentation takes place (current code);
- The monomer preceeding the current code (previous code);
- The monomer following the current code (next code);

The use of these codes is typically according to this kind of logic:

If current monomer is Glu and previous monomer is Gly and next monomer is Arg, then fragmentation should occur according to this formula : "-H2O".

See also FragmentationPathway.

## Member Function Documentation

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

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

This is the current format (FAKE 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>comment here!</comment>
    </fgr>

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

See also renderXmlFgrElement().

### FragmentationRule::FragmentationRule(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp = nullptr, const QString &name = QString(), const QString &prev_code = QString(), const QString &current_code = QString(), const QString &next_code = QString(), const QString &comment = QString(), const QString &formula_string = QString())

Constructs a fragmentation rule with a number of parameters.

- pol_chem_def_csp Polymer chemistry definition. Cannot be nullptr.
- name Name. Cannot be empty.
- prev_code Previous monomer code. Defaults to the null string.
- current_code Current monomer code. Defaults to the null string.
- next_code Next monomer code. Defaults to the null string.
- comment Comment. Defaults to the null string.
- formula_string Formula. Defaults to the null string.

Upon setting all the member data, this instance is validated and the member m_isValid is set to the result.

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

Constructs a FragmentationRule instance as a copy of other.

Upon setting all the member data, this instance is validated and the member m_isValid is set to the result.

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

Destructs the fragmentation rule.

### QString FragmentationRule::formatXmlFgrElement(int offset, const QString &indent = Utils::xmlIndentationToken)

Formats a string suitable to use as an XML element.

The string is suitable to be used as an XML element in a polymer chemistry definition file. The typical fragmentation rule element that is generated in this function looks like this:

    <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>comment here!</comment>
    </fgr>

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

indent defaults to two spaces.

Returns a dynamically allocated string that needs to be freed after use.

### const QString &FragmentationRule::getComment() const

Returns the comment.

### const QString &FragmentationRule::getCurrCode() const

Returns the current monomer code.

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

Returns a const reference to the member Formula.

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

Returns a reference to the member Formula.

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

Returns the name.

### const QString &FragmentationRule::getNextCode() const

Returns the next monomer code.

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

Returns the PolChemDef.

### const QString &FragmentationRule::getPrevCode() const

Returns the previous monomer code.

### bool FragmentationRule::isValid() const

Returns the validity status of this FragmentationRule.

### bool FragmentationRule::renderXmlFgrElement(const QDomElement &element)

Parses the FragmentationRule XML element.

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

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

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

Sets the comment.

### void FragmentationRule::setCurrCode(const QString &code)

Sets the current monomer code.

Upon setting the member data, this instance is validated and the member m_isValid is set to the result.

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

Sets the formula.

Upon setting the member data, this instance is validated and the member m_isValid is set to the result.

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

Sets the member Formula using formula_string.

Upon setting the member data, this instance is validated and the member m_isValid is set to the result.

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

Sets the name to name.

### void FragmentationRule::setNextCode(const QString &code)

Sets the next monomer code.

Upon setting the member data, this instance is validated and the member m_isValid is set to the result.

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

Sets the PolChemDef to pol_chem_def_csp.

### void FragmentationRule::setPrevCode(const QString &code)

Sets the previous monomer code.

Upon setting the member data, this instance is validated and the member m_isValid is set to the result.

### QString FragmentationRule::toString() const

Returns a string with the textual representation of this FragmentationRule instance.

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

Validates the FragmentationRule, recording any error as a message in error_list_p.

The validation involves checking that:

- The member PolChemDef cannot be nullptr.
- The name is not empty.
- The previous code is valid if non empty.
- The current code is valid if non empty.
- The next code is valid if non empty.
- The formula validates successfully if non empty.

The m_isValid member is set to true upon success, false otherwise and returned.

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

Returns true if `this` and other are different.

Returns the negated result of operator==().

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

Assigns other to this FragmentationRule instance.

Upon setting the member data, this instance is validated and the member m_isValid is set to the result.

Returns a reference to this fragmentation rule.

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

Returns true if `this` instance and other are identical.

## Member Variable Documentation

### QString FragmentationRule::m_comment

This variable holds a comment associated to the FragmentationRule.

### QString FragmentationRule::m_currCode

This variable holds the Monomer code of the Monomer at the actual fragmentation site.

### MsXpS::libXpertMassCore::Formula FragmentationRule::m_formula

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

### bool FragmentationRule::m_isValid

This variable holds the validity status of this FragmentationRule instance.

### QString FragmentationRule::m_name

This variable holds the name of the FragmentationRule.

### QString FragmentationRule::m_nextCode

This variable holds the Monomer code of the Monomer located after the actual fragmentation site.

### QString FragmentationRule::m_prevCode

This variable holds the Monomer code of the Monomer located before the actual fragmentation site.

### MsXpS::libXpertMassCore::PolChemDefCstSPtr FragmentationRule::mcsp_polChemDef

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