IsotopicData Class

Member Function Documentation

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

Constructs the IsotopicData.

The instance will have empty member data.

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

Constructs the IsotopicData as a copy of other.

This is a deep copy with all the data in the containers copied from other to this IsotopicData.

[virtual noexcept] IsotopicData::~IsotopicData()

Destructs the IsotopicData.

Nothing is explicitely deleted in the destructor.

[invokable] void IsotopicData::appendNewIsotope(MsXpS::libXpertMassCore::IsotopeQSPtr isotope_qsp, bool update_maps = true)

Appends a new IsotopeQSPtr to this IsotopicData.

isotope_qsp The new isotope to be added to this collection. The isotope is added to the end of the collection using

m_isotopes.push_back(isotope_qsp);

Each time a new isotope is added to this collection, the chemical signification of the corresponding chemical element changes at heart. It might thus be required that the data in the two m_symbolMonoMassMap and m_symbolAvgMassMap maps be recalculated.

update_maps Tells if the m_symbolMonoMassMap and m_symbolAvgMassMap need to be updated with the new collection of isotopes.

See also updateMassMaps() and appendNewIsotopes().

[invokable] void IsotopicData::appendNewIsotopes(const QList<MsXpS::libXpertMassCore::IsotopeQSPtr> &isotopes, bool update_maps = true)

Appends a collection of new IsotopeQSPtr to this IsotopicData.

isotopes The collection (<vector>) of new isotopes to be added to this collection. The isotope is added to the end of the collection using

m_isotopes.insert(m_isotopes.end(), isotopes.begin(), isotopes.end());

Each time new isotopes are added to this collection, the chemical signification of all the corresponding chemical elements changes at heart. It might thus be required that the data in the two m_symbolMonoMassMap and m_symbolAvgMassMap maps be recalculated.

Internally, this function calls <vector>.insert() to append all the isotopes in isotopes to the end of m_isotopes.

update_maps Tells if the m_symbolMonoMassMap and m_symbolAvgMassMap need to be updated with the new collection of isotopes.

See also updateMassMaps() and appendNewIsotope().

void IsotopicData::clear()

Clears (empties) all the containers in this collection, essentially resetting it completely.

These three containers are cleared:

• m_isotopes
• m_symbolMonoMassMap
• m_symbolAvgMassMap

See also clearSymbolMassMaps().

void IsotopicData::clearSymbolMassMaps()

Clears (empties) the symbol/mass maps only, not the vector if Isotope instances.

These two containers are cleared:

• m_symbolMonoMassMap
• m_symbolAvgMassMap

[invokable] double IsotopicData::computeAvgMass(MsXpS::libXpertMassCore::IsotopeListCstIteratorPair iter_pair, MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Compute the average mass for isotopes contained in the iter_pair iterator range.

iter_pair pair of [begin – end[ iterators to the isotopes in this collection

error_list_p vector of strings in which to store error messages

There are no sanity checks performed. The iterator pair should hold two iterator values that frame isotopes of the same chemical element.

The average mass is computed on the basis of the isotopes contained in the [iter_pair .first – iter_pair .second[ range.

Returns 0 if the first member of iter_pair is the collection's end iterator, the average mass otherwise.

[invokable] bool IsotopicData::containsName(const QString &name, int &count) const

Returns true if the collection contains at least one isotope of element name, false otherwise.

If count is not nullptr, its value is set to the count of isotopes of name element.

[invokable] bool IsotopicData::containsSymbol(const QString &symbol, int &count) const

Returns true if the collection contains at least one isotope of symbol, false otherwise.

If count is not nullptr, its value is set to the count of isotopes of symbol or unchanged if no isotopes by symbol were found.

MsXpS::libXpertMassCore::IsotopeListCstIterator IsotopicData::eraseIsotopes(qsizetype begin_index, qsizetype end_index, bool update_maps = true)

Removes the isotopes located between begin_index and end_index.

The removed isotopes are contained inclusively between the two indices passed as parameters.

Each time isotopes are removed from this collection, the chemical signification of the corresponding chemical elements changes at heart. It might thus be required that the data in the two m_symbolMonoMassMap and m_symbolAvgMassMap maps be recalculated.

update_maps Tells if the m_symbolMonoMassMap and m_symbolAvgMassMap need to be updated with the new collection of isotopes.

Returns an iterator to the end of this collection if either begin_index is out of bounds or this collection is empty. Otherwise, returns an iterator to the collection at the position below the last removed item.

[invokable] double IsotopicData::getAvgMassBySymbol(const QString &symbol, bool &ok) const

Returns the average mass of symbol.

The returned mass is found as the value for key symbol in m_symbolAvgMassMap. If ok is not nullptr, it is set to true.

If the symbol is not found, 0 is returned and ok is set to false if ok is not nullptr.

[invokable] double IsotopicData::getCumulatedProbabilities(MsXpS::libXpertMassCore::IsotopeListCstIteratorPair iter_pair, MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Returns the sum of the probabilities of all the isotopes in the iter_pair range of iterators.

The range of isotopes is defined by iter_pair, that is [ iter_pair .first – iter_pair .second [.

If errors are encountered, these are appended to error_list_p.

[invokable] double IsotopicData::getCumulatedProbabilitiesBySymbol(const QString &symbol, MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Returns the sum of the probabilities of all the isotopes of symbol.

If errors occur, they will be described as strings appended in error_list_p.

[invokable] qsizetype IsotopicData::getIsotopeCountBySymbol(const QString &symbol) const

Returns the count of isotopes of symbol.

const QList<QSharedPointer<MsXpS::libXpertMassCore::Isotope>> &IsotopicData::getIsotopes() const

Returns a constant reference to the container of MsXpS::libXpertMassCore::Isotopes.

MsXpS::libXpertMassCore::IsotopeListCstIteratorPair IsotopicData::getIsotopesByName(const QString &name) const

Returns a range of iterators framing the isotopes of element name.

If name is empty, the iterators are set to be end() of the Isotopes collection. The returned pair of iterators frame the isotopes of name as a [begin,end[ pair of iterators.

MsXpS::libXpertMassCore::IsotopeListCstIteratorPair IsotopicData::getIsotopesBySymbol(const QString &symbol) const

Returns a range of iterators framing the isotopes of symbol.

If symbol is empty, the iterators are set to be end() of the Isotopes collection. The returned pair of iterators frame the isotopes of symbol as a [begin,end[ pair of iterators.

[invokable] double IsotopicData::getMonoMass(MsXpS::libXpertMassCore::IsotopeListCstIteratorPair iter_pair, MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Returns the mass of the most abundant isotope in a range of isotopes.

The range of isotopes is defined by iter_pair, that is [ iter_pair .first – iter_pair .second [.

If errors are encountered, these are appended to error_list_p.

For all the common chemical elements found in organic substances, the monoisotopic mass is the mass of the most abundant isotope which happens to be also the lightest isotope. However that is not true for *all* the chemical elements. We thus need to iterate in the isotopes of each symbol in the vector of isotopes and record the mass of the isotope that is most abundant.

[invokable] double IsotopicData::getMonoMassBySymbol(const QString &symbol, bool &ok) const

Returns the monoisotopic mass for element of symbol.

Returns 0 if symbol was not found in this Isotope collection and sets ok to false if ok is not nullptr; returns the monoisotopic mass for element symbol otherwise and sets ok to true if ok is not nullptr.

qsizetype IsotopicData::getUniqueSymbolsCount() const

Returns the count of unique symbols.

std::vector<QString> IsotopicData::getUniqueSymbolsInOriginalOrder() const

Returns all the unique symbols from the collection as they are stored.

[invokable] bool IsotopicData::insertNewIsotope(MsXpS::libXpertMassCore::IsotopeQSPtr isotope_qsp, qsizetype index, bool update_maps = true)

Inserts a new IsotopeQSPtr to this IsotopicData at index index.

isotope_qsp The new isotope to be inserted in this collection.

If index is out of bounds or this collection is empty, the isotope is appended to this collection. Otherwise, the isotope is inserted at the requested index, which means that the new isotope displaces to the bottom (aka back) the isotope currently at index.

Each time a new isotope is added to this collection, the chemical signification of the corresponding chemical element changes at heart. It might thus be required that the data in the two m_symbolMonoMassMap and m_symbolAvgMassMap maps be recalculated.

update_maps Tells if the m_symbolMonoMassMap and m_symbolAvgMassMap need to be updated with the new collection of isotopes.

Returns true if the iterator at the inserted position is not m_isotopes.end().

See also updateMassMaps(), appendNewIsotope(), and appendNewIsotopes().

[invokable] bool IsotopicData::isMonoMassIsotope(MsXpS::libXpertMassCore::IsotopeCstQSPtr isotope_cqsp)

Returns true if the isotope_cqsp is isotope of its symbol having the greatest probability, false otherwise.

bool IsotopicData::isValid()

Returns the validity status of this IsotopicData instance.

See also validate(), validateBySymbol(), and validateAllBySymbol().

[invokable] QString IsotopicData::isotopesAsStringBySymbol(const QString &symbol) const

Returns a string containing a stanza describing each isotope of symbol.

See also Isotope::toString and Isotope::getMass.

void IsotopicData::replace(MsXpS::libXpertMassCore::IsotopeQSPtr old_isotope_sp, MsXpS::libXpertMassCore::IsotopeQSPtr new_isotope_sp)

Replaces old_isotope_sp by new_isotope_sp in this collection.

qsizetype IsotopicData::size() const

Returns the count of isotopes in the collection.

[invokable] std::size_t IsotopicData::updateAvgMassMap()

Recalculates the average mass of all the chemical elements in this collection of isotopes.

This function is generally called by default by all the functions that add new isotopes to this collection [via updateMassMaps()].

First, a list of all the unique element symbols in this collection is crafted. Then for each symbol in that list, updateAvgMassMap(symbol) is called.

Returns the number of updated symbols, that is, the unique symbol count in this collection.

See also updateMonoMassMap(const QString &symbol) and updateMassMaps().

[invokable] bool IsotopicData::updateAvgMassMap(const QString &symbol)

Recalculates the average mass of the chemical element specified by symbol.

For the set of isotopes corresponding to symbol, compute the average mass and set it in m_symbolAvgMassMap as the value for key symbol.

Returns true if the map pair was actually inserted in m_symbolAvgMassMap or false if the average mass value was set to an already existing key.

See also updateMonoMassMap(const QString &symbol), updateMonoMassMap(), updateAvgMassMap(const QString &symbol), and updateMassMaps().

[invokable] std::size_t IsotopicData::updateMassMaps()

Update the monoisotopic and average symbol-mass maps for all the symbols in the collection.

This function is typically called each time new isotopes are added to this collection.

Returns the count of updated symbols, that is, the unique symbol count in this collection.

See also updateMonoMassMap() and updateAvgMassMap().

[invokable] void IsotopicData::updateMassMaps(const QString &symbol)

Update the monoisotopic and average symbol-mass maps only for symbol.

See also updateMonoMassMap(const QString &symbol) and updateAvgMassMap(const QString &symbol).

[invokable] std::size_t IsotopicData::updateMonoMassMap()

Redefines the monoisotopic mass of all the chemical elements in this collection of isotopes.

This function is generally called by default by all the functions that add new isotopes to this collection [via updateMassMaps()].

First, a list of all the unique element symbols in this collection is crafted. Then for each symbol in that list, updateMonoMassMap(symbol) is called.

Returns the number of updated symbols, that is, the unique symbol count in this collection.

See also updateMonoMassMap(const QString &symbol) and updateMassMaps().

[invokable] bool IsotopicData::updateMonoMassMap(const QString &symbol)

Redefines the monoisotopic mass of the chemical element specified by symbol.

For the set of isotopes corresponding to symbol, set the most abundant isotope's mass as the value for key symbol in m_symbolMonoMassMap.

Returns true if the map pair was actually inserted in m_symbolMonoMassMap or false if the monoisotopic mass value was set to an existing key.

bool IsotopicData::validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Validates this Isotope collection.

The validation involves iterating in the whole collection and for each item in it invoke its Isotope::validate(). If errors occurred during these validations, they are reported as strings in error_list_p.

Return true if no error was encountered, false otherwise.

bool IsotopicData::validateAllBySymbol(MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Validates all the isotopes of the collection.

The validation of the Isotopes is performed by grouping them by symbol. See validateBySymbol().

Encountered errors are stored in error_list_p.

Returns true if all the Isotopes validated successfully, false otherwise.

See also validateBySymbol(), validate(), and getCumulatedProbabilitiesBySymbol().

bool IsotopicData::validateBySymbol(const QString &symbol, MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Validates the Isotopes of symbol in this collection.

This function is more powerful than IsotopicData::validate() because it actually verifies the integrity of the data symbol-wise. For example, a set of isotopes by the same symbol cannot have a cumulated probability different than 1. If that were the case, the error would be reported.

Encountered errors are stored in error_list_p.

Returns true if validation succeeded, false otherwise.

See also validateAllBySymbol() and getCumulatedProbabilitiesBySymbol().

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

Returns true if other and this are different.

MsXpS::libXpertMassCore::IsotopicData &IsotopicData::operator=(const MsXpS::libXpertMassCore::IsotopicData &other)

Assigns member data from other to this instance's member data.

The copying of other into this collection is deep, making *this collection essentially identical to other.

Returns a reference to this collection.

bool IsotopicData::operator==(const MsXpS::libXpertMassCore::IsotopicData &other) const

Returns true if other and this are identical.