MsXpS::libXpertMassCore::Formula Class

Member Function Documentation

[explicit invokable] Formula::Formula(QObject *parent = nullptr)

Constructs an uninitialized Formula instance, with parentship set to parent.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

[explicit invokable] Formula::Formula(const QString &formula_string, QObject *parent = nullptr)

Constructs a formula initialized with the formula_string action-formula string, with parentship set to parent.

formula_string does not need to be an action-formula, but it might be an action-formula. This formula gets copied into the m_actionFormula without any processing afterwards.

formula_string might hold a title, as detailed in the Formula class description.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

See also getTitle(), extractTitle(), and removeTitle().

[explicit] Formula::Formula(const QDomElement &element, int version = 1, QObject *parent = nullptr)

Constructs a Formula instance using the XML element according to the version, with parentship set to parent.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

See also renderXmlFormulaElement().

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

Constructs a Formula as a copy of other, setting parentship to parent.

The copy is deep with all the data copied from other to this Formula instance. There is no processing afterwards.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

[virtual noexcept] Formula::~Formula()

Destructs this Formula.

std::size_t Formula::accountFormula(const QString &formula_string, MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double times, bool &ok)

Accounts formula_string into this Formula using isotopic_data_csp as reference isotopic data with times as a compounding factor. The result of the operation is set to ok.

formula_string is converted into a temporary Formula instance and processed according to these steps:

• First validate() is called on the temporary Formula, with storage of the symbol/count data;
• The symbol/count data thus generated is used to update the member m_symbolCountMap map.
• The m_actionFormula is set to the result of elementalComposition().

Returns the size of the member m_symbolCountMap symbol/count map.

MsXpS::libXpertMassCore::Formula &Formula::accountMasses(bool &ok, MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double &mono, double &avg, double times = 1)

Accounts this formula's monoisotopic and average masses into mono and avg, using times as a compounding factor.

The masses corresponding to the member m_actionFormula are calculated first and then the mono and avg parameters are updated by incrementing their value with the calculated values. This incrementation might be compounded by the times factor.

The masses of the member m_actionFormula are computed using data from isotopic_data_csp.

Sets ok to false if the calculation failed, to true otherwise.

Returns a reference to this Formula instance.

See also splitActionParts().

[static] MsXpS::libXpertMassCore::Formula &Formula::accountMasses(MsXpS::libXpertMassCore::Formula &formula, bool &ok, MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double &mono, double &avg, double times = 1)

Accounts formula monoisotopic and average masses into mono and avg, using times as a compounding factor.

The masses corresponding to the formula are first calculated using isotopic_data_csp and then the mono and avg parameters are updated by incrementing their value with the calculated values. This incrementation might be compounded by that times factor.

Sets ok to false if the calculation failed, to true otherwise.

Returns a reference to this Formula instance.

See also splitActionParts().

double Formula::accountSymbolCountPair(const QString &symbol, double count = 1)

Accounts for symbol and corresponding count in the member map.

The m_symbolCountMap relates each atom (chemical element) symbol with its occurrence count as encountered while parsing the member action-formula.

If the symbol was not encountered yet, a new key/value pair is created. Otherwise, the count value is updated.

Returns the new count status for symbol.

double Formula::accountSymbolCountPair(std::map<QString, double> &symbol_count_map, const QString &symbol, double count = 1) const

Accounts for symbol and corresponding count in the symbol_count_map map.

symbol_count_map relates each atom (chemical element symbol) with its occurrence count.

If the symbol was not encountered yet, a new symbol/count pair is created. Otherwise, the pair's count value is updated with count.

Returns the updated count value for symbol.

bool Formula::accountSymbolCounts(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, int times)

Accounts this Formula's action-formula (m_actionFormula) in the member m_symbolCountMap symbol/count container.

Calls splitActionParts() to actually parse m_actionFormula and account its components to m_symbolCountMap. The accounting of the symbol/count pair can be compounded by the times factor.

While splitting the plus and minus sub-formulas of the m_actionFormula, their validity is checked against the reference isotopic data isotopic_data_csp.

This function is used when sequentially accounting many different formulas into the symbol/count map: the member m_actionFormula is set to a new formula string and this function is called again without resetting the symbol/count map, effectively adding formulas onto formulas sequentially.

Returns true if no error was encountered, false otherwise.

See also splitActionParts().

[invokable] QChar Formula::actions() const

Calls actions(const QString &formula) on this Formula's member m_actionFormula. Returns '+' if it only contains "plus" elements or '-' if at least one "minus" element was found.

If m_actionFormula contains no sign at all, then it is considered to contain only '+' elements and the function returns '+'. If at least one element is found associated to a '-', then the "minus" action prevails and the function returns '-'.

See also actions(const QString &formula) and splitActionParts().

[static invokable] QChar Formula::actions(const QString &formula)

Returns '+' if formula only contains "plus" elements or '-' if at least one "minus" element was found.

If formula contains no sign at all, then it is considered to contain only '+' elements and the function returns '+'. If at least one element is found associated to a '-', then the "minus" action prevails and the function returns '-'.

See also actions() and splitActionParts().

[invokable] bool Formula::appendActionFormula(const QString &action_formula)

Appends action_formula to this Formula's member m_actionFormula.

The action_formula string is first stripped of its whitespace with QString::simplified(). Then it is appended to m_actionFormula only if:

• It is not empty (if empty the function does nothing and returns false)
• It passes the checkSyntax() test (if not, the function does nothing and returns false)

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

The function returns false if nothing was changed and true if something was actually appended to m_actionFormula.

[invokable] bool Formula::checkSyntax() const

Returns true if the member action-formula is syntactically valid, false otherwise.

The formula is first stripped of its title (if any), then all the spaces are removed.

MsXpS::libXpertMassCore::Formula::subFormulaRegExp is then used to extract each "plus" and / or "minus" component while checking its syntactic validity.

See also checkSyntax(const QString &formula_string).

[static invokable] bool Formula::checkSyntax(const QString &formula_string)

Returns true if the formula_string action-formula is syntactically valid, false otherwise.

The formula is first stripped of its title (if any), then all the spaces are removed.

MsXpS::libXpertMassCore::Utils::subFormulaRegExp is then used to extract the "plus" and "minus" sub-formulas while checking their syntactic validity.

See also validate().

void Formula::clear()

Clears all the formula member data and set m_isValid to false.

[invokable] MsXpS::libXpertMassCore::Formula *Formula::clone(const MsXpS::libXpertMassCore::Formula &other, QObject *parent = nullptr)

Returns a new heap-allocated Formula that is initialized using other, setting parentship to parent.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

[invokable] QString Formula::elementalComposition(std::vector<std::pair<QString, double>> *symbol_count_pairs_p = nullptr) const

Returns a formula matching the contents of the member m_symbolCountMap symbol/count map.

The returned formula is formatted according to the IUPAC convention about the ordering of the chemical elements: CxxHxxNxxOxxSxxPxx.

The "plus" sub-formula components are output first and the "minus" sub-formula ones after.

If symbol_count_pairs_p is not nullptr, each symbol/count pair is added to it.

[invokable] QString Formula::extractTitle() const

Returns the title from the member action-formula.

The title of a formula is the string, enclosed in double quotes, that is located in front of the actual chemical action-formula. This function removes that title string from the member action-formula using a QRegularExpression.

[invokable] QString Formula::formatXmlFormulaElement(int offset, const QString &indent = Utils::xmlIndentationToken)

Returns a string containing a Formula XML element documenting this Formula instance.

offset and indent define the formatting of the XML element.

A typical XML element looks like this:

<formula>-H2O+CH3COOH</formula>

See also renderXmlFormulaElement().

[invokable] QString Formula::getActionFormula(bool with_title = false) const

Returns the member m_actionFormula action-formula, along with the title if with_title is true.

[invokable] QString Formula::getMinusFormula() const

Returns the m_minusFormula formula.

[invokable] QString Formula::getPlusFormula() const

Returns the m_plusFormula formula.

const std::map<QString, double> &Formula::getSymbolCountMapCstRef() const

Returns a const reference to the member m_symbolCountMap.

[invokable] QString Formula::getTitle() const

Returns the "title" leading component of a formula.

A fully selfdescribed formula might look like this:

"Acetylation"+CH3COOH-H2O

The first string between quotes is called the title.

[invokable] bool Formula::hasNetMinusPart()

Returns true if the member m_minusFormula is not empty, false otherwise.

[invokable] MsXpS::libXpertMassCore::Formula &Formula::initialize(const MsXpS::libXpertMassCore::Formula &other)

Assigns other to this Formula instance and returns a reference to this instance.

Parentship is not modified.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

[virtual] bool Formula::isValid() const

Returns the status of the formula, that is, the result of validate().

int Formula::removeSpaces()

Removes all the space characters from the member action-formula.

Spaces can be placed anywhere in formula for more readability. However, it might be required that these character spaces be removed. This function does just this, using a QRegularExpression.

Returns the number of removed characters.

[invokable] QString Formula::removeTitle()

Removes the title from m_actionFormula and returns it.

The title of a formula is the string, enclosed in double quotes, that is located in front of the actual chemical action-formula. This function removes that title string from the member action-formula using a QRegularExpression.

The caller may use the returned title string to set it to m_title.

See also Formula::extractTitle() and Formula::setTitle().

bool Formula::renderXmlFormulaElement(const QDomElement &element, int version = 1)

Parses a Formula XML element according to version and sets the data to the member m_actionFormula, checking it syntax.

Returns true if the XML element parsing was without error and if the syntax check was successful, false otherwise.

See also checkSyntax() and formatXmlFormulaElement().

void Formula::roundIndices()

Converts this Formula instance's atomic symbol indices to integers.

This function returns immediately if a call to isValid() returns false.

[invokable] void Formula::setActionFormula(const MsXpS::libXpertMassCore::Formula &formula)

Copies formula's action-formula to the member m_actionFormula of this Formula instance.

No other processing is performed afterwards.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

[invokable] void Formula::setActionFormula(const QString &formula)

Copies formula to the member m_actionFormula of this Formula instance.

No other processing is performed afterwards.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

[invokable] void Formula::setTitle(const QString &title)

Sets the title leading component of a formula to title.

A fully self-described formula might look like this:

"Acetylation" +CH3COOH-H2O

The first string between double quotes is called the title.

MsXpS::libXpertMassCore::Formula::SplitResult Formula::splitActionParts(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double times = 1, bool store = false, bool reset = false)

Tells the "plus" ('+') and "minus" ('-') sub-formulas in the member action-formula.

Parses the m_actionFormula action-formula and separates all the minus components of that action-formula from all the plus components. The different sub-formulas are set to their corresponding member (m_minusFormula and m_plusFormula).

This function delegate its work to the other splitActionParts() passing m_plusFormula, m_minusFormula, and m_symbolCountMap as parameters such that this function modifies the contents of this Formula instance.

In all the computations above, reference isotopic data are accessed at isotopic_data_csp. If times is not 1, then that value is used to compound the results of the computations. If store is true, then the results of the computations are stored in this object. If reset is true, then the intermediate computation values and objects are reset.

Returns a Formula::SplitResult result documenting the outcome of the operation.

MsXpS::libXpertMassCore::Formula::SplitResult Formula::splitActionParts(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, QString &plus_formula, QString &minus_formula, std::map<QString, double> &symbol_count_map, double times = 1, bool store = false, bool reset = false) const

Tells the "plus" ('+') and "minus" ('-') sub-formulas in the member action-formula.

Parses the m_actionFormula action-formula and separates all the minus components of that action-formula from all the plus components. The two sub-fomulas are set to plus_formula and minus_formula.

At the end of the split work, each sub-formula (plus_formula and minus_formula) is actually parsed for validity, using the isotopic_data_csp IsotopicData as reference.

If times is not 1, then the accounting of the plus/minus sub-formulas is compounded by this factor.

If store is true, the symbol/count data obtained while parsing of the plus/minus sub-formulas are stored in symbol_count_map.

If reset is true, the symbol/count data in symbol_count_map are reset before the parsing operation. Setting this parameter to false may be useful if the caller needs to "accumulate" the sequential accounting of multiple formulas.

The parsing of the action-formula is performed by performing its deconstruction using Utils::subFormulaRegExp.

Returns a SplitResult value detailing the outcome of the operation.

Because this function does not modify member data, only writing results to the passed variables, it is declared const.

If this function completes successfully, then that validates it successfully (syntax ok, and symbols known to the reference isotopic data), and m_isValid is set to true, otherwise m_isValid is set to false.

double Formula::symbolCount(const QString &symbol) const

Returns the count value associated with key symbol in the member m_symbolCountMap symbol/count member map.

double Formula::totalAtoms() const

Returns the total count of symbols (atoms) in this formula.

The determination is performed by summing up all the count values for all the symbols in the member m_symbolCountMap symbol/count pairs map.

double Formula::totalIsotopes(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp) const

Returns the total count of isotopes in this formula using isotopic_data_csp as the reference isotopic data.

The determination is performed by summing up all the isotope counts for all the symbols keys in the member symbol / count map m_symbolCountMap.

[virtual] bool Formula::validate(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Returns true if the formula validates successfully, false otherwise.

The validation uses the isotopic_data_csp reference data (that cannot be nullptr) and involves:

• Checking that the member action-formula is not empty and has a proper syntax. Returns false otherwise;
• Splitting the action-formula into plus and a minus sub-formulas using splitActionParts()). If that step fails, returns false;
• Verifying that both the plus and the minus formulas are not empty. Returns false otherwise.

If errors are encountered, meaningful messages are stored in error_list_p (is not nullptr and that is not cleared).

If the validation is successful, m_isValid is set to true, otherwise it is set to false.

See also validate(IsotopicDataCstSPtr isotopic_data_csp, bool store, bool reset, ErrorList *error_list_p).

[virtual] bool Formula::validate(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, bool store, bool reset, MsXpS::libXpertMassCore::ErrorList *error_list_p)

Returns true if the formula validates successfully, false otherwise.

The validation uses the isotopic_data_csp reference data (that cannot be nullptr) and involves:

• Checking that the member action-formula is not empty and has a proper syntax. Returns false otherwise;
• Splitting the action-formula into plus and a minus sub-formulas using splitActionParts()). If that step fails, returns false;
• Verifying that both the plus and the minus formulas are not empty. Returns false otherwise.

If errors are encountered, meaningful messages are stored in error_list_p (is not nullptr and that is not cleared).

Member data are updated during the operations.

If the validation is successful, m_isValid is set to true, otherwise it is set to false.

See also validate(IsotopicDataCstSPtr isotopic_data_csp, ErrorList *error_list_p) const.

[virtual] bool Formula::operator!=(const MsXpS::libXpertMassCore::Formula &other) const

Returns true if this Formula and other are different, false otherwise.

Returns the negated result of operator==().

See also operator==().

[virtual] MsXpS::libXpertMassCore::Formula &Formula::operator=(const MsXpS::libXpertMassCore::Formula &other)

Assigns other to this Formula instance and returns a reference to this instance.

The copy is deep with all the data from other being copied into this formula.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

[virtual] bool Formula::operator==(const MsXpS::libXpertMassCore::Formula &other) const

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

The comparison is only performed on the title and action-formula, not on any other member data that actually derive from the processing of the action-formula.

See also operator!=().