Ionizer Class

Member Function Documentation

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

Constructs an Ionizer initialized as an empty object.

The instantiated Ionizer is invalid.

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.

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.

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.

[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).

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.

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

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.

int Ionizer::getNominalCharge() const

Returns the nominal charge.

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.

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.

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.

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.

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.

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.

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.

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.