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

- libXpertMassCore
- Sequence

# MsXpS::libXpertMassCore::Sequence Class

class MsXpS::libXpertMassCore::Sequence

The Sequence class provides abstractions to work with a simple sequence of Monomers. More...

Header: | `#include <Sequence.hpp>`

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

## Public Functions

| Sequence()
| Sequence(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QString &sequence_text)
| Sequence(const MsXpS::libXpertMassCore::Sequence &other)
virtual | ~Sequence()
int | appendSequence(const QString &sequence, std::vector<std::size_t> &failing_indices)
quint16 | checksum(int index_start = -1, int index_stop = -1, bool with_modifs = false) const
void | cleanupMonomers()
void | clear()
int | findForwardMotif(const MsXpS::libXpertMassCore::Sequence &sequence_motif, std::size_t &index) const
std::vector<QString> | getAllMonomerUuids() const
MsXpS::libXpertMassCore::MonomerCstRPtr | getMonomerCstRPtrAt(std::size_t index) const
MsXpS::libXpertMassCore::MonomerSPtr | getMonomerCstSPtrAt(std::size_t index) const
MsXpS::libXpertMassCore::MonomerSPtr | getMonomerForUuid(const QString &uuid) const
MsXpS::libXpertMassCore::MonomerRPtr | getMonomerRPtrAt(std::size_t index)
MsXpS::libXpertMassCore::MonomerSPtr | getMonomerSPtrAt(std::size_t index)
const std::vector<MsXpS::libXpertMassCore::MonomerSPtr> & | getMonomersCstRef() const
std::vector<MsXpS::libXpertMassCore::MonomerSPtr> & | getMonomersRef()
MsXpS::libXpertMassCore::PolChemDefCstSPtr | getPolChemDef() const
QString | getSequence() const
QString | getSequence(const MsXpS::libXpertMassCore::IndexRangeCollection &index_ranges, bool with_modif = false, bool delimited_regions = false) const
QString | getSequence(std::size_t start_index, std::size_t stop_index, bool with_modif = false) const
QString | getUuidForMonomer(const MsXpS::libXpertMassCore::MonomerSPtr &monomer_sp) const
bool | hasModifiedMonomer(std::size_t left_index, std::size_t right_index) const
bool | hasMonomer(const MsXpS::libXpertMassCore::MonomerSPtr &monomer_sp) const
bool | hasUuid(const MsXpS::libXpertMassCore::MonomerSPtr &monomer_sp) const
QString | insertMonomerAt(const MsXpS::libXpertMassCore::Monomer &monomer, std::size_t index)
bool | isInBound(std::size_t index)
bool | isValid() const
int | makeMonomers(const QString &sequence_text, bool reset, std::vector<std::size_t> &failing_indices)
std::vector<std::size_t> | modifiedMonomerIndices(std::size_t left_index, std::size_t right_index) const
bool | modifyMonomer(std::size_t index, const QString modif_name, bool override)
std::size_t | monomerIndex(MsXpS::libXpertMassCore::MonomerCstRPtr monomer_crp, bool &ok) const
std::size_t | monomerIndex(MsXpS::libXpertMassCore::MonomerCstSPtr monomer_csp, bool &ok) const
std::size_t | monomerIndex(MsXpS::libXpertMassCore::MonomerSPtr monomer_sp, bool &ok) const
std::size_t | nextCode(const QString &sequence, QString &code, std::size_t &index, QString &err)
bool | removeMonomerAt(std::size_t index)
void | setPolChemDefCstSPtr(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp)
int | setSequence(const QString &sequence, std::vector<std::size_t> &failing_indices)
std::size_t | size() const
QString | storeMonomer(const MsXpS::libXpertMassCore::MonomerSPtr &monomer_sp)
QString | storeMonomer(const MsXpS::libXpertMassCore::MonomerSPtr &monomer_sp, std::size_t index)
QString | unspacifySequence(const QString &monomer_text)
bool | validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | operator!=(const MsXpS::libXpertMassCore::Sequence &other)
MsXpS::libXpertMassCore::Sequence & | operator=(const MsXpS::libXpertMassCore::Sequence &other)
bool | operator==(const MsXpS::libXpertMassCore::Sequence &other)

## Protected Variables

bool | m_isValid
std::vector<MsXpS::libXpertMassCore::MonomerSPtr> | m_monomers
MsXpS::libXpertMassCore::PolChemDefCstSPtr | mcsp_polChemDef

## Detailed Description

A sequence of monomer is a vector of fully qualified Monomer instances allocated on the heap.

## Member Function Documentation

### Sequence::Sequence()

Constructs a totally empty Sequence as an invalid object.

See also setSequence().

### Sequence::Sequence(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, const QString &sequence_text)

Constructs a Sequence in the context of the pol_chem_def_csp polymer chemistry definition using the sequence_text representation of a Monomer sequence.

The sequence_text is a concatenation of monomer codes. That text sequence is immediately converted into Monomer instances using pol_chem_def_csp as the reference PolChemDef. The Monomer instances (actually newly allocated Monomer shared pointers) are stored in the member container keeping the order of the Monomer codes in sequence_text.

If all the Monomer codes in the sequence_text were correct, the status of the Sequence is set to valid, otherwise it is set to invalid (query with isValid()).

See also makeMonomers().

### Sequence::Sequence(const MsXpS::libXpertMassCore::Sequence &other)

Constructs this Sequence instance as a copy of other.

The copying is deep with the Monomer instances in the member container being reinstantiated into this Sequence.

### `[virtual noexcept]` Sequence::~Sequence()

Destructs this sequence.

### int Sequence::appendSequence(const QString &sequence, std::vector<std::size_t> &failing_indices)

Appends the sequence of Monomer codes to this Sequence.

No verification is performed on sequence. The codes are immediately converted into newly allocated Monomer instances appended in order to the m_monomers container. If there are indices of the sequence that failed converting to Monomer instances, they are stored in failing_indices.

After setting the member data, the instance is validated and the result is set to m_isValid.

Returns -1 if an error occurred, or the count of Monomer instances actually added to the sequence.

### quint16 Sequence::checksum(int index_start = -1, int index_stop = -1, bool with_modifs = false) const

Returns a checksum calculated on this Sequence's portion contained in [index_start – index_stop].

The sequence matching the [index_start – index_stop] range is extracted from m_monomerText, with (with_modifs is true) or without (with_modifs is false) the monomer modifications. The checksum is computed on that extracted string.

Returns the checksum.

### void Sequence::cleanupMonomers()

Removes from the member container all the Monomer instance pointers that are not found to still be alive.

### void Sequence::clear()

Reset this Sequence instance to default values.

### int Sequence::findForwardMotif(const MsXpS::libXpertMassCore::Sequence &sequence_motif, std::size_t &index) const

Searches for a Sequence textual sequence_motif in this Sequence's container of Monomer instances, starting at index.

sequence_motif, a text string is first converted to a container of Monomer instances (using the reference list of Monomer instances in the member polymer chemistry definition). Then, this Sequence's container of Monomer instances is searched for a Monomer stretch that matches that created for sequence_motif.

As soon as a Monomer code stretch is found, the index in this Sequence's container of Monomer instances is set to index.

Returns -1 if an error occurred, 1 if sequence_motif was found in this Sequence, 0 otherwise.

### std::vector<QString> Sequence::getAllMonomerUuids() const

Returns a container of QString instances that correspond to the UUID strings that identify all the Monomer instances involved in this Sequence.

If no Monomer is found, an empty container is returned.

### MsXpS::libXpertMassCore::MonomerCstRPtr Sequence::getMonomerCstRPtrAt(std::size_t index) const

Returns the Monomer instance at index in this Sequence's container of Monomer instances as a const raw pointer.

An index that is out of bounds is fatal.

### MsXpS::libXpertMassCore::MonomerSPtr Sequence::getMonomerCstSPtrAt(std::size_t index) const

Returns the Monomer instance at index in this Sequence's container of Monomer instances as a const shared pointer.

An index that is out of bounds is fatal.

### MsXpS::libXpertMassCore::MonomerSPtr Sequence::getMonomerForUuid(const QString &uuid) const

Returns the Monomer instance pointer in the member container that is associated to the uuid Uuid string.

If no such Monomer instance pointer is found, nullptr is returned.

### MsXpS::libXpertMassCore::MonomerRPtr Sequence::getMonomerRPtrAt(std::size_t index)

Returns the Monomer instance at index in this Sequence's container of Monomer instances as a raw pointer.

An index that is out of bounds is fatal.

### MsXpS::libXpertMassCore::MonomerSPtr Sequence::getMonomerSPtrAt(std::size_t index)

Returns the Monomer instance at index in this Sequence's container of Monomer instances as a shared pointer.

An index that is out of bounds is fatal.

### const std::vector<MsXpS::libXpertMassCore::MonomerSPtr> &Sequence::getMonomersCstRef() const

Returns a const reference to the Monomer container.

### std::vector<MsXpS::libXpertMassCore::MonomerSPtr> &Sequence::getMonomersRef()

Returns a reference to the Monomer container.

### MsXpS::libXpertMassCore::PolChemDefCstSPtr Sequence::getPolChemDef() const

Returns the polymer chemistry definition.

### QString Sequence::getSequence() const

Returns a string with all the codes of the Monomer instances found in the member container concatenated in order.

### QString Sequence::getSequence(const MsXpS::libXpertMassCore::IndexRangeCollection &index_ranges, bool with_modif = false, bool delimited_regions = false) const

Returns a string with all the codes of the Monomer instances found in the member container concatenated in order.

The returned string only contains the sequence of monomer codes for Monomer instances contained in the IndexRange instances contained in index_ranges.

If with_modif is true, the modification(s) associated to Monomers are also output to the string. The form of the string is, in this case,

    Thr<Phosphorylation>

If delimited_regions is true, the sequence of Monomer codes belonging to each sequence range will be delimited using the IndexRange positions (not the indices).

See also IndexRange::positionsAsText().

### QString Sequence::getSequence(std::size_t start_index, std::size_t stop_index, bool with_modif = false) const

Returns a string with all the codes of the Monomer instances found in the member container concatenated in order.

The returned string only contains the sequence of monomer codes for Monomer instances included in the indices range [start_index – stop_index] (inclusively) in this Sequence's container of Monomer instances.

If stop_index is > size(), then it is set to size().

If with_modif is true, the Modif instances associated to Monomers are also output to the string. The form of the string is, in this case,

    Thr<Phosphorylation>

### QString Sequence::getUuidForMonomer(const MsXpS::libXpertMassCore::MonomerSPtr &monomer_sp) const

Returns the UUID string identifying monomer_sp in the member container.

If no such Monomer is found, an empty string is returned.

### bool Sequence::hasModifiedMonomer(std::size_t left_index, std::size_t right_index) const

Returns true if this Sequence instance, between Monomer indices left_index and right_index, has at least one modified Monomer instance.

If no Monomer is modified, returns false.

### bool Sequence::hasMonomer(const MsXpS::libXpertMassCore::MonomerSPtr &monomer_sp) const

Returns true if monomer_sp was found in the member container of Monomer instances, false otherwise.

### bool Sequence::hasUuid(const MsXpS::libXpertMassCore::MonomerSPtr &monomer_sp) const

Returns true if monomer_sp was found in the member container of Uuid-Monomer pairs, false otherwise.

### QString Sequence::insertMonomerAt(const MsXpS::libXpertMassCore::Monomer &monomer, std::size_t index)

Inserts monomer at index index.

If the index value is equal to the size of the Monomer container, then, the monomer is added to the bottom of the container.

If the index value is greater than the size of the Monomer container, that is fatal.

Returns the Uuid string corresponding to the new Monomer.

### bool Sequence::isInBound(std::size_t index)

Returns true if index is valid as an index of a Monomer instance in this Sequence's container of Monomer instances, false otherwise.

### bool Sequence::isValid() const

Returns the validity status of this Sequence instance.

### int Sequence::makeMonomers(const QString &sequence_text, bool reset, std::vector<std::size_t> &failing_indices)

Allocates all the Monomer instances to describe this Sequence's string representation of monomer codes.

This function parses the sequence_text Monomer codes string and, for each encountered code, creates a Monomer instance and adds it to the member container of Monomer instances.

If reset is true, the member container of Monomer instances is reset before the work is done. Any error that might occur is stored as the index of the failing Monomer code in the failing_indices container.

The allocation of each Monomer instance based on its code is performed by looking at the reference Monomer in the member polymer chemistry definition..

Because the m_monomerText member string of Monomer codes does not document any monomer modification, no modifications are handled in this function.

Returns the count of Monomer instances set to the list or -1 if an error occurred.

### std::vector<std::size_t> Sequence::modifiedMonomerIndices(std::size_t left_index, std::size_t right_index) const

Returns a container holding all the indices corresponding to modified Monomer instances in the member Monomer container.

The search is performed only between Monomer indices left_index and right_index.

If no Monomer is modified, returns an empty container.

### bool Sequence::modifyMonomer(std::size_t index, const QString modif_name, bool override)

Modifies the Monomer instance at index index with a Modif instance that is created on the basis of modif_name.

If override is set to true, then the modification occurs even if the Monomer at already modified max count times.

An index that is out of bounds is fatal.

Returns true.

See also Modif::m_maxCount.

### std::size_t Sequence::monomerIndex(MsXpS::libXpertMassCore::MonomerCstRPtr monomer_crp, bool &ok) const

Returns the index of monomer_crp in this Sequence's list of Monomer instances.

The search is based on comparison of the pointers, that is, the returned index is for the same Monomer object (pointer-wise). If the Monomer was found, the returned value is certain to be correct and ok is set to true. If the Monomer was not found, the returned value is 0 and ok is set to false.

### std::size_t Sequence::monomerIndex(MsXpS::libXpertMassCore::MonomerCstSPtr monomer_csp, bool &ok) const

Returns the index of monomer_csp in this Sequence's container of Monomer instances.

The search is based on comparison of the pointers, that is, the returned index is for the same Monomer object (pointer-wise). If the Monomer was found, the returned value is certain to be correct and ok is set to true. If the Monomer was not found, the returned value is 0 and ok is set to false.

### std::size_t Sequence::monomerIndex(MsXpS::libXpertMassCore::MonomerSPtr monomer_sp, bool &ok) const

Returns the index of monomer_sp in this Sequence's container of Monomer instances.

The search is based on comparison of the pointers, that is, the returned index is for the same Monomer object (pointer-wise). If the Monomer was found, the returned value is certain to be correct and ok is set to true. If the Monomer was not found, the returned value is 0 and ok is set to false.

### std::size_t Sequence::nextCode(const QString &sequence, QString &code, std::size_t &index, QString &err)

Seeks the next code occurring in the sequence string of Monomer codes.

This function starts looking in sequence at index. The next found Monomer code is stored in code. If sequence is not a monomer code, it is set to err.

Returns the count of characters that make code. This count can be used to search for the next code by setting its value incremented by 1 to index for a next function call.

### bool Sequence::removeMonomerAt(std::size_t index)

Removes the Monomer instance at index index from this Sequence's list of Monomer instances.

An index that is out of bounds is fatal.

Returns true.

### void Sequence::setPolChemDefCstSPtr(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp)

Sets the polymer chemistry definition to pol_chem_def_csp.

### int Sequence::setSequence(const QString &sequence, std::vector<std::size_t> &failing_indices)

Sets the sequence of Monomer codes to this Sequence.

No verification is performed on sequence. The codes are immediately converted into newly allocated Monomer instances appended in order to the member container of Monomer instances.

The member Monomer container is first cleared.

If there are indices of the sequence that failed converting to Monomer instances, they are stored in failing_indices.

After setting the member data, the instance is validated and the result is set to m_isValid.

Returns -1 if an error occurred, or the count of Monomer instances actually set to the sequence.

### std::size_t Sequence::size() const

Returns the size of this Sequence as the size of the container of Monomer instances.

### QString Sequence::storeMonomer(const MsXpS::libXpertMassCore::MonomerSPtr &monomer_sp)

Stores the Monomer instance pointer monomer_sp in the member container and returns the Uuid string associated to it.

### QString Sequence::storeMonomer(const MsXpS::libXpertMassCore::MonomerSPtr &monomer_sp, std::size_t index)

Stores the Monomer instance pointer in the member container and returns the Uuid string associated to it.

### QString Sequence::unspacifySequence(const QString &monomer_text)

Removes all spaces, tabulations, carriage returns and linefeeds from the monomer_text sequence of Monomer codes.

### bool Sequence::validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Validates this Sequence using the member polymer chemistry definition as the reference polymer chemistry definition and sets m_isValid to the result of this validation.

Returns true if all the Monomer instances in the member container could be found in the polymer chemistry definition's container of reference Monomer instances.

Any error is documented by storing a message to error_list_p.

See also makeMonomers().

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

Returns true if the `this` Sequence is different than other, false otherwise.

Returns the negation of operator==(other).

### MsXpS::libXpertMassCore::Sequence &Sequence::operator=(const MsXpS::libXpertMassCore::Sequence &other)

Assigns other to this Sequence.

The copying is deep with the instances in the other container of Monomer instances being reinstantiated anew into this Sequence's container of Monomer instances.

Returns a reference to this Sequence.

### bool Sequence::operator==(const MsXpS::libXpertMassCore::Sequence &other)

Returns true if the `this` Sequence is identical to other, false otherwise.

The comparison of the Monomer instances is deep and is not based on merely comparing the pointers.

## Member Variable Documentation

### bool Sequence::m_isValid

This variable holds the validity status of this Sequence instance.

### std::vector<MsXpS::libXpertMassCore::MonomerSPtr> Sequence::m_monomers

Vector of allocated Monomer instances.

### MsXpS::libXpertMassCore::PolChemDefCstSPtr Sequence::mcsp_polChemDef

This variable holds the PolChemDef polymer chemistry definition that is the context in which the Sequence exists.