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

- libXpertMassCore
- MassPeakShaperConfig

# MsXpS::libXpertMassCore::MassPeakShaperConfig Class

class MsXpS::libXpertMassCore::MassPeakShaperConfig

The MassPeakShaperConfig class provides the features required to configure the shaping of a mass peak centroid into a Gaussian or a Lorentzian fully profiled shape. More...

Header: | `#include <MsXpS/libXpertMassCore/MassPeakShaperConfig.hpp>`
Inherits: | QObject

- List of all members, including inherited members
- MassPeakShaperConfig is part of libXpertMassCore Mass calculations.

## Properties

- binSize : double
- binSizeDivisor : int
- fwhm : double
- isBinSizeFixed : bool
- massPeakShapeType : Enums::MassPeakShapeType
- massPeakWidthLogic : Enums::MassPeakWidthLogic

- mzStep : double
- pointCount : int
- referencePeakMz : double
- resolution : double
- withBins : bool

## Public Functions

| MassPeakShaperConfig(QObject *parent = nullptr)
| MassPeakShaperConfig(const MsXpS::libXpertMassCore::MassPeakShaperConfig &other, QObject *parent = nullptr)
virtual | ~MassPeakShaperConfig()
double | binSize(bool *ok)
MsXpS::libXpertMassCore::MassPeakShaperConfig * | clone(const MsXpS::libXpertMassCore::MassPeakShaperConfig &other, QObject *parent = nullptr) const
double | fwhm(bool *ok)
double | getBinSize() const
int | getBinSizeDivisor() const
bool | getBinSizeFixed()
double | getFwhm() const
MsXpS::libXpertMassCore::Enums::MassPeakShapeType | getMassPeakShapeType() const
MsXpS::libXpertMassCore::Enums::MassPeakWidthLogic | getMassPeakWidthLogic() const
double | getMzStep() const
int | getPointCount() const
double | getReferencePeakMz() const
double | getResolution() const
double | halfFwhm(bool *ok)
MsXpS::libXpertMassCore::MassPeakShaperConfig & | initialize(const MsXpS::libXpertMassCore::MassPeakShaperConfig &other)
bool | isWithBins() const
double | mzStep(bool *ok)
void | reset()
int | resolution(bool *ok)
bool | resolve(MsXpS::libXpertMassCore::ErrorList &error_list)
void | setBinSize(double bin_size)
void | setBinSizeDivisor(int factor)
void | setBinSizeFixed(bool is_fixed)
void | setFwhm(double fwhm)
void | setMassPeakShapeType(MsXpS::libXpertMassCore::Enums::MassPeakShapeType mass_peak_shape_type)
void | setMassPeakWidthLogic(MsXpS::libXpertMassCore::Enums::MassPeakWidthLogic logic)
void | setMzStep(double mz_step)
void | setPointCount(int point_count)
void | setReferencePeakMz(double mz)
void | setResolution(int resolution)
void | setWithBins(bool with_bins)
QString | toString()

## Protected Variables

double | m_binSize
int | m_binSizeDivisor
double | m_fwhm
bool | m_isBinSizeFixed
MsXpS::libXpertMassCore::Enums::MassPeakShapeType | m_massPeakShapeType
MsXpS::libXpertMassCore::Enums::MassPeakWidthLogic | m_massPeakWidthLogic
double | m_mzStep
int | m_pointCount
double | m_referencePeakMz
int | m_resolution
bool | m_withBins

## Detailed Description

Shaping a peak means creating a shape around a centroid m/z value such that the m/z peak is represented like it appears in a mass spectrum displayed in "profile" mode.

The peak shaping process

The model used to craft the "profiled" mass peak can be of two types:

- Gaussian
- Lorentzian

The starting parameters are the (m/z,intensity) values of the peak centroid and the full width at half maximum (FWHM) value that will govern the width of the shape at 50% height of the peak. The width of the peak will be an inverse representation of the resolving power of the instrument: the instrument with the greatest resolving power will yield mass peaks with the smallest width. Conversely, a very old instrument will produce mass spectra where the peaks will be broad.

There are thus two possiblities for configuring the peak shape:

- Provide the FWHM value itself.
- Provide the resolving power of the instrument that the peak simulation should emulate.

## Property Documentation

### binSize : double

This property holds the size of the m/z bins.

Access functions:

double | getBinSize() const
void | setBinSize(double bin_size)

### binSizeDivisor : int

Empirical division factor to apply to m_binSize to reduce the size of the bins after the bin size calculation.

Empirically, a good value is `6`.

Access functions:

int | getBinSizeDivisor() const
void | setBinSizeDivisor(int factor)

### fwhm : double

Full width at half maximum of the shaped peak.

Access functions:

double | getFwhm() const
void | setFwhm(double fwhm)

### isBinSizeFixed : bool

Tells if the size of the m/z bins is fixed.

Access functions:

bool | getBinSizeFixed()
void | setBinSizeFixed(bool is_fixed)

### massPeakShapeType : Enums::MassPeakShapeType

This property holds the requested shape of the mass peak.

Access functions:

MsXpS::libXpertMassCore::Enums::MassPeakShapeType | getMassPeakShapeType() const
void | setMassPeakShapeType(MsXpS::libXpertMassCore::Enums::MassPeakShapeType mass_peak_shape_type)

### massPeakWidthLogic : Enums::MassPeakWidthLogic

Describes the logic used to compute the peak shape width.

Access functions:

MsXpS::libXpertMassCore::Enums::MassPeakWidthLogic | getMassPeakWidthLogic() const
void | setMassPeakWidthLogic(MsXpS::libXpertMassCore::Enums::MassPeakWidthLogic logic)

### mzStep : double

This property holds the m/z distance (a Delta) between to consecutive data points in the shaped mass peak.

Access functions:

double | getMzStep() const
void | setMzStep(double mz_step)

### pointCount : int

This property holds the count of points used to shape the peak. Typically between 150 and 300.

Access functions:

int | getPointCount() const
void | setPointCount(int point_count)

### referencePeakMz : double

This property holds the m/z value to be used when computing the FWHM value starting from a mass spectrometer resolving power.

Access functions:

double | getReferencePeakMz() const
void | setReferencePeakMz(double mz)

### resolution : double

Resolving power of the instrument.

Access functions:

double | getResolution() const
void | setResolution(int resolution)

### withBins : bool

Tells if bins are requested for the computation.

There is no need in the context of the calculations performed by the MassPeakShaperConfig class to know if bins are required or not. This property is useful when multiple peak shapes are combined into a more complex trace or mass spectrum, typically when simulating an isotopic cluster. In this case, each cluster peak centroid is shaped in sequence and then they are all merged into a single trace (no bins) or mass spectrum (binning). The width of the bins is defined using this withBins variable.

Access functions:

bool | isWithBins() const
void | setWithBins(bool with_bins)

## Member Function Documentation

### `[explicit]` MassPeakShaperConfig::MassPeakShaperConfig(QObject *parent = nullptr)

Constructs a MassPeakShaperConfig instance.

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

Constructs a MassPeakShaperConfig instance as a copy of other.

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

Destructs this MassPeakShaperConfig instance.

### double MassPeakShaperConfig::binSize(bool *ok)

Computes the bin size.

If there is no requirement for bins (m_withBins is false), returns 0 and set ok to true.

In order to compute the bin size we need that at least the FWHM (m_fwhm) or the resolving power (m_resolution) be set. If none of these values are set, this function returns 0 and sets ok to false.

If the bin size was fixed (m_isBinSizeFixed is true), then the bin size (m_binSize) must be set. If that is not the case, the function returns 0 and sets ok to false.

If the FWHM value (m_fwhm) is set, then it is used right away. Otherwise, the FWHM is computed starting from the resolving power (m_resolution). If that computation fails, the function returns 0 and sets ok to false.

Starting from the FWHM value (m_fwhm), the bin size calculation requires that the m_binSizeDivisor be > 1. The bin size is thus computed as the ratio FWHM / m_binSizeDivisor, and the obtained value is set to m_binSize.

Empirically, a value of 6 for m_binSizeDivisor, yields bin sizes that allow combining correctly multiple peak shapes into a mass spectrum. Essentially, that means that 6 individual m/z bins are required to combine nicely all the peaks shapes obtained for all the peak centroids in a given isotopic cluster, for example.

At this point, the function returns the bin size and sets ok to true.

See also setBinSizeDivisor().

### MsXpS::libXpertMassCore::MassPeakShaperConfig *MassPeakShaperConfig::clone(const MsXpS::libXpertMassCore::MassPeakShaperConfig &other, QObject *parent = nullptr) const

Returns a newly allocated MassPeakShaperConfig instance initialized using other and with parent set to parent.

### double MassPeakShaperConfig::fwhm(bool *ok)

Calculates the fwhm (full width at half maximum).

The calculation involves using the instrument's resolving power (m_resolution) member datum and the m/z value that is considered to be the reference for the calculation (m_referencePeakMz).

If any of these two values is not set, then this function returns 0 and sets ok to false.

The calculation is that simple:

    m_fwhm = m_referencePeakMz / m_resolution;

Because we used the resolution to compute the FWHM and set the calculated value to the m_fwhm member datum, we keep a record of this by:

    m_massPeakWidthLogic = Enums::MassPeakWidthLogic::RESOLUTION;

Returns the FWHM value as set in m_fwhm and sets ok to true.

See also setFwhm().

### double MassPeakShaperConfig::getBinSize() const

Returns (no computation) the bin size.

Note: Getter function for property binSize.

### int MassPeakShaperConfig::getBinSizeDivisor() const

Returns the bin size computation dividing factor.

Note: Getter function for property binSizeDivisor.

See also setBinSizeDivisor().

### double MassPeakShaperConfig::getFwhm() const

Gets the fwhm (full width at half maximum).

Note: Getter function for property fwhm.

### MsXpS::libXpertMassCore::Enums::MassPeakShapeType MassPeakShaperConfig::getMassPeakShapeType() const

Gets the type of mass peak shape.

Note: Getter function for property massPeakShapeType.

See also MsXpS::libXpertMassCore::Enums::MassPeakShapeType.

### MsXpS::libXpertMassCore::Enums::MassPeakWidthLogic MassPeakShaperConfig::getMassPeakWidthLogic() const

Gets the mass peak width calculation logic.

Note: Getter function for property massPeakWidthLogic.

See also MsXpS::libXpertMassCore::Enums::MassPeakWidthLogic.

### double MassPeakShaperConfig::getMzStep() const

Gets the m/z step.

The m/z step value is the distance between two consecutive points in the peak shape.

Note: Getter function for property mzStep.

See also setMzStep().

### int MassPeakShaperConfig::getPointCount() const

Gets the count of points to be used to shape the mass peak around the m/z centroid value.

Note: Getter function for property pointCount.

### double MassPeakShaperConfig::getReferencePeakMz() const

Gets the reference m/z value required for calculations.

Note: Getter function for property referencePeakMz.

### double MassPeakShaperConfig::getResolution() const

Returns the resolution (the resolving power of the instrument).

Note: Getter function for property resolution.

### double MassPeakShaperConfig::halfFwhm(bool *ok)

Returns the half of the FWMH (m_fwhm) for use in the Lorentzian shape calculation.

Uses the fwhm() function to compute the FWHM value. If the FWHM calculation fails, returns 0 and ok is set to false, otherwise returns half of FWHM and ok is set to true.

See also fwhm().

### MsXpS::libXpertMassCore::MassPeakShaperConfig &MassPeakShaperConfig::initialize(const MsXpS::libXpertMassCore::MassPeakShaperConfig &other)

Assigns other to this MassPeakShaperConfig instance.

### bool MassPeakShaperConfig::isWithBins() const

Returns the requirement to prepare m/z bins at a later computing stage.

Note: Getter function for property withBins.

See also IsotopicClusterShaper::run() and setWithBins().

### double MassPeakShaperConfig::mzStep(bool *ok)

Calculates the m/z step.

The m/z step value is the distance between two consecutive points in the peak shape. To compute that value, the full m/z width of the calculated shape (not only the width at half maximum, FWHM) is divided by the total number of data points that make the final shape of the m/z peak.

The first variable is FWHM_PEAK_SPAN_FACTOR * m_fwhm, and the second variable is m_pointCount. The calculation is thus:

    m_mzStep = (FWHM_PEAK_SPAN_FACTOR * m_fwhm) / m_pointCount;

The first step is to compute the FWHM and then to check the value of m_pointCount (that cannot be 0). If any of these fails, the function returns 0 and set ok to false, otherwise the computed value is set to m_mzStep and returned, while ok is set to true.

See also setMzStep() and FWHM_PEAK_SPAN_FACTOR.

### void MassPeakShaperConfig::reset()

Resets this MassPeakShaperConfig instance to default values like at construction time.

### int MassPeakShaperConfig::resolution(bool *ok)

Calculates the resolution (resolving power of the instrument).

The calculation involves using the FWHM (m_fwhm) member datum and the m/z value that is considered to be the reference for the calculation (m_referencePeakMz).

If any of these two values is not set, then this function returns 0 and sets ok to false.

The calculation is that simple:

    m_resolution = m_referencePeakMz / m_fwhm;

Because we used the FWHM to compute the resolution and set the calculated value to the m_resolution member datum, we keep a record of this by:

    m_massPeakWidthLogic = Enums::MassPeakWidthLogic::FWHM;

Returns the resolving power as set in m_resolution and sets ok to true.

See also setResolution().

### bool MassPeakShaperConfig::resolve(MsXpS::libXpertMassCore::ErrorList &error_list)

Calculates the various parameters of the peak shape using member data.

This function first checks that all the required data are set. Then this functions computes the FWHM value required to shape the peak centroid. Once the basic data have been computed or set, the parameters of the shape are computed: c, a, gamma.

If one or more errors occur, they are logged in error_list.

Returns true if the computation was successful, false otherwise.

### void MassPeakShaperConfig::setBinSize(double bin_size)

Sets the bin_size.

Note: Setter function for property binSize.

See also binSize().

### void MassPeakShaperConfig::setBinSizeDivisor(int factor)

Sets the bin size computation dividing factor.

When the bin size is computed (m_isBinSizeFixed is false), that value is determined by dividing the FWHM value by this factor (m_binSizeDivisor).

Empirically, a value of 6 for m_binSizeDivisor, yields bin sizes that allow combining correctly multiple peak shapes into a mass spectrum. Essentially, that means that 6 individual m/z bins are required to combine nicely all the peaks shapes obtained for all the peak centroids in a given isotopic cluster, for example.

Note: Setter function for property binSizeDivisor.

### void MassPeakShaperConfig::setBinSizeFixed(bool is_fixed)

Sets the requirement that the bin size be set and fixed (not modifiable by computations) to is_fixed.

When is_fixed is true, the binSize() function returns the bin size without trying to compute it.

Note: Setter function for property isBinSizeFixed.

See also binSize().

### void MassPeakShaperConfig::setFwhm(double fwhm)

Sets the fwhm (full width at half maximum).

Note: Setter function for property fwhm.

See also fwhm().

### void MassPeakShaperConfig::setMassPeakShapeType(MsXpS::libXpertMassCore::Enums::MassPeakShapeType mass_peak_shape_type)

Sets the type of mass peak shape to mass_peak_shape_type.

Note: Setter function for property massPeakShapeType.

See also MsXpS::libXpertMassCore::Enums::MassPeakShapeType.

### void MassPeakShaperConfig::setMassPeakWidthLogic(MsXpS::libXpertMassCore::Enums::MassPeakWidthLogic logic)

Sets the mass peak width calculation logic.

The full mass peak width at half peak maximum (FWHM) can either be set manually or be computed from a reference m/z value and the instrument's resolving power.

Note: Setter function for property massPeakWidthLogic.

See also MsXpS::libXpertMassCore::Enums::MassPeakWidthLogic.

### void MassPeakShaperConfig::setMzStep(double mz_step)

Sets the mz_step.

The m/z step value is the distance between two consecutive points in the peak shape.

Note: Setter function for property mzStep.

See also mzStep() and getMzStep().

### void MassPeakShaperConfig::setPointCount(int point_count)

Sets the point_count to be used to shape the mass peak around the m/z centroid value.

Typically, a value between 150 and 200 points is fine to nicely shape a m/z peak centroid.

Note: Setter function for property pointCount.

### void MassPeakShaperConfig::setReferencePeakMz(double mz)

Sets the reference m/z value required for calculations to mz.

Note: Setter function for property referencePeakMz.

### void MassPeakShaperConfig::setResolution(int resolution)

Sets the resolution (the resolving power of the instrument).

Note: Setter function for property resolution.

See also resolution().

### void MassPeakShaperConfig::setWithBins(bool with_bins)

Sets the requirement to prepare m/z bins at a later computing stage to with_bins.

Note: Setter function for property withBins.

See also IsotopicClusterShaper::run() and isWithBins().

### QString MassPeakShaperConfig::toString()

Returns a string representing this MassPeakShaperConfig instance.

The configuration of the MassPeakShaper is first resolved. If that step fails, an empty string is returned, otherwise the configuration is returned as a string.

## Member Variable Documentation

### double MassPeakShaperConfig::m_binSize

This variable holds the size of the m/z bins.

### int MassPeakShaperConfig::m_binSizeDivisor

Empirical division factor to apply to m_binSize to reduce the size of the bins after the bin size calculation.

Empirically, a good value is `6`.

### double MassPeakShaperConfig::m_fwhm

Full width at half maximum of the shaped peak.

### bool MassPeakShaperConfig::m_isBinSizeFixed

Tells if the size of the m/z bins is fixed.

### MsXpS::libXpertMassCore::Enums::MassPeakShapeType MassPeakShaperConfig::m_massPeakShapeType

This variable holds the requested shape of the mass peak.

### MsXpS::libXpertMassCore::Enums::MassPeakWidthLogic MassPeakShaperConfig::m_massPeakWidthLogic

Describes the logic used to compute the peak shape width.

### double MassPeakShaperConfig::m_mzStep

This variable holds the m/z distance (a Delta) between to consecutive data points in the shaped mass peak.

### int MassPeakShaperConfig::m_pointCount

This variable holds the count of points used to shape the peak. Typically between 150 and 300.

### double MassPeakShaperConfig::m_referencePeakMz

This variable holds the m/z value to be used when computing the FWHM value starting from a mass spectrometer resolving power.

### int MassPeakShaperConfig::m_resolution

Resolving power of the instrument.

### bool MassPeakShaperConfig::m_withBins

Tells if bins are requested for the computation.

There is no need in the context of the calculations performed by the MassPeakShaperConfig class to know if bins are required or not. This variable is useful when multiple peak shapes are combined into a more complex trace or mass spectrum, typically when simulating an isotopic cluster. In this case, each cluster peak centroid is shaped in sequence and then they are all merged into a single trace (no bins) or mass spectrum (binning). The width of the bins is defined using this m_withBins variable.