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

- libXpertMassCore
- Monomer

# MsXpS::libXpertMassCore::Monomer Class

class MsXpS::libXpertMassCore::Monomer

The Monomer class provides abstractions to work with monomers. More...

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

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

## Public Functions

| Monomer(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QDomElement &element, int version)
| Monomer(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp = nullptr, const QString &name = QString(), const QString &code = QString(), const QString &formula_string = QString(), double mono = 0.0, double avg = 0.0)
| Monomer(const MsXpS::libXpertMassCore::Monomer &other)
virtual | ~Monomer()
const MsXpS::libXpertMassCore::Monomer & | accountMasses(double &mono, double &avg, int times = 1) const
const MsXpS::libXpertMassCore::Monomer & | accountMasses(double *mono_p = nullptr, double *avg_p = nullptr, int times = 1) const
bool | calculateMasses(const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp, MsXpS::libXpertMassCore::Enums::ChemicalEntity monomer_chemical_entities = Enums::ChemicalEntity::NONE)
MsXpS::libXpertMassCore::Monomer & | calculateMasses(bool &ok, const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp, MsXpS::libXpertMassCore::Enums::ChemicalEntity monomer_chemical_entities = Enums::ChemicalEntity::NONE)
bool | calculateMasses(const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp, double &mono, double &avg, MsXpS::libXpertMassCore::Enums::ChemicalEntity monomer_chemical_entities = Enums::ChemicalEntity::NONE) const
bool | checkCodeSyntax(int code_length = -1) const
void | clear()
int | countModifsByName(const QString &modif_name)
QString | formatXmlMnmElement(int offset, const QString &indent = Utils::xmlIndentationToken) const
QString | formatXmlMonomerElement(int offset, const QString &indent = Utils::xmlIndentationToken) const
std::vector<QString> | getAllModifUuids() const
QString | getCode() const
MsXpS::libXpertMassCore::MonomerSPtr | getFromPolChemDefByCode() const
MsXpS::libXpertMassCore::MonomerSPtr | getFromPolChemDefByName() const
double | getMass(MsXpS::libXpertMassCore::Enums::MassType mass_type) const
MsXpS::libXpertMassCore::ModifSPtr | getModifForUuid(const QString &uuid) const
const std::vector<MsXpS::libXpertMassCore::ModifSPtr> & | getModifsCstRef() const
QString | getName() const
const MsXpS::libXpertMassCore::PolChemDefCstSPtr & | getPolChemDefCstSPtr() const
QString | getUuidForModif(const MsXpS::libXpertMassCore::ModifSPtr &modif_sp) const
bool | hasModif(const MsXpS::libXpertMassCore::ModifSPtr &modif_sp) const
bool | hasUuid(const MsXpS::libXpertMassCore::ModifSPtr &modif_sp) const
MsXpS::libXpertMassCore::Enums::PolChemDefEntityStatus | isKnownByCodeInPolChemDef() const
MsXpS::libXpertMassCore::Enums::PolChemDefEntityStatus | isKnownByNameInPolChemDef() const
bool | isModified() const
bool | isValid() const
std::vector<QString> | modifNamesInOrder() const
QString | modify(const MsXpS::libXpertMassCore::Modif &modif, bool override, MsXpS::libXpertMassCore::ErrorList *error_list_p)
QString | modify(const QString &modif_name, bool override, MsXpS::libXpertMassCore::ErrorList *error_list_p)
bool | renderXmlMnmElement(const QDomElement &element, int version)
bool | renderXmlMonomerElement(const QDomElement &element, int version)
void | setCode(const QString &code)
void | setFormula(const QString &formula_string)
void | setName(const QString &name)
void | setPolChemDefCstSPtr(MsXpS::libXpertMassCore::PolChemDefCstSPtr &pol_chem_def_csp)
QString | storeModif(const MsXpS::libXpertMassCore::Modif &modif)
QString | storeModif(const MsXpS::libXpertMassCore::ModifSPtr &modif_sp)
QString | toString() const
bool | unmodify()
bool | unmodify(const QString &uuid)
bool | validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | operator!=(const MsXpS::libXpertMassCore::Monomer &other) const
MsXpS::libXpertMassCore::Monomer & | operator=(const MsXpS::libXpertMassCore::Monomer &other)
bool | operator==(const MsXpS::libXpertMassCore::Monomer &other) const

## Protected Variables

QString | m_code
QString | m_formula
bool | m_isValid
std::vector<MsXpS::libXpertMassCore::ModifSPtr> | m_modifs
QString | m_name
MsXpS::libXpertMassCore::PolChemDefCstSPtr | mcsp_polChemDef

## Related Non-Members

| MonomerCstRPtr
| MonomerCstSPtr
| MonomerCstUPtr
| MonomerCstWPtr
| MonomerRPtr
| MonomerSPtr
| MonomerUPtr
| MonomerWPtr
| UuidMonomerCstWPtrPair

## Detailed Description

In libmass, a momomer is an entity that is part of a polymer chemistry definition. A monomer models a chemical entity that is part of a polymer.

In protein chemistry, that would be a residue, that is, an amino-acid that has been polymerized into a residue chain (that is, a protein, or a peptide). The chemical reaction that polymerizez an amino acid into an elongating protein structure is a condensation, with loss of H2O from the amino acid to actually lead to a what is called a residue of a monomer, or for short a residue.

Note: The monomer, that is partly defined by its formula, has the formula of the residue, not of the amino acid. This is always true, whatever the polymer chemistry definition at hand: protein, saccharide, nucleic acid.

## Member Function Documentation

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

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

This is the current format:

    <mnm>
    <name>Glycine</name>
    <code>G</code>
    <formula>C2H3N1O1</formula>
    </mnm>

### Monomer::Monomer(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp = nullptr, const QString &name = QString(), const QString &code = QString(), const QString &formula_string = QString(), double mono = 0.0, double avg = 0.0)

Constructs a monomer with its member data set to name, code, formula_string, The pol_chem_def_csp and both masses mono and avg.

The member m_isValid validity status is set to the result of this Monomer validation.

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

Constructs a monomer as a copy of other.

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

Destroys the monomer.

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

Increases mono and avg by the corresponding member masses first compounded by times.

Returns true.

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

Increases mono_p and avg_p by the corresponding member masses first compounded by times.

Returns true.

### bool Monomer::calculateMasses(const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp, MsXpS::libXpertMassCore::Enums::ChemicalEntity monomer_chemical_entities = Enums::ChemicalEntity::NONE)

Calculates this monomer's monoisotopic and avg masses.

The calculation is performed by computing the masses of this monomer's formula, accounting or not the entities described by monomer_chemical_entities.

The reference data for the computations are accessed at isotopic_data_csp.

Returns true if the calculations were successful, false otherwise.

See also Formula::accountMasses().

### MsXpS::libXpertMassCore::Monomer &Monomer::calculateMasses(bool &ok, const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp, MsXpS::libXpertMassCore::Enums::ChemicalEntity monomer_chemical_entities = Enums::ChemicalEntity::NONE)

Calculates this monomer's monoisotopic and avg masses.

The calculation is performed by computing the masses of this monomer's formula.

If monomer_chemical_entities & MONOMER_CHEMENT_MODIF is true, then the masses are updated to account for the mass of modifications.

Set ok to true if the calculations were successful, false otherwise.

Returns this object.

See also Formula::accountMasses().

### bool Monomer::calculateMasses(const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp, double &mono, double &avg, MsXpS::libXpertMassCore::Enums::ChemicalEntity monomer_chemical_entities = Enums::ChemicalEntity::NONE) const

Calculates this monomer's monoisotopic and avg masses and sets the results to mono and avg.

The calculation is performed by computing the masses of this monomer's formula, accounting the chemical entities defined by monomer_chemical_entities.

The calculations are performed using reference data in isotopic_data_csp.

Returns true if the calculations were successful, false otherwise.

See also Formula::accountMasses().

### bool Monomer::checkCodeSyntax(int code_length = -1) const

Checks the code's syntactic validity.

If code_length is not -1, then that length is used for the check. Otherwise, the length from the polymer chemistry definition (if available) is used.

The monomer code is verified and has to verify these criteria:

- It must be non-empty
- Its character length has to be less or equal to the code length parameter in the polymer chemistry definition (see PolChemDef::m_codeLength)
- The first character is uppercase
- All the remaining characters are lowercase

Returns true if the code syntax checked successfully, false otherwise.

See also validate().

### void Monomer::clear()

Clears all the data of the Monomer instance.

### int Monomer::countModifsByName(const QString &modif_name)

Returns the count of modifications by name modif_name in this monomer.

### QString Monomer::formatXmlMnmElement(int offset, const QString &indent = Utils::xmlIndentationToken) const

Formats this monomer's data as a string suitable to be used as an XML element in the polymer chemistry definition.

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

    <monomers>
    <mnm>
    <name>Glycine</name>
    <code>G</code>
    <formula>C2H3N1O1</formula>
    </mnm>

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.

### QString Monomer::formatXmlMonomerElement(int offset, const QString &indent = Utils::xmlIndentationToken) const

Formats a string suitable to be used as an XML element in a polymer sequence file.

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

    <monomer>
    <code>S</code>
    <prop>
    <name>MODIF</name>
    <data>Phosphorylation</data>
    </prop>
    <prop>
    <name>COMMENT</name>
    <data>Phosphorylation is only partial</data>
    </prop>
    </monomer>

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.

### std::vector<QString> Monomer::getAllModifUuids() const

Returns a container of QString instances that correspond to the UUID strings that identify all the Modif instances involved in this Monomer.

If no Modif is found, an empty container is returned.

### QString Monomer::getCode() const

Returns the code

### MsXpS::libXpertMassCore::MonomerSPtr Monomer::getFromPolChemDefByCode() const

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

The key to search the Monomer is this instance's member code.

If there is no PolChemDef available, nullptr is returned.

If no Monomer instance is found by this instance's code, nullptr is returned.

### MsXpS::libXpertMassCore::MonomerSPtr Monomer::getFromPolChemDefByName() const

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

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

If there is no PolChemDef available, nullptr is returned.

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

### double Monomer::getMass(MsXpS::libXpertMassCore::Enums::MassType mass_type) const

Returns the mass of the type defined by mass_type.

### MsXpS::libXpertMassCore::ModifSPtr Monomer::getModifForUuid(const QString &uuid) const

Returns the Monomer instance pointer in the member container that is associated to the uuid Uuid string.

If no such Monomer instance pointer is found, nullptr is returned.

### const std::vector<MsXpS::libXpertMassCore::ModifSPtr> &Monomer::getModifsCstRef() const

Returns the container of Modif instances that modify this Monomer.

### QString Monomer::getName() const

Returns the name.

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

Returns the polymer chemistry definition.

### QString Monomer::getUuidForModif(const MsXpS::libXpertMassCore::ModifSPtr &modif_sp) const

Returns the UUID string identifying modif_sp in the member container.

If no such Modif is found, an empty string is returned.

### bool Monomer::hasModif(const MsXpS::libXpertMassCore::ModifSPtr &modif_sp) const

Returns true if modif_sp was found in the member container of Modif instances, false otherwise.

### bool Monomer::hasUuid(const MsXpS::libXpertMassCore::ModifSPtr &modif_sp) const

Returns true if modif_sp was found in the member container of Uuid-Modif pairs, false otherwise.

### MsXpS::libXpertMassCore::Enums::PolChemDefEntityStatus Monomer::isKnownByCodeInPolChemDef() const

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

The key to search the Monomer is this instance's member code.

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

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

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

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

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

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

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

### bool Monomer::isModified() const

Returns true if this monomer has at least one modification, false otherwise.

### bool Monomer::isValid() const

Returns the validity status of this Monomer.

See also validate().

### std::vector<QString> Monomer::modifNamesInOrder() const

Returns the list of Modif names in the same order as the Modif instances are stored in the member container.

### QString Monomer::modify(const MsXpS::libXpertMassCore::Modif &modif, bool override, MsXpS::libXpertMassCore::ErrorList *error_list_p)

Modifies this monomer using modif.

These two verifications that are done:

- This monomer must be a target of modif;
- The count of modif modifications in this monomer must be at most the authorized count - 1, to accomodate this new modification [see Modif::maxCount()].

The two restrictions above can be overridden by setting override to true.

If errors are encountered, these are reported as strings in error_list_p.

Returns a string with the Uuid of the allocated Modif instance.

### QString Monomer::modify(const QString &modif_name, bool override, MsXpS::libXpertMassCore::ErrorList *error_list_p)

Modifies this monomer using modif_name.

modif_name is used to find a Modif instance in the polymer chemistry definition.

If such a Modif is found, it is used to modify this Monomer.

Returns a string with the Uuid of the allocated Modif instance.

### bool Monomer::renderXmlMnmElement(const QDomElement &element, int version)

Parses the monomer XML element specifically for version.

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

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

    <monomers>
    <mnm>
    <name>Glycine</name>
    <code>G</code>
    <formula>C2H3N1O1</formula>
    </mnm>
    <mnm>
    <name>Alanine</name>
    <code>A</code>
    <formula>C3H5N1O1</formula>
    </mnm>

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

See also validate().

### bool Monomer::renderXmlMonomerElement(const QDomElement &element, int version)

Parses into this monomer the XML monomer element passed as argument.

The XML element comes from a polymer sequence file, where the monomer is singled out (not in a sequence string) because it might be modified, like this:

    <monomer>
    <code>S</code>
    <mdf>
    <name>Phosphorylation</name>
    <formula>H1O3P1</formula>
    <targets>*</targets>
    <maxcount>1</maxcount>
    </mdf>
    </monomer>
    <codes>GRKASGSSPTSPINADKVENEDAFLEEVAEEKPHVKPYFTKTILDMEVVEGSAARFDCKIEGYPDPEVM</codes>
    <monomer>
    <code>W</code>
    <mdf>
    <name>Oxidation</name>
    <formula>O1</formula>
    <targets>*</targets>
    <maxcount>1</maxcount>
    </mdf>
    </monomer>
    <codes>YKDDQPVKESRHFQIDYDEEGNCSLTISEVCGDDDAKYTCKAVNSLGEATCTAELLVETMGKEGEGEGEGEEDEEEEEE</codes>

version indicates the format version of this XML element.

As soon as the monomer code is known, while parsing the element, the corresponding monomer is searched in the list of monomers in the member polymer chemistry definition (`mcsp_polChemDef`). Then, the found monomer is copied into `this` monomer so that both monomers are identical, effectively initializing this monomer to the monomer described by the element.

If the element contains one or more `mdf` modifications, these modifications are allocated as Modif's and validated. If these modifications validate successfully, they are appended to this monomer's list of modifications.

Returns true if initialization of his monomer with the contents of element succeeded, false otherwise.

See also formatXmlMonomerElement(int offset, const QString &indent).

### void Monomer::setCode(const QString &code)

Sets the code to code

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

Sets the formula to formula_string.

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

Sets the name.

### void Monomer::setPolChemDefCstSPtr(MsXpS::libXpertMassCore::PolChemDefCstSPtr &pol_chem_def_csp)

Sets the polymer chemistry definition to pol_chem_def_csp.

### QString Monomer::storeModif(const MsXpS::libXpertMassCore::Modif &modif)

Stores the Modif instance modif in the member container.

The modif is used to craft a ModifSPtr that is stored.

Returns the Uuid string associated to the stored Modif.

### QString Monomer::storeModif(const MsXpS::libXpertMassCore::ModifSPtr &modif_sp)

Stores the Modif instance modif_sp pointer in the member container.

The modif_sp is stored as is, without duplication.

Returns the Uuid string associated to the stored Modif.

### QString Monomer::toString() const

Returns a text string representing this Monomer instance.

### bool Monomer::unmodify()

Removes all the modification from this monomer.

Returns true if at least one Modif instance was removed, false if this Monomer instance was not modified.

### bool Monomer::unmodify(const QString &uuid)

Removes from this monomer the Modif instance tagged using the Uuid uuid string.

Returns true if the unmodification was actually performed, false otherwise.

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

Returns true if this monomer is valid, false otherwise.

Validation of the monomer occurs if:

- Its name is not empty
- Its code is not empty and its syntax is correct
- Its formula validates
- Its modifications (if any) validate

If errors are encountered, describing message are stored in error_list_p.

See also checkCodeSyntax().

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

Returns true if `this` monomer and other differ, false otherwise.

Returns the negated result of operator==(other).

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

Assigns other's member data to this monomer.

The copy is deep, in particular with the mpa_modifList being copied.

Returns a reference to this monomer.

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

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

The comparison involves also the comparison of the Modif objects in mpa_modifList.

## Member Variable Documentation

### QString Monomer::m_code

This variable holds the code of the monomer, like K for lysine, A for adenine.

### QString Monomer::m_formula

This variable holds the formula of the monomer.

### bool Monomer::m_isValid

This variable holds the validity status of the Monomer.

### std::vector<MsXpS::libXpertMassCore::ModifSPtr> Monomer::m_modifs

This variable holds the container of Modif instances that are involved in the modification of this Monomer.

The Modif pointers stored in the m_modifs member are ModifSPtr pointers.

### QString Monomer::m_name

This variable holds the name of the monomer, like Lysine, Adenine.

### MsXpS::libXpertMassCore::PolChemDefCstSPtr Monomer::mcsp_polChemDef

This variable holds the polymer chemistry definition that is the context in which the Monomer instance exists.

## Related Non-Members

### MonomerCstRPtr

Synonym for const Monomer *.

### `[alias]` MonomerCstSPtr

Synonym for std::shared_ptr<const Monomer>.

### MonomerCstUPtr

Synonym for std::unique_ptr<const Monomer>.

### MonomerCstWPtr

Synonym for std::weak_ptr<const Monomer>.

### MonomerRPtr

Synonym for Monomer *.

### `[alias]` MonomerSPtr

Synonym for std::shared_ptr<Monomer>.

### MonomerUPtr

Synonym for std::unique_ptr<Monomer>.

### MonomerWPtr

Synonym for std::weak_ptr<Monomer>.

### `[alias]` UuidMonomerCstWPtrPair

Synonym for std::pair<QString, MonomerCstWPtr> items.

These pairs are used to store a unique identifier (Uuid) string related to a std::shared_ptr<const Monomer> type. This kind of pair is used in a container in the CrossLink class. The fact that the std::shared_ptr is converted to a std::weak_ptr is interesting because the item in the pair will not increase the reference count.