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

- libXpertMassCore
- Modif

# MsXpS::libXpertMassCore::Modif Class

class MsXpS::libXpertMassCore::Modif

The Modif class provides abstractions to work with chemical modifications. More...

Header: | `#include <Modif.hpp>`
Inherits: | MsXpS::libXpertMassCore::PropListHolder

- List of all members, including inherited members
- Modif is part of Polymer chemistry building blocks.

## Public Functions

| Modif(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QDomElement &element, int version)
| Modif(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp = nullptr, const QString &modif_name = QString(), const QString &formula_string = QString(), double mono = 0.0, double avg = 0.0)
| Modif(const MsXpS::libXpertMassCore::Modif &other)
virtual | ~Modif()
const MsXpS::libXpertMassCore::Modif & | accountMasses(double &mono, double &avg, int times = 1) const
const MsXpS::libXpertMassCore::Modif & | accountMasses(double *mono_p = nullptr, double *avg_p = nullptr, int times = 1) const
bool | calculateMasses(const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp)
MsXpS::libXpertMassCore::Modif & | calculateMasses(bool &ok, const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp)
bool | calculateMasses(const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp, double &mono, double &avg) const
void | clear()
bool | doesTargetMonomer(const QString &code) const
QString | formatXmlMdfElement(int offset, const QString &indent = Utils::xmlIndentationToken) const
MsXpS::libXpertMassCore::ModifCstSPtr | getFromPolChemDefByName() const
double | getMass(MsXpS::libXpertMassCore::Enums::MassType mass_type)
int | getMaxCount() const
QString | getName() const
const MsXpS::libXpertMassCore::PolChemDefCstSPtr & | getPolChemDefCstSPtr() const
QString | getTargets() const
MsXpS::libXpertMassCore::Enums::PolChemDefEntityStatus | isKnownByNameInPolChemDef() const
bool | isValid() const
bool | renderXmlMdfElement(const QDomElement &element, int version)
void | setFormula(const QString &formula_string)
void | setMaxCount(int value)
void | setName(const QString &name)
void | setPolChemDefCstSPtr(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp)
void | setTargets(const QString &targets)
QString | toString() const
bool | validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const
QString | validateTargets(bool simplify, bool &ok)
QString | validateTargets(const QString &targets_string, bool simplify, bool &ok) const
bool | operator!=(const MsXpS::libXpertMassCore::Modif &other) const
MsXpS::libXpertMassCore::Modif & | operator=(const MsXpS::libXpertMassCore::Modif &other)
bool | operator==(const MsXpS::libXpertMassCore::Modif &other) const

## Protected Variables

double | m_avg
QString | m_formula
bool | m_isValid
int | m_maxCount
double | m_mono
QString | m_name
QString | m_targets
MsXpS::libXpertMassCore::PolChemDefCstSPtr | mcsp_polChemDef

## Detailed Description

The Modif class provides a chemical modification that can be set to any monomer in a polymer sequence or to any one of the polymer sequence ends. In the protein world, chemical modifications of proteins that occur in the living cell are called post-translational modifications.This class aims at modelling, among others, such modifications.

The chemical reaction described by the Modif class is encoded as an action-formula (see Formula).

## Member Function Documentation

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

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

The version indicates what version of the XML element is to be used.

This is the current format:

    <mdf>
    <name>Acetylation</name>
    <formula>C2H2O1</formula>
    <targets>;K;</targets>
    <maxcount>1</maxcount>
    </mdf>
    <mdf>
    <name>AmidationAsp</name>
    <formula>H1N1-O1</formula>
    <targets>;D;</targets>
    <maxcount>1</maxcount>
    </mdf>

The XML element is rendered using the dedicated function renderXmlMdfElement().

See also renderXmlMdfElement().

### Modif::Modif(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp = nullptr, const QString &modif_name = QString(), const QString &formula_string = QString(), double mono = 0.0, double avg = 0.0)

Constructs a modification.

A Modif instance cannot be of any use if it is not associated logically to a polymer chemistry definition (pol_chem_def_csp). The Modif instance is defined by its modif_name and its formula_string as as string (that defaults to empty in this constructor).

Being able to construct a Modif without a formula string is necessary when Modif objects are intialized piecemeal upon reading XML elements that describe the Modif.

The formula_string might be a simple formula ("O", for an oxidation) or an action-formula, if that is desirable to best characterize the modification ("-H20+CH3COOH", for example, for an acetylation). The formula string can also have a title, like:

`"Acetylation"-H20+CH3COOH`.

The member string datum representing the allowed targets of this Modif instanceis set to "all" (that is, `"*"`) and the maximum count that this modification can bet set to a given target is set to `1` by default, like a Seryl residue can only be phosphorylated once, for example.

After setting the member data and if the polymer chemistry definition is available, validate() is called, the masses are calculated and if all went without error the member m_isValid validity status is set to true, otherwise it is set to false.

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

Constructs a Modif object as a copy of other.

After setting the member data and if the polymer chemistry definition is available, validate() is called, the masses are calculated and if all went without error the member m_isValid validity status is set to true, otherwise it is set to false.

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

Destructs this Modif.

### const MsXpS::libXpertMassCore::Modif &Modif::accountMasses(double &mono, double &avg, int times = 1) const

Adds to mono and avg the corresponding mass of this modification.

The m_mono and m_avg masses are added to the arguments. The masses are compounded by factor times before the addition.

Returns this object.

### const MsXpS::libXpertMassCore::Modif &Modif::accountMasses(double *mono_p = nullptr, double *avg_p = nullptr, int times = 1) const

Adds to mono_p and avg_p the corresponding mass of this modification.

The m_mono and m_avg masses are added to the arguments. The masses are compounded by factor times before the addition.

Returns this object.

### bool Modif::calculateMasses(const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp)

Calculates the net masses of this modification.

The masses of the modification are the masses (monoisotopic and average) that are added to the target as a result of that target being modified with this modification.

The calculated masses are set to the m_mono and m_avg members.

The mass calculations are performed using reference data in isotopic_data_csp. If isotopic_data_csp is nullptr, then the reference data are searched in the member polymer chemistry definition.

Returns true if the mass calculations were successful, false otherwise.

If the calculations failed, m_isValid is set to false.

See also Formula::accountMasses().

### MsXpS::libXpertMassCore::Modif &Modif::calculateMasses(bool &ok, const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp)

Calculates the net masses of this modification.

The masses of the modification are the masses (monoisotopic and average) that are added to the target as a result of that target being modified with this modification.

The calculated masses are set to the m_mono and m_avg members.

The mass calculations are performed using reference data in isotopic_data_csp. If isotopic_data_csp is nullptr, then the reference data are searched in the member polymer chemistry definition.

Returns a reference to this Modif instance.

If the calculations failed, m_isValid is set to false.

See also Formula::accountMasses().

### bool Modif::calculateMasses(const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp, double &mono, double &avg) const

Calculates the net masses of this modification and sets the results in mono and avg.

The masses of the modification are the masses (monoisotopic and average) that are added to the target as a result of that target being modified with this modification.

The mass calculations are performed using reference data in isotopic_data_csp. If isotopic_data_csp is nullptr, then the reference data are searched in the member polymer chemistry definition.

Returns true if the mass calculations were successful, false otherwise.

If the calculations failed, m_isValid is set to false.

See also Formula::accountMasses().

### void Modif::clear()

Resets this modification to an empty object.

### bool Modif::doesTargetMonomer(const QString &code) const

Returns true if Mnomer code is found among the targets of this Modif instance, false otherwise.

### QString Modif::formatXmlMdfElement(int offset, const QString &indent = Utils::xmlIndentationToken) const

Formats this modification's data as a string suitable to be used as a `mdf` XML element in the polymer chemistry definition or a polymer sequence file.

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

    <mdf>
    <name>Acetylation</name>
    <formula>C2H2O1</formula>
    <targets>;K;</targets>
    <maxcount>1</maxcount>
    </mdf>
    <mdf>
    <name>AmidationAsp</name>
    <formula>H1N1-O1</formula>
    <targets>;D;</targets>
    <maxcount>1</maxcount>
    </mdf>

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 string.

### MsXpS::libXpertMassCore::ModifCstSPtr Modif::getFromPolChemDefByName() const

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

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

If there is no PolChemDef available, nullptr is returned.

If no Modif instance is found by this instance's name, nullptr is returned.

### double Modif::getMass(MsXpS::libXpertMassCore::Enums::MassType mass_type)

Returns the mass of the type defined by mass_type.

### int Modif::getMaxCount() const

Returns the maximum count of times that this modification might be set to a target.

### QString Modif::getName() const

Returns the name.

### const MsXpS::libXpertMassCore::PolChemDefCstSPtr &Modif::getPolChemDefCstSPtr() const

Returns the polymer chemistry definition.

### QString Modif::getTargets() const

Returns the tagets of this modification.

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

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

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

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

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

### bool Modif::isValid() const

Returns the validity status of this Modif instance.

### bool Modif::renderXmlMdfElement(const QDomElement &element, int version)

Parses the modification XML element specifically for version.

Parses the modif `mdf` XML element passed as argument and for each encountered data will set the data to this modif (this is called XML rendering).The parsing is delegated to a function that is specific for version of the polymer chemistry definition.

The `mdf` XML element is found in the polymer chemistry definition and has the following form:

    <mdf>
    <name>Acetylation</name>
    <formula>C2H2O1</formula>
    <targets>;K;</targets>
    <maxcount>1</maxcount>
    </mdf>
    <mdf>
    <name>AmidationAsp</name>
    <formula>H1N1-O1</formula>
    <targets>;D;</targets>
    <maxcount>1</maxcount>
    </mdf>

After setting all the data, this modification calculates it masses and validates itself. If any of these steps fails, the error is reported by returning false.

Returns true if parsing was successful, false otherwise.

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

Sets the formula to formula_string.

After setting the member data and if the polymer chemistry definition is available, validate() is called, the masses are calculated and if all went without error the member m_isValid validity status is set to true, otherwise it is set to false.

### void Modif::setMaxCount(int value)

Sets the maximum count (times the modification event is allowed to occur on a target) that this modification might be set to a target to value.

For Phosphorylation, for example, that would be `1` count exclusively for modification of Seryl, Threonyl and Tyrosinyl residues.

After setting the member data, validate() is called and the m_isValid member is set to the result of the validation.

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

Sets the name.

After setting the member data, validate() is called and the m_isValid member is set to the result of the validation.

### void Modif::setPolChemDefCstSPtr(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp)

Sets the polymer chemistry definition to pol_chem_def_csp.

After setting the member data, validate() is called and the m_isValid member is set to the result of the validation.

### void Modif::setTargets(const QString &targets)

Sets the targets for this modification.

Setting the targets of a Modif instance means specifying which target (Monomer code) might be modified using this modification. For example, for `Phosphorylation`, in protein chemistry, one would define targets as `Serine`, `Threonine`, `Tyrosine` (there are other targets, like Histidine, but very rarely encountered).

Multiple targets are separated using ';'.

The targets are validated (Modif::validateTargets()) and the obtained string is set to m_targets. If the validation fails, m_targets is set to QString().

After setting the member data, validate() is called and the m_isValid member is set to the result of the validation.

### QString Modif::toString() const

Returns a string representing this Modif instance.

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

Validates this modification, sets the validity status accordingly and returns it.

Any potential error is reported with a message added to error_list_p (that is not cleared).

The modification validates successfully if:

- The member polymer chemistry definition is available and the isotopic data inside it also
- The name is not empty
- The formula validates successfully
- The masses can be calculated (on local mass variables, given constness of this function)
- The targets validate successfully (that is, they reference Monomer codes known to the polymer chemistry definition)
- The m_maxCount member is greater than 0

If the validation is successful, the validity status (m_isValide) is set to true, to false otherwise, and returned.

### QString Modif::validateTargets(bool simplify, bool &ok)

Validates the member targets and returns the processed targets string.

If simplify is true, then, whenever '*' or '!' is encountered in the member targets string, then ok is set to true and either '*' or '!' is returned. Indeed, the target list is split using ';' as a delimiter. If '*' is found and simplify is true, the function returns '*' immediately (as all the monomers in the polymer chemistry definition might be a target of this modification) and ok is set to true. Likewise, if '!' is found and simplify is true, the function returns '!' immediately (as none of all the monomers in the polymer chemistry definition might be a target of this modification) and ok is set to true.

If at least one target is found, then each target is a monomer code and that code is looked for in the member polymer chemistry definition list of monomers. If the code is found, that code is added to a temporary string. If the code is not found, ok is set to false and the member targets string is returned unchanged.

When the process completes, without error, ok is set to true and the string corresponding to the processed monomer codes in the member targets string is returned. Otherwise, ok is set to false and an empty string is returned.

### QString Modif::validateTargets(const QString &targets_string, bool simplify, bool &ok) const

Validates the targets_string target and returns the processed targets string.

If targets_string is non-empty, it is validated. Otherwise, ok is set to false and targets_string is returned unchanged.

If simplify is true, then, whenever '*' or '!' is encountered in targets_string, then ok is set to true and either '*' or '!' is returned. Indeed, the target list is split using ';' as a delimiter. If '*' is found and simplify is true, the function returns '*' immediately (as all the monomers in the polymer chemistry definition might be a target of this modification) and ok is set to true. Likewise, if '!' is found and simplify is true, the function returns '!' immediately (as none of all the monomers in the polymer chemistry definition might be a target of this modification) and ok is set to true.

If at least one target is found, then each target is a monomer code and that code is looked for in the member polymer chemistry definition list of monomers. If the code is found, that code is added to a temporary string. If the code is not found, ok is set to false and targets_string is returned unchanged.

When the process completes, without error, ok is set to true and the string corresponding to the processed monomer codes in the targets_string is returned. Otherwise, ok is set to false and an empty string is returned.

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

Returns true if this and the other modifications differ, false otherwise.

Returns the negated result of operator==().

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

Assigns other to this modification.

Returns a reference to this modification.

After setting the member data, validate() is called and the m_isValid member is set to the result of the validation.

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

Returns true if this and the other modifications are identical, false otherwise.

## Member Variable Documentation

### double Modif::m_avg

Value representing the average mass of the formula.

### QString Modif::m_formula

Formula string representing the chemical modification.

### bool Modif::m_isValid

Validity status of the Modif instance.

### int Modif::m_maxCount

Value indicating the maximum number of times this modification can be set to a target entity (monomer or polymer).

The value cannot be less than one, otherwise the Modif is set to an invalid state.

This member is designed to prohibit modifying more than chemically possible a given Monomer. For example it is not possible to phosphorylate a Seryl residue more than once.

### double Modif::m_mono

Value representing the monoisotopic mass of the formula.

### QString Modif::m_name

Name of the chemical modification, like "Acetylation".

### QString Modif::m_targets

String that holds a list of all the target monomers of this modification.

If there are more than one target, the targets (Monomer codes) must be separated by ';' characters.

If any monomer in the polymer chemistry definition might be modified by this Modif object, then, the "*" string can be used to indicate so.

### MsXpS::libXpertMassCore::PolChemDefCstSPtr Modif::mcsp_polChemDef

This variable holds the PolChemDef polymer chemistry definition.

This member allows to root the Modif instance in a chemical context where IsotopicData can be used to calculate masses starting from a Formula, but also where the Monomer instances can be checked for existence when validating the Modif targets, for example.