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

- libXpertMassCore
- CleavageAgent

# MsXpS::libXpertMassCore::CleavageAgent Class

class MsXpS::libXpertMassCore::CleavageAgent

The CleavageAgent class provides a model for specifying aqueous cleavage specifications (patterns) of Polymer Sequences. More...

Header: | `#include <CleavageAgent.hpp>`
Inherits: | QObject
Inherited By: | MsXpS::libXpertMassCore::CleavageConfig

- List of all members, including inherited members
- CleavageAgent is part of Aqueous chemical reactions.

## Public Functions

| CleavageAgent(QObject *parent = nullptr)
| CleavageAgent(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QDomElement &element, int version, QObject *parent = nullptr)
| CleavageAgent(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QString &name = QString(), const QString &pattern = QString(), QObject *parent = nullptr)
| CleavageAgent(const MsXpS::libXpertMassCore::CleavageAgent &other, QObject *parent = nullptr)
virtual | ~CleavageAgent()
QString | formatXmlClaElement(int offset, const QString &indent = Utils::xmlIndentationToken) const
MsXpS::libXpertMassCore::CleavageRuleCstSPtr | getCleavageRuleCstSPtrByName(const QString &name) const
int | getCleavageRuleIndexByName(const QString &name) const
MsXpS::libXpertMassCore::CleavageRuleSPtr | getCleavageRuleSPtrByName(const QString &name) const
MsXpS::libXpertMassCore::CleavageAgentCstSPtr | getFromPolChemDefByName() const
const std::vector<MsXpS::libXpertMassCore::CleavageMotifSPtr> & | getMotifsCstRef() const
std::vector<MsXpS::libXpertMassCore::CleavageMotifSPtr> & | getMotifsRef()
const QString & | getName() const
const QString & | getPattern() const
MsXpS::libXpertMassCore::PolChemDefCstSPtr | getPolchemDefCstSPtr() const
const std::vector<MsXpS::libXpertMassCore::CleavageRuleSPtr> & | getRulesCstRef() const
std::vector<MsXpS::libXpertMassCore::CleavageRuleSPtr> & | getRulesRef()
bool | initialize(const MsXpS::libXpertMassCore::CleavageAgent &other)
MsXpS::libXpertMassCore::Enums::PolChemDefEntityStatus | isKnownByNameInPolChemDef() const
bool | isValid() const
bool | parse()
bool | renderXmlClaElement(const QDomElement &element, int version = 2)
bool | renderXmlClsElement(const QDomElement &element, int version = 1)
void | setName(const QString &name)
void | setPattern(const QString &pattern)
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::CleavageAgent &other) const
bool | operator==(const MsXpS::libXpertMassCore::CleavageAgent &other) const

## Protected Variables

bool | m_isValid
std::vector<MsXpS::libXpertMassCore::CleavageMotifSPtr> | m_motifs
QString | m_name
QString | m_pattern
std::vector<MsXpS::libXpertMassCore::CleavageRuleSPtr> | m_rules
MsXpS::libXpertMassCore::PolChemDefCstSPtr | mcsp_polChemDef

## Detailed Description

Cleavage specifications determine the specificity of cleavage in a polymer sequence using a simple syntax. For example, Trypsin is able to cleave after lysyl and arginyl residues. Its cleavage pattern is thus "Lys/;Arg/". However, it is known that Trypsin fails to cleave after Lys if that monomer is followed by a Prolyl residue, thus the complete cleavage agent specification for Trypsin comprises three cleavage patterns: "Lys/;Arg/;-Lys/Pro".

A cleavage agent specification might not be enough information to determine the manner in which a polymer is cleaved. Cleavage rules might be required to refine the specification. A cleavage agent specification might hold as many cleavage rules as required.

See also CleavageMotif and CleavageRule.

## Member Function Documentation

### `[explicit]` CleavageAgent::CleavageAgent(QObject *parent = nullptr)

Constructs a totally empty CleavageAgent instance

### `[explicit]` CleavageAgent::CleavageAgent(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QDomElement &element, int version, QObject *parent = nullptr)

Constructs a CleavageAgent instance starting from an XML element according to version and a pol_chem_def_csp PolChemDef.

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

Before version 2, the CleavageAgent class was named CleaveSpec and thus the XML element was called <cls>:

This is the current format (FAKE cls):

    <cls>
    <name>CyanogenBromide</name>
    <pattern>M/A</pattern>
    <clr>
    <le-mnm-code>M</le-mnm-code>
    <le-formula>-C1H2S1+O1</le-formula>
    <re-mnm-code>A</re-mnm-code>
    <re-formula>-CH3COOH</re-formula>
    </clr>
    </cls>

After version 2, the CleaveSpec class has been named CleavageAgent and thus the XML element is now called <cla>.The inner structure of the element has not changed.

Depending on the version argument, one function (older) or the other (current) is used to parse the XML element.

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

See also renderXmlClsElement() and renderXmlClaElement().

### `[explicit]` CleavageAgent::CleavageAgent(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QString &name = QString(), const QString &pattern = QString(), QObject *parent = nullptr)

Constructs a CleavageAgent instance.

- pol_chem_def_csp: The polymer chemistry definition.
- name: The name of the CleavageAgent.
- pattern: The pattern of the CleavageAgent, like ("Lys/;Arg/;-Lys/Pro").

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

### `[explicit]` CleavageAgent::CleavageAgent(const MsXpS::libXpertMassCore::CleavageAgent &other, QObject *parent = nullptr)

Constructs a CleavageAgent instance as a copy of other.

The copying of the member containers of CleavageMotif and CleavageRule instances is shallow (only the shared pointers are copied).

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

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

Destructs this CleavageAgent instance.

### QString CleavageAgent::formatXmlClaElement(int offset, const QString &indent = Utils::xmlIndentationToken) const

Formats and returns a string describing this CleavageAgent instance in a format suitable to be used as an XML element.

The XML element is typically used in a polymer chemistry defintion and looks like this:

    <cla>
    <name>CyanogenBromide</name>
    <pattern>M/</pattern>
    <clr>
    <re-mnm-code>M</re-mnm-code>
    <re-formula>-CH2S+O</re-formula>
    </clr>
    </cla>

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::CleavageRuleCstSPtr CleavageAgent::getCleavageRuleCstSPtrByName(const QString &name) const

Returns the CleavageRule from the container that has name.

If no CleavageRule is found, nullptr is returned.

### int CleavageAgent::getCleavageRuleIndexByName(const QString &name) const

Returns the index of the CleavageRule instance named name in the member container of CleavageRule intances. If no CleavageRule by name name is found, -1 is returned.

### MsXpS::libXpertMassCore::CleavageRuleSPtr CleavageAgent::getCleavageRuleSPtrByName(const QString &name) const

Returns the CleavageRule that has name name, or nullptr if not found.

### MsXpS::libXpertMassCore::CleavageAgentCstSPtr CleavageAgent::getFromPolChemDefByName() const

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

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

If there is no PolChemDef available, nullptr is returned.

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

### const std::vector<MsXpS::libXpertMassCore::CleavageMotifSPtr> &CleavageAgent::getMotifsCstRef() const

Returns a const reference to the container of CleavageMotif instances.

### std::vector<MsXpS::libXpertMassCore::CleavageMotifSPtr> &CleavageAgent::getMotifsRef()

Returns a reference to the container of CleavageMotif instances.

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

Returns the name.

### const QString &CleavageAgent::getPattern() const

Returns the pattern.

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

Returns the PolChemDef.

### const std::vector<MsXpS::libXpertMassCore::CleavageRuleSPtr> &CleavageAgent::getRulesCstRef() const

Returns a const reference to the container of CleavageRule instances.

### std::vector<MsXpS::libXpertMassCore::CleavageRuleSPtr> &CleavageAgent::getRulesRef()

Returns a reference to the container of CleavageRule instances.

### bool CleavageAgent::initialize(const MsXpS::libXpertMassCore::CleavageAgent &other)

Initialized this CleavageAgent using other.

After initialization, validity is checked, the result is set to m_isValid and is returned.

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

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

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

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

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

### bool CleavageAgent::isValid() const

Returns the validity status of this instance.

### bool CleavageAgent::parse()

Parses this CleavageAgent instance.

The parsing involves separating the components found in the m_pattern string and making CleavageMotif instances out of them.

Starting from a pattern "Lys/;Arg/;-Lys/Pro", the parsing would first split it into three cleavage site strings:

- "Lys/";
- "Arg/";
- "-Lys/Pro"

Each of these site strings will be deconstructed into motifs, stored in CleavageMotif objects:

- First motif has a code container "[0] Lys", an offset of 1 and is for cleavage;
- Second motif has a code container "[0] Arg", an offset of 1 and is for cleavage;
- Third motif has a code container "[0] Lys, [1] Pro", an offset of 1 and is not for cleavage (mind the '-')

If the pattern string is empty, m_isValid is set to false and false is returned.

Returns true if parsing is successful, false otherwise.

### bool CleavageAgent::renderXmlClaElement(const QDomElement &element, int version = 2)

Parses a cleavage agent XML <cla> element using a versioned function.

The data in the element are validated and if successful they are set to this instance, thus initializing it.

After setting the member data, the instance is validated and the result is set to m_isValid that is returned.

### bool CleavageAgent::renderXmlClsElement(const QDomElement &element, int version = 1)

Parses a cleavage specification XML <cls> element using a versioned function.

The data in the element are validated and if successful they are set to this instance, thus initializing it.

After setting the member data, the instance is validated and the result is set to m_isValid that is returned.

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

Sets the name to name.

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

### void CleavageAgent::setPattern(const QString &pattern)

Sets the pattern.

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

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

Sets the PolChemDef to pol_chem_def_csp.

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

### QString CleavageAgent::toString() const

Returns a string describing this CleavageAgent instance.

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

Validates this CleavageAgent instance setting error messages to error_list_p.

The validation involves checking that:

- The PolChemDef must be available;
- The name is not empty;
- The pattern is nt empty;
- The parsing of the pattern is successful.;
- Each CleavageRule instance (if any) validates successfully.

Returns true if the validation is successful, false otherwise.

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

Returns true if `this` and other are different.

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

Returns true if `this` and other are identical.

Because the CleavageMotifSPtr in m_motifs and the CleavageRuleSPtr in m_rules do not necessarily reference data from the PolChemDef, the comparison of the two instances involves a deep comparison (not a comparison of the pointers themselves).

## Member Variable Documentation

### bool CleavageAgent::m_isValid

This variable holds the validity status of the instance.

### std::vector<MsXpS::libXpertMassCore::CleavageMotifSPtr> CleavageAgent::m_motifs

This variable holds the container of CleavageMotifs that together make the CleavageAgent.

See also CleavageMotif.

### QString CleavageAgent::m_name

This variable holds the name of the CleavageAgent.

### QString CleavageAgent::m_pattern

This variable holds the cleavage pattern, that might comprise more than one CleavageMotif.

See also CleavageMotif and CleavageRule.

### std::vector<MsXpS::libXpertMassCore::CleavageRuleSPtr> CleavageAgent::m_rules

This variable holds the container of CleavageRules that might be requied to refine the CleavageAgent.

See also CleavageRule.

### MsXpS::libXpertMassCore::PolChemDefCstSPtr CleavageAgent::mcsp_polChemDef

This variable holds the PolChemDef polymer chemistry definition.