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

- libXpertMassCore
- IsotopicData

# MsXpS::libXpertMassCore::IsotopicData Class

class MsXpS::libXpertMassCore::IsotopicData

The IsotopicData class provides a collection of Isotopes and associated methods to access them in various ways. More...

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

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

## Public Functions

| IsotopicData(QObject *parent = nullptr)
| IsotopicData(const MsXpS::libXpertMassCore::IsotopicData &other, QObject *parent = nullptr)
virtual | ~IsotopicData()
void | appendNewIsotope(MsXpS::libXpertMassCore::IsotopeQSPtr isotope_qsp, bool update_maps = true)
void | appendNewIsotopes(const QList<MsXpS::libXpertMassCore::IsotopeQSPtr> &isotopes, bool update_maps = true)
void | clear()
void | clearSymbolMassMaps()
double | computeAvgMass(MsXpS::libXpertMassCore::IsotopeListCstIteratorPair iter_pair, MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | containsName(const QString &name, int &count) const
bool | containsSymbol(const QString &symbol, int &count) const
MsXpS::libXpertMassCore::IsotopeListCstIterator | eraseIsotopes(qsizetype begin_index, qsizetype end_index, bool update_maps = true)
double | getAvgMassBySymbol(const QString &symbol, bool &ok) const
double | getCumulatedProbabilities(MsXpS::libXpertMassCore::IsotopeListCstIteratorPair iter_pair, MsXpS::libXpertMassCore::ErrorList *error_list_p) const
double | getCumulatedProbabilitiesBySymbol(const QString &symbol, MsXpS::libXpertMassCore::ErrorList *error_list_p) const
QString | getFilePath() const
qsizetype | getIsotopeCountBySymbol(const QString &symbol) const
const QList<QSharedPointer<MsXpS::libXpertMassCore::Isotope>> & | getIsotopes() const
MsXpS::libXpertMassCore::IsotopeListCstIteratorPair | getIsotopesByName(const QString &name) const
MsXpS::libXpertMassCore::IsotopeListCstIteratorPair | getIsotopesBySymbol(const QString &symbol) const
double | getMonoMass(MsXpS::libXpertMassCore::IsotopeListCstIteratorPair iter_pair, MsXpS::libXpertMassCore::ErrorList *error_list_p) const
double | getMonoMassBySymbol(const QString &symbol, bool &ok) const
qsizetype | getUniqueSymbolsCount() const
std::vector<QString> | getUniqueSymbolsInOriginalOrder() const
bool | insertNewIsotope(MsXpS::libXpertMassCore::IsotopeQSPtr isotope_qsp, qsizetype index, bool update_maps = true)
bool | isMonoMassIsotope(MsXpS::libXpertMassCore::IsotopeCstQSPtr isotope_cqsp)
bool | isValid()
QString | isotopesAsStringBySymbol(const QString &symbol) const
void | replace(MsXpS::libXpertMassCore::IsotopeQSPtr old_isotope_sp, MsXpS::libXpertMassCore::IsotopeQSPtr new_isotope_sp)
void | setFilePath(const QString &file_path)
qsizetype | size() const
std::size_t | updateAvgMassMap()
bool | updateAvgMassMap(const QString &symbol)
std::size_t | updateMassMaps()
void | updateMassMaps(const QString &symbol)
std::size_t | updateMonoMassMap()
bool | updateMonoMassMap(const QString &symbol)
bool | validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | validateAllBySymbol(MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | validateBySymbol(const QString &symbol, MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | operator!=(const MsXpS::libXpertMassCore::IsotopicData &other) const
MsXpS::libXpertMassCore::IsotopicData & | operator=(const MsXpS::libXpertMassCore::IsotopicData &other)
bool | operator==(const MsXpS::libXpertMassCore::IsotopicData &other) const

## Protected Variables

bool | m_isValid
QList<QSharedPointer<MsXpS::libXpertMassCore::Isotope>> | m_isotopes
QMap<QString, double> | m_symbolAvgMassMap
QMap<QString, double> | m_symbolMonoMassMap

## Detailed Description

The IsotopicData class provides a collection of Isotopes and provides methods to access them in various ways. Methods are available to return the monoisotopic mass of an isotope or the average mass calculated from the data of all the isotopes listed for a given chemical element.

## Member Function Documentation

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

Constructs the IsotopicData.

The instance will have empty member data.

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

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

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

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

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

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.

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

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.

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

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

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

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

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

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

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

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

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

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

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

### `[invokable]` QString IsotopicData::getFilePath() const

Gets the path of the file from which data were loaded.

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

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

Returns the count of isotopes of symbol.

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

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

Note: The order of the isotopes in the collection is not alphabetical (it is the order of the atomic number. This function works on the assumption that all the isotopes of a given symbol are clustered together in the isotopes vector with *no* gap in between.

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.

Note: The order of the isotopes in the collection is not alphabetical (it is the order of the atomic number. This function works on the assumption that all the isotopes of a given symbol are clustered together in the isotopes vector with *no* gap in between.

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.

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

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

Returns the monoisotopic mass for element of symbol.

Returns the monoisotopic mass for element symbol if it is found in this Isotope collection and sets ok to true. If the symbol is not found returns 0.0 and set ok to false.

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

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

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

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.

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

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

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

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.

### `[invokable]` void IsotopicData::setFilePath(const QString &file_path)

Sets the path of the file from which data were loaded to file_path.

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

### qsizetype IsotopicData::size() const

Returns the count of isotopes in the collection.

Note: The count that is returned is for all isotopes, that is, the count if items in the collection.

Note: Getter function for property size.

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

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

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.

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

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.

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

See also updateMonoMassMap() and updateAvgMassMap().

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

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

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

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.

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

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.

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

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

## Member Variable Documentation

### bool IsotopicData::m_isValid

This variable holds the validity status of the IsotopicData instance.

See also isValid() and validate().

### QList<QSharedPointer<MsXpS::libXpertMassCore::Isotope>> IsotopicData::m_isotopes

This variable holds the vector of MsXpS::libXpertMassCore::IsotopeQSPtr.

The vector should never be sorted as we want to keep the order of the isotopes in the way the vector has been populated, either by looking into the IsoSpec library tables or by reading data from a user-configured file.

### QMap<QString, double> IsotopicData::m_symbolAvgMassMap

This variable holds the map relating the Isotope::m_symbol to the average mass.

### QMap<QString, double> IsotopicData::m_symbolMonoMassMap

This variable holds the map relating the Isotope::m_symbol to the monoisotopic mass.