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

- libXpertMassCore
- Ionizer

# MsXpS::libXpertMassCore::Ionizer Class

class MsXpS::libXpertMassCore::Ionizer

The Ionizer class provides abstractions to ionize analytes. More...

Header: | `#include <Ionizer.hpp>`
Inherits: | QObject

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

## Public Functions

| Ionizer(QObject *parent = nullptr)
| Ionizer(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, QObject *parent = nullptr)
| Ionizer(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, const MsXpS::libXpertMassCore::Formula &formula, int charge, int level, QObject *parent = nullptr)
| Ionizer(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, const QString &formula_string, int charge, int level, QObject *parent = nullptr)
| Ionizer(const MsXpS::libXpertMassCore::Ionizer &other, QObject *parent = nullptr)
int | charge() const
void | clear()
int | currentStateCharge() const
MsXpS::libXpertMassCore::Enums::IonizationOutcome | deionize(double &mono, double &avg) const
void | forceCurrentState(const MsXpS::libXpertMassCore::Formula &formula, int nominal_charge, int level)
void | forceCurrentStateLevel(int level)
QString | formatXmlIonizeRuleElement(int offset, const QString &indent = Utils::xmlIndentationToken)
const MsXpS::libXpertMassCore::Formula & | getCurrentStateFormulaCstRef() const
int | getCurrentStateLevel() const
int | getCurrentStateNominalCharge() const
const MsXpS::libXpertMassCore::Formula & | getFormulaCstRef() const
MsXpS::libXpertMassCore::Formula & | getFormulaRef()
MsXpS::libXpertMassCore::IsotopicDataCstSPtr | getIsotopicDataCstSPtr() const
int | getLevel() const
int | getNominalCharge() const
void | initialize(const MsXpS::libXpertMassCore::Ionizer &other)
MsXpS::libXpertMassCore::Enums::IonizationOutcome | ionize(double &mono, double &avg) const
bool | isCurrentStateValid() const
bool | isIonized() const
bool | isValid() const
MsXpS::libXpertMassCore::Ionizer | makeIonizerWithCurrentStateData()
MsXpS::libXpertMassCore::Enums::IonizationOutcome | molecularMasses(double &mono, double &avg) const
bool | renderXmlIonizeRuleElement(const QDomElement &element)
void | setFormula(const MsXpS::libXpertMassCore::Formula &formula)
void | setFormula(const QString &formula_string)
void | setIsotopicDataCstSPtr(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp)
void | setLevel(int level)
void | setNominalCharge(int nominal_charge)
QString | toString(bool with_title = true) const
bool | validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | validateCurrentState(MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | operator!=(const MsXpS::libXpertMassCore::Ionizer &other) const
MsXpS::libXpertMassCore::Ionizer & | operator=(const MsXpS::libXpertMassCore::Ionizer &other)
bool | operator==(const MsXpS::libXpertMassCore::Ionizer &other) const

## Protected Variables

MsXpS::libXpertMassCore::Formula | m_currentStateFormula
int | m_currentStateLevel
int | m_currentStateNominalCharge
MsXpS::libXpertMassCore::Formula | m_formula
bool | m_isCurrentStateValid
bool | m_isValid
int | m_level
int | m_nominalCharge
MsXpS::libXpertMassCore::IsotopicDataCstSPtr | mcsp_isotopicData

## Detailed Description

Ionizations are chemical reactions that bring a charge (or more charges) to an analyte. In this Ionizer class, that process is modelled along with the idea that a previously ionized analyte might be re-ionized with a different ionization chemistry (that is, either a different ionization agent, or a different ionization nominal charge or a different ionization level).

To provide the basis for re-ionization, the class provides two ionization rules describing the ionization state (present and future) of the analyte managed by the Ionizer:

- one ionization rule (formula, nominal charge, level) for the "current state" of ionization;
- another ionization rule for the "ionization to come", that is the rule that will be applied to the analyte managed by this Ionizer when the ionize() function will be called.

The class data members that describe the current ionization state of the analyte managed by the Ionizer have the "currentState" prefix to their name (eg m_currentStateFormula). The class data members that describe the so-called "ionization-to-come" ionization rule have no prefix associated to their name (eg m_formula).

The ionization chemical reaction is described by the member Formula instances Ionizer::m_formula (ionization to come) and Ionizer::m_currentStateFormula (current state of ionization). The electric charge that is brought by this reaction is described by the members Ionizer::m_nominalCharge and Ionizer::m_currentStateNominalCharge. The ionization level is described by the members Ionizer::m_level and Ionizer::m_currentStateLevel. The ionization level is typically set to the number of ionization reactions, that is, for example, it would be set to 10 for a protein to be ionized ten times by protonation, each protonation event bringing a nominal charge of 1.

An Ionizer like the following, if used to ionize a molecule of Mr 1000

- Formula +H
- Charge 1
- Level 1

would lead to an ion of mass 1001 and of m/z 1001.

In protein chemistry, the ionization reaction is mainly a protonation reaction, which brings a single charge. Thus, the Formula would be "+H" and the charge 1. In MALDI, we would have a single protonation, thus level would be set to 1 by default. In electrospray ionization, more than one ionization reaction occur, and we could have a protein that is 25+, thus having an ionization level of 25, for example.

An Ionizer like the following, if used to ionize a molecule of Mr 1000

- Formula +H
- Charge 1
- Level 4

would lead to an ion of mass 1004 and of m/z 251 (1004 / 4).

An Ionizer like the following, if used to ionize a molecule of Mr 1000

- Formula +Mg (in fact Mg2+)
- Charge 2
- Level 4

would lead to an ion of mass 1000 + (24 * 4) and of m/z 137 = (1096 / 8).

Note: The real nature of the ionization is beared by the Formula (with, for example in protein chemistry, "+H" for protonation and, in nucleic acids chemistry, "-H" for deprotonation).

Thus, an Ionizer is valid if it generates a m/z ratio after ionization of the analyte that is different than the previous (M) and if its member Formula validates successfully. This means that the following should be true:

- The Formula should be valid (that is, should contain at least one symbol (which might have a very small mass, like when the ionization is done by electron gain or loss);
- The charge is >0 (the ionization event should bring one charge, otherwise there is no ionization). To reset the ionization to 0 (that is to deionize the analyte, set the level to 0);
- The level is >= 0 (if the level is 0, then the analyte is considered not ionized);

Note: We do not consider compulsory that the Formula brings a mass difference whatsoever, because some ionizations might not involve heavy mass transfers, like electron gain or electron loss. However, the member Formula must validate successfully and that means that it cannot be empty. In that case, use a zero-sum formula like (-H+H) that has no weight.

The Ionizer class should be used with caution because its internal state conditions heavily the reliability of the ionization calculations. The best way to proceed is to construct the ionizer fully at start and then only use the functional features of the class (ionize(), deionize(), molecularMasses()).

## Member Function Documentation

### `[invokable]` Ionizer::Ionizer(QObject *parent = nullptr)

Constructs an Ionizer initialized as an empty object.

The instantiated Ionizer is invalid.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### Ionizer::Ionizer(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, QObject *parent = nullptr)

Constructs an Ionizer initialized only with the IsotopicData.

The instantiated Ionizer is invalid.

### Ionizer::Ionizer(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, const MsXpS::libXpertMassCore::Formula &formula, int charge, int level, QObject *parent = nullptr)

Constructs an Ionizer initialized with isotopic_data_csp, formula, charge, level.

The current state member data are unitialized and the analyte managed by this Ionizer is thus in an un-ionized state. Instead, if ionize() is called, the ionization is performed using the data passed to this constructor.

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

Note that the validation first checks the ionization-to-come members and then also checks the ionization current state members.

See also validate() and validateCurrentState().

### Ionizer::Ionizer(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, const QString &formula_string, int charge, int level, QObject *parent = nullptr)

Constructs an Ionizer initialized with isotopic_data_csp, formula_string, charge, level.

The current state member data are unitialized and the analyte managed by this Ionizer is thus in an un-ionized state. Instead, if ionize() is called, the ionization is performed using the data passed to this constructor.

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

Note that the validation first checks the ionization-to-come members and then also checks the ionization current state members.

See also validate() and validateCurrentState().

### Ionizer::Ionizer(const MsXpS::libXpertMassCore::Ionizer &other, QObject *parent = nullptr)

Constructs an Ionizer as a copy of other.

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

### `[invokable]` int Ionizer::charge() const

Returns the total charge.

The total charge is the product (m_nominalCharge * m_level). This charge will be brought to the analyte when ionize() gets called.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### void Ionizer::clear()

Resets this instance to default values.

### `[invokable]` int Ionizer::currentStateCharge() const

Returns the last status total charge.

The total charge is the product (m_currentStateNominalCharge * m_currentStateLevel). This current state charge is the charge that was brought to the analyte when ionize() was called previously. It thus reflects the current charge of the analyte managed by this Ionizer.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### MsXpS::libXpertMassCore::Enums::IonizationOutcome Ionizer::deionize(double &mono, double &avg) const

Attempts to deionize the analyte and returns the outcome.

The analyte (of which the masses are passed as modifiable mono and avg arguments) is deionized using m_formula, m_nominalCharge and m_level.

The following logic is applied:

1. If this Ionizable is not ionized, this function does not do anything and returns Enums::IonizationOutcome::UNCHANGED.
2. If this Ionizer is not valid, this function returns Enums::IonizationOutcome::FAILED because it makes no sense to try to change the ionization of an analyte if the Ionizer is invalid.
3. The deionization process is carried out.

If the deionization process leads to masses different to mono and avg, then it is deemed successful and Enums::IonizationOutcome::DEIONIZED is returned, otherwise Enums::IonizationOutcome::UNCHANGED is returned.

### `[invokable]` void Ionizer::forceCurrentState(const MsXpS::libXpertMassCore::Formula &formula, int nominal_charge, int level)

Sets the current state member data.

This is useful when starting from an ionized state (for a Formula, for example) that will require to be ionized later in a different manner. See, for example, in MassXpert3, the MzCalculationDlg::getSrcIonizerData() function.

The three parameters thus describe in full the current ionization status of the analyte managed by this Ionizer:

- formula The formula that describes the current ionization state;
- nominal_charge The charge that is brought by the reaction described in the formula;
- level The count of ionization events to be applied to the analyte managed by this Ionizer instance.

The m_isCurrentStateValid is set to the result of the validation of the current state of this Ionizer.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[invokable]` void Ionizer::forceCurrentStateLevel(int level)

Sets the current state ionization level to level.

This function resets the current state ionization level and is practical to use for setting the analyte managed by this Ionizer to an un-ionized state even if the other members of the current state are valid (the formula and the nominal charged are correctly described).

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### QString Ionizer::formatXmlIonizeRuleElement(int offset, const QString &indent = Utils::xmlIndentationToken)

Formats and returns a string suitable to use as an XML element.

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

The DTD says this: <!ELEMENT ionizerule(formula,charge,level)>

A typical ionization rule element looks like this:

    <ionizerule>
    ~~<formula>+H</formula>
    ~~<charge>1</charge>
    ~~<level>1</level>
    </ionizerule>

offset times the indent string must be used as a lead in the formatting of elements.

See also renderXmlIonizeRuleElement(const QDomElement &element).

### const MsXpS::libXpertMassCore::Formula &Ionizer::getCurrentStateFormulaCstRef() const

Returns a const reference to the current state Formula.

The m_currentStateFormula describes the formula that has been already applied to the analyte as it has already been ionized.

### int Ionizer::getCurrentStateLevel() const

Returns the ionization level.

This ionization level describes the number of times the ionization formula and the nominal charge have been applied when ionize() was called on the managed analyte.

Note: Getter function for property currentStateLevel.

### int Ionizer::getCurrentStateNominalCharge() const

Returns the current state nominal charge.

The m_currentStateNominalCharge member datum describes the charge that was brought by the formula to the analyte when it was ionized (independently from the ionization level).

Note: Getter function for property currentStateNominalCharge.

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

Returns a const reference to the Formula.

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

Returns a reference to the Formula.

### MsXpS::libXpertMassCore::IsotopicDataCstSPtr Ionizer::getIsotopicDataCstSPtr() const

Returns the IsotopicData.

### int Ionizer::getLevel() const

Returns the ionization level.

This ionization level describes the number of times the ionization formula and the nominal charge need to be applied when ionize() gets called on the managed analyte.

Note: Getter function for property level.

### int Ionizer::getNominalCharge() const

Returns the nominal charge.

Note: Getter function for property nominalCharge.

### void Ionizer::initialize(const MsXpS::libXpertMassCore::Ionizer &other)

brief Initializes this Ionizer instance using* other.

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

### MsXpS::libXpertMassCore::Enums::IonizationOutcome Ionizer::ionize(double &mono, double &avg) const

Returns the outcome of the ionization process.

The mono and avg masses are the masses of the analyte to be ionized. These masses are passed as non const because they are modified to become m/z values accounting for the ionization process (or to become Mr values accounting for the deionization process).

The ionization is performed by accounting into mono and avg the formula of the ionization rule compounded by the level of ionization that is required. Then, the resulting masses are divided by the charge (that is the product of m_nominalCharge by m_level), thus becoming the m/z value of the ionized analyte.

If this Ionizer instance's m_isIonized member value is true, the function does not do anything and returns Enums::IonizationOutcome::UNCHANGED.

The modification of mono and avg is "atomic", that it, it occurs only if the ionization is successful and leads to values different than those initially passed to the function.

### bool Ionizer::isCurrentStateValid() const

Returns the validity status of the current state of this Ionizer instance: true if the current state is valid, false otherwise.

Note: Getter function for property isCurrentStateValid.

See also validate().

### bool Ionizer::isIonized() const

Returns the current ionization status.

The analyte managed by this Ionizer is considered ionized if the current state nominal charge multiplied by the ionization level is not 0.

See also currentStateCharge().

### bool Ionizer::isValid() const

Returns the validity status of this instance: true if this Ionizer is valid, false otherwise.

Note: Getter function for property isValid.

See also validateCurrentState() and validate().

### `[invokable]` MsXpS::libXpertMassCore::Ionizer Ionizer::makeIonizerWithCurrentStateData()

Allocates on the stack an Ionizer instance and initializes its ionization-to-come data using the current state data from this Ionizer. The current ionization state of the returned Ionizer instance are reset to nothing, effectively setting the managed analyte to a non-ionized state.

Returns the allocated Ionizer instance.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### MsXpS::libXpertMassCore::Enums::IonizationOutcome Ionizer::molecularMasses(double &mono, double &avg) const

Sets the molecular mass of the analyte of which the masses are passed as modifiable parameters in mono and avg.

The analyte is first deionized (on copy data) and if the deionization process was successful, mono and avg are set to the masses of the deionized analyte (that is, Mr molecular masses).

If the analyte is not ionized, returns Enums::IonizationOutcome::UNCHANGED (and nothing is changed). If the analyte was actually ionized, then if it is first successfully deionized, then the analyte is set to deionized and the mono and avg masses are set to the Mr molecular mass.

### bool Ionizer::renderXmlIonizeRuleElement(const QDomElement &element)

Renders the ionization rule XML element.

The XML element is parsed and the data extracted from the XML data are set to this Ionizer instance.

The DTD says this: <!ELEMENT ionizerule(formula,charge,level)>

A typical ionization rule element looks like this:

    <ionizerule>
    <formula>+H</formula>
    <charge>1</charge>
    <level>1</level>
    </ionizerule>

The caller is reponsible for checking the validity of the IonizeRule prior use.

Returns true if the parsing is successful, false otherwise.

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

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

Sets the Formula to formula.

The m_formula describes the reaction to be applied to an analyte when the ionize() function gets called.

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

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

Sets the Formula to formula_string.

The m_formula describes the reaction to be applied to an analyte when the ionize() function gets called.

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

### void Ionizer::setIsotopicDataCstSPtr(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp)

Sets the IsotopicData to isotopic_data_csp.

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

### void Ionizer::setLevel(int level)

Sets the ionization level to level.

This ionization level describes the number of times the ionization formula and the nominal charge need to be applied when ionize() gets called on the managed analyte.

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

Note: Setter function for property level.

### void Ionizer::setNominalCharge(int nominal_charge)

Sets the nominal charge to nominal_charge.

The m_nominalCharge describes the charge that is brought to the analyte by the m_formula member when ionize() is called.

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

Note: Setter function for property nominalCharge.

### QString Ionizer::toString(bool with_title = true) const

Returns a string holding a textual representation of the member data.

If with_title is true, the member formulas (m_formula and m_currentStateFormula) are output with their title (if any).

### `[invokable]` bool Ionizer::validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Validates this Ionizer, setting any error message to error_list_p.

An Ionizer is valid if the following data for the ionization-to-come:

- The member IsotopicData are available
- The Formula validates successfully (that is, should contain at least one atom (for a zero-mass formula, use "+H-H", for example);
- The nominal charge should be != 0 because otherwise the Ionizer raison d'être is absent.

Further, the current ionization state data are checked and are valid if:

- The member IsotopicData are available
- The Formula validates successfully if it is not empty (that is, should contain at least one atom (for a zero-mass formula, use "+H-H", for example);

Note that both the current state nominal charge and level may be 0 (which is logical if the analyte being managed by this Ionizer is not currently ionized).

If any of the tests above fail, the Ionizer is considered invalid and the validity status (m_isValid) value is set to false; true otherwise.

Returns true if validation succeeded, false otherwise.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also Formula::validate(), validateCurrentState(), and isValid().

### `[invokable]` bool Ionizer::validateCurrentState(MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Validates this Ionizer current state, setting any error message to error_list_p.

An Ionizer has a valid current state if:

- The member IsotopicData are available
- The Formula validates successfully if it is not empty (that is, should contain at least one atom (for a zero-mass formula, use "+H-H", for example);

Note that both the current state nominal charge and level may be 0 (which is logical if the analyte being managed by this Ionizer is not currently ionized).

If any of the tests above fail, the Ionizer is considered as invalid for the current ionization state and the validity status (m_isCurrentStateValid) value is set to false; true otherwise.

Returns true if validation succeeded, false otherwise.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also Formula::validate(), validate(), and isValid().

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

Returns true if this Ionizer is different than other, false otherwise.

Returns the negated result of operator==().

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

Assigns other to this Ionizer.

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

Returns a reference to this ionization rule.

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

Returns true if this Ionizer is identical to other, false otherwise.

Note: The comparison of the IsotopicData is deep, with a true comparison of all the Isotope instances, not only of the shared pointers.

## Member Variable Documentation

### MsXpS::libXpertMassCore::Formula Ionizer::m_currentStateFormula

This variable holds the Formula that was last used to ionize the analyte

This formula is only used when an analyte is being ionized. If this formula and the current state of ionization of the analyte is true, then it is used to first deionize the analyte.

### int Ionizer::m_currentStateLevel

This variable holds the number of times the "ionization-to-come" formula and nominal charge will be applied to the analyte managed by this Ionizer upon next call to ionize().

### int Ionizer::m_currentStateNominalCharge

This variable holds the charge that is currently bore by the analyte when it was last ionized.

### MsXpS::libXpertMassCore::Formula Ionizer::m_formula

This variable holds the Formula that is used to perform the ionization.

For a protonation event, that would be "+H", for example. For a deprotonation event, that would be "-H".

### bool Ionizer::m_isCurrentStateValid

Tells if the current ionization state of the analyte managed by this Ionizer is valid.

See also isValid(), isCurrentStateValid(), validate(), and validateCurrentState().

### bool Ionizer::m_isValid

Tells if this Ionizer is valid, both for the current state and for the ionization-to-come member data.

See also isValid() and validate().

### int Ionizer::m_level

This variable holds the number of times this IonizRule is used to ionize a molecule.

For example, applying this Ionizer to a molecule

- Formula +H
- Charge 1
- Level 4

would protonate it 4 times, with a charge of 4 and an increment in mass of the mass of 4 times 1 proton. The m_level should be construed as "how many times should the ionization reaction (formula / nominal charge) be performed."

### int Ionizer::m_nominalCharge

This variable holds the charge that is brought to the molecule when it is ionized by the Ionizer with an ionization level (m_level) of 1. For a protonation, that would be 1.

### MsXpS::libXpertMassCore::IsotopicDataCstSPtr Ionizer::mcsp_isotopicData

This variable holds the IsotopicData required to actually account for the ionization formula.

See also m_currentStateFormula and m_formula.