GwyPeaks: Gwyddion Library Reference Manual

## GwyPeaks GwyPeaks — Graph peak analyser |

## Functions

GwyPeaks * | gwy_peaks_new ()
GwyPeaks * | gwy_peaks_copy ()
void | gwy_peaks_free ()
void | gwy_peaks_set_background ()
void | gwy_peaks_set_order ()
guint | gwy_peaks_analyze ()
guint | gwy_peaks_analyze_xy ()
guint | gwy_peaks_analyze_line ()
guint | gwy_peaks_n_peaks ()
void | gwy_peaks_get_quantity ()

## Types and Values

enum | GwyPeakBackgroundType
enum | GwyPeakOrderType
enum | GwyPeakQuantity
| GwyPeaks

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

One GwyPeaks analyser can be used repeatedly to find and characterise peaks in several data sets.

Feed the curve data to the analyser using functions such as `gwy_peaks_analyze()`, `gwy_peaks_analyze_line()` or `gwy_peaks_analyze_xy()`. It will process the data, locate peaks and remember their various characteristics that you can subsequently obtain using `gwy_peaks_get_quantity()`. The results are static; if you change the analyser settings (or the curve data) you need to re-run the analysis function.

## Functions

### gwy_peaks_new()

    GwyPeaks *
    gwy_peaks_new (void);

Creates a new empty peak analyser.

#### Returns

A new peak analyser.

### gwy_peaks_copy()

    GwyPeaks *
    gwy_peaks_copy (GwyPeaks *peaks);

Creates a copy of a peak analyser.

This is mostly useful for language bindings.

#### Parameters

peaks | A peak analyser. |

#### Returns

A newly created peak analyser.

### gwy_peaks_free()

    void
    gwy_peaks_free (GwyPeaks *peaks);

Frees a peak analyser and all associated data.

#### Parameters

peaks | A peak analyser. |

### gwy_peaks_set_background()

    void
    gwy_peaks_set_background (GwyPeaks *peaks,
                              GwyPeakBackgroundType background);

Sets the background type a peak analyser will use.

The default background is `GWY_PEAK_BACKGROUND_MMSTEP`. Note that the new background type will only be used in future analyses; it does not change the results of the already performed analysis.

#### Parameters

peaks | A peak analyser. |
background | Background type to use in future analyses. |

### gwy_peaks_set_order()

    void
    gwy_peaks_set_order (GwyPeaks *peaks,
                         GwyPeakOrderType order);

Sets the order type a peak analyser will use.

The default order is `GWY_PEAK_ORDER_ABSCISSA`. Note that the new order will only be effective in future analyses; it does not change the results of the already performed analysis.

#### Parameters

peaks | A peak analyser. |
order | Order type to use in future analyses. |

### gwy_peaks_analyze()

    guint
    gwy_peaks_analyze (GwyPeaks *peaks,
                       const gdouble *xdata,
                       const gdouble *ydata,
                       guint n,
                       guint maxpeaks);

Finds peaks a graph curve given as separated `x` and `y` data.

The peaks are remembered by the analyser and their properties can be subsequently requested using `gwy_peaks_get_quantity()`.

#### Parameters

peaks | A peak analyser. |
xdata | Abscissa values (array with `n` items), must be ordered in ascending order. |
ydata | Ordinate values corresponding to `xdata` . |
n | Number of data points in the curve. |
maxpeaks | Maximum number of the most prominent peaks to locate. |

#### Returns

The number of peaks found.

### gwy_peaks_analyze_xy()

    guint
    gwy_peaks_analyze_xy (GwyPeaks *peaks,
                          const GwyXY *xydata,
                          guint n,
                          guint maxpeaks);

Finds peaks a graph curve given as GwyXY data.

The peaks are remembered by the analyser and their properties can be subsequently requested using `gwy_peaks_get_quantity()`.

#### Parameters

peaks | A peak analyser. |
xydata | Curve points (array with `n` items) that must be ordered by `x` values in ascending order. | [array length=n]
n | Number of data points in the curve. |
maxpeaks | Maximum number of the most prominent peaks to locate. |

#### Returns

The number of peaks found.

### gwy_peaks_analyze_line()

    guint
    gwy_peaks_analyze_line (GwyPeaks *peaks,
                            GwyLine *dline,
                            guint maxpeaks);

Finds peaks a graph curve given as GwyLine.

The peaks are remembered by the analyser and their properties can be subsequently requested using `gwy_peaks_get_quantity()`.

#### Parameters

peaks | A peak analyser. |
dline | Curve data as a data line. |
maxpeaks | Maximum number of the most prominent peaks to locate. |

#### Returns

The number of peaks found.

### gwy_peaks_n_peaks()

    guint
    gwy_peaks_n_peaks (GwyPeaks *peaks);

Gets the current number of peaks of a peak analyser.

#### Parameters

peaks | A peak analyser. |

#### Returns

The currently remembered number of peaks.

### gwy_peaks_get_quantity()

    void
    gwy_peaks_get_quantity (GwyPeaks *peaks,
                            GwyPeakQuantity quantity,
                            gdouble *data);

Obtaines values of a given quantity for all found peaks.

#### Parameters

peaks | A peak analyser. |
quantity | Peak property to return. |
data | Array of sufficient length to hold values for all peaks (their number is returned by `gwy_peaks_n_peaks()`). |

## Types and Values

### enum GwyPeakBackgroundType

Type of background available in graph peak analysers.

#### Members

GWY_PEAK_BACKGROUND_ZERO | The background is fixed at zero value. |
GWY_PEAK_BACKGROUND_MMSTEP | The background is a step function connecting the nearest minima on the left and right side. |

### enum GwyPeakOrderType

Type of peak ordering by in the graph peak analyser results.

#### Members

GWY_PEAK_ORDER_ABSCISSA | Peaks are ordered by abscissa values, from left to right. |
GWY_PEAK_ORDER_PROMINENCE | Peaks are ordered by prominence, from most to least prominent. |

### enum GwyPeakQuantity

Type of characteristics graph peak analysers can provide.

#### Members

GWY_PEAK_PROMINENCE | Compound quantity characteristing the overall peak prominence (taking into account height, area, distance from other peaks, ...). |
GWY_PEAK_ABSCISSA | Position of peak maximum. |
GWY_PEAK_HEIGHT | Peak height (with respect to the chosen background function). |
GWY_PEAK_AREA | Peak area (with respect to the chosen background function). |
GWY_PEAK_WIDTH | Peak width, more or less corresponding to standard deviation. |

### GwyPeaks

    typedef struct _GwyPeaks GwyPeaks;

GwyPeaks is an opaque data structure and should be only manipulated with the functions below.