Formula Class

Member Function Documentation

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

Constructs a Formula instance.

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

Constructs a formula initialized with the formula_string action-formula string.

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

The default status of the Formula (m_isValid) is let to false because the formula cannot be validated without reference isotopic data.

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

Constructs a Formula instance using the XML element according to the version.

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

Constructs a formula as a copy of other.

The copy is deep with all the data copied from other to the new formula. There is no processing afterwards.

[virtual noexcept] Formula::~Formula()

Destructs this formula.

There is nothing to be delete explicitly.

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

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

The formula_string formula is converted into a temporary Formula and processed:

• 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 map.
• The m_actionFormula is set to the result of elementalComposition().

Returns the size of the member symbol/count m_symbolCountMap.

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 action-formula 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 that times factor.

The masses of the member action-formula are computed using data from isotopic_data_csp.

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

Returns this object.

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 the formula monoisotopic and average masses into mono and avg, using times as a compounding factor.

The masses corresponding to the formula 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 that times factor.

The masses of the formula are computed using data from isotopic_data_csp.

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

Returns this object.

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.

The symbol_count_map 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.

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

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

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

While splitting the "plus" and "minus" components of the action-formula, their validity is checked against the reference isotopic data isotopic_data_csp.

This function is used when processively accounting many different formulas into the symbol / count map. The formula is set to a new value and this function is called without resetting the symbol / count map, effectively adding formulas onto formulas sequentially.

Returns true if no error was encountered, false otherwise.

See also splitActionParts() and Polymer::elementalComposition.

[invokable] QChar Formula::actions() const

Calls actions(const QString &formula) on this Formula's action-formula 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 to this formula the action_formula.

The action_formula string is first stripped of its whitespace with QString::simplified(). Then it is appended to the 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)

The status of this Formula is set to false because there was not explicit validation done.

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.

See also checkSyntax(const QString &formula, bool force_count_index).

[static invokable] bool Formula::checkSyntax(const QString &formula_string, bool force_count_index = false)

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

If force_count_index is true, the syntax check accounts for the requirement that all the symbols in the formula must be indexed, even if that symbol's count is 1. This means that H2O would not pass the check, while H2O1 would.

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

void Formula::clear()

Clears all the formula member data.

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

Return a newly allocated Formula that is initialized using other and setting its parent to parent.

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

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

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

The "plus" components are output first and the "minus" components 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.

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

Returns the action formula, along the the title if with_title is true.

[invokable] QString Formula::getPlusFormula() const

Returns the m_plusFormula formula.

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

Returns a const reference to the std::map<QString, double> container that relates chemical symbols with corresponding counts.

[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 "minus" formula component is not empty, false otherwise.

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

Return a reference to this Formula after having initialized it using other.

[invokable] bool Formula::isForceCountIndex() const

Returns true if single atoms should have a count index, false otherwise.

The force count index is set to true, when a formula needs to have atom indices set even if the count for these atoms is 1. For example, H2O1 as compared to H2O.

[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 action-formula checking it syntax.

Returns true if parsing and syntax checking were successful, false otherwise.

See also checkSyntax().

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

Sets the action-formula from formula to this Formula.

The action-formula from formula is copied to this m_actionFormula. Since the new formula was not validated, the status of this formula (m_isValid) is set to false. No other processing is performed afterwards.

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

Sets the action-formula formula to this Formula.

The formula is copied to this m_actionFormula. Since the new formula was not validated, the status of this formula (m_isValid) is set to false. No other processing is performed afterwards.

[invokable] void Formula::setForceCountIndex(bool forceCountIndex)

Sets m_forceCountIndex to forceCountIndex.

When a formula contains a chemical element in a single copy, it is standard practice to omit the count index: H2O is the same as H2O1. If forceCountIndex is true, then the formula has to be in the form H2O1. This is required for some specific calculations. The status (m_isValid) is set to false.

See also isForceCountIndex().

[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" ('-') parts in the member actionformula.

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

This function delegate its work to the other splitActionParts() passing arguments m_plusFormula, m_minusFormula, m_symbolCountMap, such that this function modifies the content of this very object.

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.

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" ('-') parts 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 components 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 formulas is compounded by this factor.

If store is true, the symbol/count data obtained while parsing of the plus/minus action-formula components 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 accounting of the formulas.

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

Returns FormulaSplitResult::FAILURE if the splitting failed, FormulaSplitResult::HAS_PLUS_COMPONENT if at least one of the components of the action-formula was found to be of type plus, FormulaSplitResult::HAS_MINUS_COMPONENT if at least one of the components of the action-formula was found to be of type minus. The result can be an OR'ing of both values (FormulaSplitResult::HAS_BOTH_COMPONENTS) in the m_actionFormula action-formula.

Because this function does not modify member data, by writing the results of the computations 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 symbol / count member map m_symbolCountMap.

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 symbol / count pairs in the member map m_symbolCountMap.

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 and involves:

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

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

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

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

See the other validation function for the validation logic.

This function allows to store in member data the results of the validation process if store is set to true. If reset is true, the member data are first cleared.

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

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

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

Initializes all the member data of this formula by copying to it the data from other.

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

There is no processing afterwards.

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