Line statistics: Gwyddion Library Reference Manual

## Line statistics Line statistics — One-dimensional statistical functions |

## Functions

gdouble | gwy_line_max ()
gdouble | gwy_line_min ()
void | gwy_line_min_max ()
gint | gwy_line_min_pos_i ()
gint | gwy_line_max_pos_i ()
gdouble | gwy_line_min_pos_r ()
gdouble | gwy_line_max_pos_r ()
gdouble | gwy_line_mean ()
gdouble | gwy_line_rms ()
gdouble | gwy_line_tan_beta0 ()
gdouble | gwy_line_variation ()
gdouble | gwy_line_sum ()
gdouble | gwy_line_ra ()
gdouble | gwy_line_skew ()
gdouble | gwy_line_kurtosis ()
gdouble | gwy_line_part_max ()
gdouble | gwy_line_part_min ()
void | gwy_line_part_min_max ()
gdouble | gwy_line_part_mean ()
gdouble | gwy_line_part_rms ()
gdouble | gwy_line_part_tan_beta0 ()
gdouble | gwy_line_part_variation ()
gdouble | gwy_line_part_sum ()
gdouble | gwy_line_part_ra ()
gdouble | gwy_line_part_skew ()
gdouble | gwy_line_part_kurtosis ()
gdouble | gwy_line_modus ()
gdouble | gwy_line_part_modus ()
gdouble | gwy_line_median ()
gdouble | gwy_line_part_median ()
gdouble | gwy_line_length ()
gdouble | gwy_line_xpm ()
gdouble | gwy_line_xvm ()
gdouble | gwy_line_xtm ()
gint | gwy_line_kth_peaks ()
gint | gwy_line_count_peaks ()
void | gwy_line_distribution ()
void | gwy_line_height_dist ()
void | gwy_line_angle_dist ()
void | gwy_line_acf ()
void | gwy_line_hhcf ()
void | gwy_line_psdf ()

## Types and Values

enum | GwyLineStatQuantity

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

## Functions

### gwy_line_max()

    gdouble
    gwy_line_max (GwyLine *line);

Finds the maximum value of a data line.

#### Parameters

line | A data line. |

#### Returns

The maximum value.

### gwy_line_min()

    gdouble
    gwy_line_min (GwyLine *line);

Finds the minimum value of a data line.

#### Parameters

line | A data line. |

#### Returns

The minimum value.

### gwy_line_min_max()

    void
    gwy_line_min_max (GwyLine *line,
                      gdouble *min,
                      gdouble *max);

Finds the minimum and maximum values of a data line.

#### Parameters

line | A data line. |
min | Location to store minimum to. | [out]
max | Location to store maximum to. | [out]

### gwy_line_min_pos_i()

    gint
    gwy_line_min_pos_i (GwyLine *line);

Finds the minimum pixel position of a data line.

For historical reasons the value is returned as double, but it is always an integer.

#### Parameters

line | A data line. |

#### Returns

The minimum pixel position.

### gwy_line_max_pos_i()

    gint
    gwy_line_max_pos_i (GwyLine *line);

Finds the maximum pixel position of a data line.

For historical reasons the value is returned as double, but it is always an integer.

#### Parameters

line | A data line. |

#### Returns

The maximum pixel position.

### gwy_line_min_pos_r()

    gdouble
    gwy_line_min_pos_r (GwyLine *line);

Finds the real minimum position in a data line.

#### Parameters

line | A data line. |

#### Returns

Real position for the minimum.

### gwy_line_max_pos_r()

    gdouble
    gwy_line_max_pos_r (GwyLine *line);

Finds the real maximum position in a data line.

#### Parameters

line | A data line. |

#### Returns

Real position for the maximum.

### gwy_line_mean()

    gdouble
    gwy_line_mean (GwyLine *line);

Computes average value of a data line.

#### Parameters

line | A data line. |

#### Returns

Average value

### gwy_line_rms()

    gdouble
    gwy_line_rms (GwyLine *line);

Computes root mean square value of a data line.

#### Parameters

line | A data line. |

#### Returns

Root mean square deviation of values.

### gwy_line_tan_beta0()

    gdouble
    gwy_line_tan_beta0 (GwyLine *line);

Computes root mean square slope in a data line.

#### Parameters

line | A data line. |

#### Returns

Root mean square slope within a given interval.

### gwy_line_variation()

    gdouble
    gwy_line_variation (GwyLine *line);

Computes the total variation of a data line.

See `gwy_line_part_variation()` for definition and discussion.

#### Parameters

line | A data line. |

#### Returns

The total variation.

### gwy_line_sum()

    gdouble
    gwy_line_sum (GwyLine *line);

Computes sum of all values in a data line.

#### Parameters

line | A data line. |

#### Returns

sum of all the values.

### gwy_line_ra()

    gdouble
    gwy_line_ra (GwyLine *line);

Computes the mean absolute deviation of a data line.

#### Parameters

line | A data line. |

#### Returns

The mean absolute deviation of height values.

### gwy_line_skew()

    gdouble
    gwy_line_skew (GwyLine *line);

Computes the skew of a data line.

#### Parameters

line | A data line. |

#### Returns

The skew of height values.

### gwy_line_kurtosis()

    gdouble
    gwy_line_kurtosis (GwyLine *line);

Computes the kurtosis of a data line.

#### Parameters

line | A data line. |

#### Returns

The kurtosis of height values.

Note the kurtosis returned by this function returns is the excess kurtosis which is zero for the Gaussian distribution (not 3).

### gwy_line_part_max()

    gdouble
    gwy_line_part_max (GwyLine *line,
                       gint pos,
                       gint len);

Finds the maximum value of a part of a data line.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

Maximum within given interval.

### gwy_line_part_min()

    gdouble
    gwy_line_part_min (GwyLine *line,
                       gint pos,
                       gint len);

Finds the minimum value of a part of a data line.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

Minimum within given interval.

### gwy_line_part_min_max()

    void
    gwy_line_part_min_max (GwyLine *line,
                           gint pos,
                           gint len,
                           gdouble *min,
                           gdouble *max);

Finds the minimum and maximum values of a part of a data line.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |
min | Location to store minimum to. | [out]
max | Location to store maximum to. | [out]

### gwy_line_part_mean()

    gdouble
    gwy_line_part_mean (GwyLine *line,
                        gint pos,
                        gint len);

Computes mean value of all values in a part of a data line.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

Average value within given interval.

### gwy_line_part_rms()

    gdouble
    gwy_line_part_rms (GwyLine *line,
                       gint pos,
                       gint len);

Computes root mean square value of a part of a data line.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

Root mean square deviation of heights within a given interval

### gwy_line_part_tan_beta0()

    gdouble
    gwy_line_part_tan_beta0 (GwyLine *line,
                             gint pos,
                             gint len);

Computes root mean square slope in a part of a data line.

This is the root mean square of value derivatives, it is also proportional to the second derivative of both HHCF and ACF at zero.

This roughness quantity is also known as Dq.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

Root mean square slope within a given interval.

### gwy_line_part_variation()

    gdouble
    gwy_line_part_variation (GwyLine *line,
                             gint pos,
                             gint len);

Computes the total variation of a part of a data line.

The total variation is estimated as the integral of the absolute value of local gradient. For one dimensional data, the variation reduces to the integral of absolute value of the derivative. Its units are thus the same as the value units of the line. See also `gwy_field_area_get_variation()` for some more discussion.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

The total variation within a given interval.

### gwy_line_part_sum()

    gdouble
    gwy_line_part_sum (GwyLine *line,
                       gint pos,
                       gint len);

Computes sum of all values in a part of a data line.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

Sum of all values within the interval.

### gwy_line_part_ra()

    gdouble
    gwy_line_part_ra (GwyLine *line,
                      gint pos,
                      gint len);

Computes mean absolute deviation value of a part of a data line.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

Mean absolute deviation of heights within a given interval.

### gwy_line_part_skew()

    gdouble
    gwy_line_part_skew (GwyLine *line,
                        gint pos,
                        gint len);

Computes skew value of a part of a data line.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

Skew of heights within a given interval.

### gwy_line_part_kurtosis()

    gdouble
    gwy_line_part_kurtosis (GwyLine *line,
                            gint pos,
                            gint len);

Computes kurtosis value of a part of a data line.

Note the kurtosis returned by this function returns is the excess kurtosis which is zero for the Gaussian distribution (not 3).

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

Kurtosis of heights within a given interval.

### gwy_line_modus()

    gdouble
    gwy_line_modus (GwyLine *line,
                    gint histogram_steps);

Finds approximate modus of a data line.

See `gwy_line_part_modus()` for details and caveats.

#### Parameters

line | A data line. |
histogram_steps | Number of histogram steps used for modus searching, pass a nonpositive number to autosize. |

#### Returns

The modus.

### gwy_line_part_modus()

    gdouble
    gwy_line_part_modus (GwyLine *line,
                         gint pos,
                         gint len,
                         gint histogram_steps);

Finds approximate modus of a data line part.

As each number in the data line is usually unique, this function does not return modus of the data itself, but modus of a histogram.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |
histogram_steps | Number of histogram steps used for modus searching, pass a nonpositive number to autosize. |

#### Returns

The modus.

### gwy_line_median()

    gdouble
    gwy_line_median (GwyLine *line);

Finds median of a data line.

#### Parameters

line | A data line. |

#### Returns

The median.

### gwy_line_part_median()

    gdouble
    gwy_line_part_median (GwyLine *line,
                          gint pos,
                          gint len);

Finds median of a data line part.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

#### Returns

The median.

### gwy_line_length()

    gdouble
    gwy_line_length (GwyLine *line);

Calculates physical length of a data line.

The length is calculated from approximation by straight segments between values.

#### Parameters

line | A data line to compute length of. |

#### Returns

The line length.

### gwy_line_xpm()

    gdouble
    gwy_line_xpm (GwyLine *line,
                  gint m,
                  gint k);

Calculates a peak roughness quantity for a data line.

Depending on `m` and `k` , the function can calculate Average Maximum Profile Peak Height `Rpm` or Maximum Profile Peak Height `Rp` , `Pp` , `Wp` .

#### Parameters

line | A data line. |
m | Number of sampling lengths. |
k | Number of peaks to consider. |

#### Returns

The peak roughness quantity defined by `m` and `k` .

### gwy_line_xvm()

    gdouble
    gwy_line_xvm (GwyLine *line,
                  gint m,
                  gint k);

Calculates a valley roughness quantity for a data line.

Depending on `m` and `k` , the function can calculate Average Maximum Profile Valley Depth `Rvm` or Maximum Profile Peak Depth `Rv` , `Pv` , `Wv` .

#### Parameters

line | A data line. |
m | Number of sampling lengths. |
k | Number of valleys to consider. |

#### Returns

The valley roughness quantity defined by `m` and `k` .

### gwy_line_xtm()

    gdouble
    gwy_line_xtm (GwyLine *line,
                  gint m,
                  gint k);

Calculates a total roughness quantity for a data line.

The total quantity is just the sum of the corresponding quantities obtained by `gwy_line_xpm()` and `gwy_line_xvm()`.

#### Parameters

line | A data line. |
m | Number of sampling lengths. |
k | Number of peaks and valleys to consider. |

#### Returns

The total roughness quantity defined by `m` and `k` .

### gwy_line_kth_peaks()

    gint
    gwy_line_kth_peaks (GwyLine *line,
                        gint m,
                        gint rank,
                        gboolean peaks,
                        gboolean average,
                        gdouble pthreshold,
                        gdouble vthreshold,
                        gdouble *peakvalues);

Calculate k-th largers peaks or valleys in a data line split into given number of sampling lengths.

This is a general function that can be used as the base for various standard roughness quantities such as Rp, Rpm, Rv, Rvm or R3z. It is assumed the line is already levelled, the form removed, etc.

See `gwy_line_count_peaks()` for the description what is considered a peak.

For larger thresholds and/or short lines some sampling lengths may contain fewer than the requested number of peaks. If there are any peaks at all, the smallest peak height (even though it is not `rank` -th) is used. If there are no peaks, a large negative value is stored in the corresponding `peakvalues` item.

#### Parameters

line | A data line. |
m | Number of sampling lengths the line is split into. |
rank | Rank of the peak to find. One means the highest peak, three the third highest, etc. |
peaks | `TRUE` for peaks, `FALSE` for valleys. If you pass `FALSE`, swap the meanings of peaks and valleys in the description. Valley depths are positive. |
average | Calculate the average of the first `rank` peaks instead of the height of `rank` -th peak. |
pthreshold | Peak height threshold. Peaks must stick above this threshold. |
vthreshold | Valley depth threshold. Valleys must fall below this threshold. The depth is a positive value. |
peakvalues | Array of length at least `m` where the peak heights in each sampling length should be stored. |

#### Returns

The actual number of peaks found (i.e. number of positive values filled in `peakvalues` ). If it is smaller than `m` , some sampling lengths did not contain enough peaks.

### gwy_line_count_peaks()

    gint
    gwy_line_count_peaks (GwyLine *line,
                          gboolean peaks,
                          gdouble pthreshold,
                          gdouble vthreshold);

Counts peaks or valleys defined by thresholds in a data line.

Peak is defined as a part of the profile that extends above the peak threshold and is separarted by valleys that extend below the valley threshold. For non-zero thresholds there may be parts between that are neither peaks not valleys because the local maxima in them are insignificant.

In either case, values of `pthreshold` and `vthreshold` must be non-negative. Usually one passes the same value for both.

#### Parameters

line | A data line. |
peaks | `TRUE` for peaks, `FALSE` for valleys. If you pass `FALSE`, swap the meanings of peaks and valleys in the description. Valley depths are positive. |
pthreshold | Peak height threshold. Peaks must stick above this threshold. |
vthreshold | Valley depth threshold. Valleys must fall below this threshold. |

#### Returns

The number of peaks found.

### gwy_line_distribution()

    void
    gwy_line_distribution (GwyLine *line,
                           GwyLine *distribution,
                           gdouble ymin,
                           gdouble ymax,
                           gboolean normalize_to_unity,
                           gint nstats);

Calculates the distribution of data line values.

This function is quite similar to `gwy_line_dh()`, the differences are: output normalization (chosen to make the integral unity), output units (again set to make the integral unity), automated binning.

Note the `i` -th bin is [`i` *`dx` +`off` ,(`i` +1)*`dx` +`off` ] so the central value you probably want to use for plotting is (`i` +0.5)*`dx` +`off` (where `dx` is the `distribution` data line pixel size, `off` is its offset).

If all values are equal and `ymin` , `ymax` are not explictly specified, the range is chosen as [`v` -|`v` |/2,`v` +|`v` /2] where `v` is the unique value, except when `v` =0, in which case the range is set to [-1,1].

#### Parameters

line | A data line. |
distribution | Data line to put the distribution of `line` values to. It will be resampled to `nstats` samples (or the automatically chosen number of bins). |
ymin | Start of value range, pass `ymin` = `ymax` = 0.0 for the full range. |
ymax | End of value range. |
normalize_to_unity | `TRUE` to normalize the integral to unity (including setting y-units of output to the inverse of x-units), `FALSE` to keep plain counts in the output (and set y-units to none). |
nstats | The requested number of histogram bins, pass a non-positive number to automatically choose a suitable number of bins. |

### gwy_line_height_dist()

    void
    gwy_line_height_dist (GwyLine *line,
                          GwyLine *target_line,
                          gdouble ymin,
                          gdouble ymax,
                          gint nsteps);

Computes distribution of heights in interval [`ymin` , `ymax` ).

If the interval is (0, 0) it computes the distribution from real data minimum and maximum value.

#### Parameters

line | A data line. |
target_line | Data line to store height distribution function to. It will be resized to `nsteps` . |
ymin | Height distribution minimum value. |
ymax | Height distribution maximum value. |
nsteps | Number of histogram steps. |

### gwy_line_angle_dist()

    void
    gwy_line_angle_dist (GwyLine *line,
                         GwyLine *target_line,
                         gdouble ymin,
                         gdouble ymax,
                         gint nsteps);

Computes distribution of angles in interval [`ymin` , `ymax` ).

If the interval is (0, 0) it computes the distribution from real data minimum and maximum angle value.

#### Parameters

line | A data line. |
target_line | Data line to store angle distribution function to. |
ymin | Angle distribution minimum value. |
ymax | Angle distribution maximum value. |
nsteps | Mumber of angular histogram steps. |

### gwy_line_acf()

    void
    gwy_line_acf (GwyLine *line,
                  GwyLine *target_line);

Coputes autocorrelation function and stores the values in `target_line`

#### Parameters

line | A data line. |
target_line | Data line to store autocorrelation function to. It will be resized to `line` size. |

### gwy_line_hhcf()

    void
    gwy_line_hhcf (GwyLine *line,
                   GwyLine *target_line);

Computes height-height correlation function and stores results in `target_line` .

#### Parameters

line | A data line. |
target_line | Data line to store height-height function to. It will be resized to `line` size. |

### gwy_line_psdf()

    void
    gwy_line_psdf (GwyLine *line,
                   GwyLine *target_line,
                   GwyWindowingType windowing);

Calculates the power spectral density function of a data line.

#### Parameters

line | A data line. |
target_line | Data line to store power spectral density function to. It will be resized to `line` size. |
windowing | Windowing method to use. |

## Types and Values

### enum GwyLineStatQuantity

Line statistical quantities to be requested with `gwy_field_area_get_line_stats()`.

#### Members

GWY_LINE_STAT_MEAN | Mean value. |
GWY_LINE_STAT_MEDIAN | Median. |
GWY_LINE_STAT_MINIMUM | Minimum value. |
GWY_LINE_STAT_MAXIMUM | Maximum value. |
GWY_LINE_STAT_RMS | Root mean square of deviations from the mean value. |
GWY_LINE_STAT_LENGTH | Line length. |
GWY_LINE_STAT_SLOPE | Overall line slope. |
GWY_LINE_STAT_TAN_BETA0 | Root mean square slope. |
GWY_LINE_STAT_RA | Arithmetic mean surface roughness. |
GWY_LINE_STAT_RZ | Maximum height of the roughness profile. |
GWY_LINE_STAT_RT | Total height of the roughness profile. |
GWY_LINE_STAT_SKEW | Line skew. |
GWY_LINE_STAT_KURTOSIS | Line excess kurtosis (which is 0 for a Gaussaian distrubution, not 3). |
GWY_LINE_STAT_RANGE | Difference between maximum and minimum value. |
GWY_LINE_STAT_VARIATION | Variation (integral of absolute value). |
GWY_LINE_STAT_MINPOS | Minimum position along the line. |
GWY_LINE_STAT_MAXPOS | Maximum position along the line. |