Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

linestats (HEAD)

linestats — One-dimensional statistical functions

Functions

gdouble gwy_data_line_get_max ()
gdouble gwy_data_line_get_min ()
void gwy_data_line_get_min_max ()
gdouble gwy_data_line_min_pos_i ()
gdouble gwy_data_line_max_pos_i ()
gdouble gwy_data_line_min_pos_r ()
gdouble gwy_data_line_max_pos_r ()
gdouble gwy_data_line_get_avg ()
gdouble gwy_data_line_get_rms ()
gdouble gwy_data_line_get_tan_beta0 ()
gdouble gwy_data_line_get_variation ()
gdouble gwy_data_line_get_sum ()
gdouble gwy_data_line_get_ra ()
gdouble gwy_data_line_get_skew ()
gdouble gwy_data_line_get_kurtosis ()
gdouble gwy_data_line_part_get_max ()
gdouble gwy_data_line_part_get_min ()
void gwy_data_line_part_get_min_max ()
gdouble gwy_data_line_part_get_avg ()
gdouble gwy_data_line_part_get_rms ()
gdouble gwy_data_line_part_get_tan_beta0 ()
gdouble gwy_data_line_part_get_variation ()
gdouble gwy_data_line_part_get_sum ()
gdouble gwy_data_line_part_get_ra ()
gdouble gwy_data_line_part_get_skew ()
gdouble gwy_data_line_part_get_kurtosis ()
gdouble gwy_data_line_get_modus ()
gdouble gwy_data_line_part_get_modus ()
gdouble gwy_data_line_get_median ()
gdouble gwy_data_line_part_get_median ()
gdouble gwy_data_line_get_length ()
gdouble gwy_data_line_get_xpm ()
gdouble gwy_data_line_get_xvm ()
gdouble gwy_data_line_get_xtm ()
gint gwy_data_line_get_kth_peaks ()
gint gwy_data_line_count_peaks ()
void gwy_data_line_distribution ()
void gwy_data_line_dh ()
void gwy_data_line_cdh ()
void gwy_data_line_da ()
void gwy_data_line_cda ()
void gwy_data_line_acf ()
void gwy_data_line_hhcf ()
void gwy_data_line_psdf ()

Includes

#include <libprocess/gwyprocess.h>

Description

Functions

gwy_data_line_get_max ()

gdouble
gwy_data_line_get_max (GwyDataLine *data_line);

Finds the maximum value of a data line.

Parameters

data_line

A data line.

 

Returns

The maximum value.

gwy_data_line_get_min ()

gdouble
gwy_data_line_get_min (GwyDataLine *data_line);

Finds the minimum value of a data line.

Parameters

data_line

A data line.

 

Returns

The minimum value.

gwy_data_line_get_min_max ()

void
gwy_data_line_get_min_max (GwyDataLine *data_line,
                           gdouble *min,
                           gdouble *max);

Finds the minimum and maximum values of a data line.

Since 2.42

Parameters

data_line

A data line.

 

min

Location to store minimum to.

 

max

Location to store maximum to.

 

gwy_data_line_min_pos_i ()

gdouble
gwy_data_line_min_pos_i (GwyDataLine *data_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

data_line

A data line.

 

Returns

The minimum pixel position.

Since 2.48

gwy_data_line_max_pos_i ()

gdouble
gwy_data_line_max_pos_i (GwyDataLine *data_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

data_line

A data line.

 

Returns

The maximum pixel position.

Since 2.48

gwy_data_line_min_pos_r ()

gdouble
gwy_data_line_min_pos_r (GwyDataLine *data_line);

Finds the real minimum position in a data line.

Parameters

data_line

A data line.

 

Returns

Real position for the minimum.

Since 2.48

gwy_data_line_max_pos_r ()

gdouble
gwy_data_line_max_pos_r (GwyDataLine *data_line);

Finds the real maximum position in a data line.

Parameters

data_line

A data line.

 

Returns

Real position for the maximum.

Since 2.48

gwy_data_line_get_avg ()

gdouble
gwy_data_line_get_avg (GwyDataLine *data_line);

Computes average value of a data line.

Parameters

data_line

A data line.

 

Returns

Average value

gwy_data_line_get_rms ()

gdouble
gwy_data_line_get_rms (GwyDataLine *data_line);

Computes root mean square value of a data line.

Parameters

data_line

A data line.

 

Returns

Root mean square deviation of values.

gwy_data_line_get_tan_beta0 ()

gdouble
gwy_data_line_get_tan_beta0 (GwyDataLine *data_line);

Computes root mean square slope in a data line.

Parameters

data_line

A data line.

 

Returns

Root mean square slope within a given interval.

Since: 2.2

gwy_data_line_get_variation ()

gdouble
gwy_data_line_get_variation (GwyDataLine *data_line);

Computes the total variation of a data line.

See gwy_data_line_part_get_variation() for definition and discussion.

Parameters

data_line

A data line.

 

Returns

The total variation.

Since: 2.42

gwy_data_line_get_sum ()

gdouble
gwy_data_line_get_sum (GwyDataLine *data_line);

Computes sum of all values in a data line.

Parameters

data_line

A data line.

 

Returns

sum of all the values.

gwy_data_line_get_ra ()

gdouble
gwy_data_line_get_ra (GwyDataLine *data_line);

Computes the mean absolute deviation of a data line.

Parameters

data_line

A data line.

 

Returns

The mean absolute deviation of height values.

Since: 2.42

gwy_data_line_get_skew ()

gdouble
gwy_data_line_get_skew (GwyDataLine *data_line);

Computes the skew of a data line.

Parameters

data_line

A data line.

 

Returns

The skew of height values.

Since: 2.42

gwy_data_line_get_kurtosis ()

gdouble
gwy_data_line_get_kurtosis (GwyDataLine *data_line);

Computes the kurtosis of a data line.

Parameters

data_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).

Since: 2.42

gwy_data_line_part_get_max ()

gdouble
gwy_data_line_part_get_max (GwyDataLine *data_line,
                            gint from,
                            gint to);

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

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

Maximum within given interval.

gwy_data_line_part_get_min ()

gdouble
gwy_data_line_part_get_min (GwyDataLine *data_line,
                            gint from,
                            gint to);

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

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

Minimum within given interval.

gwy_data_line_part_get_min_max ()

void
gwy_data_line_part_get_min_max (GwyDataLine *data_line,
                                gint from,
                                gint to,
                                gdouble *min,
                                gdouble *max);

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

Since 2.42

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

min

Location to store minimum to.

 

max

Location to store maximum to.

 

gwy_data_line_part_get_avg ()

gdouble
gwy_data_line_part_get_avg (GwyDataLine *data_line,
                            gint from,
                            gint to);

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

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

Average value within given interval.

gwy_data_line_part_get_rms ()

gdouble
gwy_data_line_part_get_rms (GwyDataLine *data_line,
                            gint from,
                            gint to);

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

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

Root mean square deviation of heights within a given interval

gwy_data_line_part_get_tan_beta0 ()

gdouble
gwy_data_line_part_get_tan_beta0 (GwyDataLine *data_line,
                                  gint from,
                                  gint to);

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

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

Root mean square slope within a given interval.

Since: 2.2

gwy_data_line_part_get_variation ()

gdouble
gwy_data_line_part_get_variation (GwyDataLine *data_line,
                                  gint from,
                                  gint to);

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_data_field_area_get_variation() for some more discussion.

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

The total variation within a given interval.

Since: 2.42

gwy_data_line_part_get_sum ()

gdouble
gwy_data_line_part_get_sum (GwyDataLine *data_line,
                            gint from,
                            gint to);

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

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

Sum of all values within the interval.

gwy_data_line_part_get_ra ()

gdouble
gwy_data_line_part_get_ra (GwyDataLine *data_line,
                           gint from,
                           gint to);

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

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

Mean absolute deviation of heights within a given interval.

gwy_data_line_part_get_skew ()

gdouble
gwy_data_line_part_get_skew (GwyDataLine *data_line,
                             gint from,
                             gint to);

Computes skew value of a part of a data line.

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

Skew of heights within a given interval.

gwy_data_line_part_get_kurtosis ()

gdouble
gwy_data_line_part_get_kurtosis (GwyDataLine *data_line,
                                 gint from,
                                 gint to);

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

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

Kurtosis of heights within a given interval.

gwy_data_line_get_modus ()

gdouble
gwy_data_line_get_modus (GwyDataLine *data_line,
                         gint histogram_steps);

Finds approximate modus of a data line.

See gwy_data_line_part_get_modus() for details and caveats.

Parameters

data_line

A data line.

 

histogram_steps

Number of histogram steps used for modus searching, pass a nonpositive number to autosize.

 

Returns

The modus.

gwy_data_line_part_get_modus ()

gdouble
gwy_data_line_part_get_modus (GwyDataLine *data_line,
                              gint from,
                              gint to,
                              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

data_line

A data line.

 

from

The index in data_line to start from (inclusive).

 

to

The index in data_line to stop (noninclusive).

 

histogram_steps

Number of histogram steps used for modus searching, pass a nonpositive number to autosize.

 

Returns

The modus.

gwy_data_line_get_median ()

gdouble
gwy_data_line_get_median (GwyDataLine *data_line);

Finds median of a data line.

Parameters

data_line

A data line.

 

Returns

The median.

Since: 2.1

gwy_data_line_part_get_median ()

gdouble
gwy_data_line_part_get_median (GwyDataLine *data_line,
                               gint from,
                               gint to);

Finds median of a data line part.

Parameters

data_line

A data line.

 

from

The index in data_line to start from (inclusive).

 

to

The index in data_line to stop (noninclusive).

 

Returns

The median.

Since: 2.1

gwy_data_line_get_length ()

gdouble
gwy_data_line_get_length (GwyDataLine *data_line);

Calculates physical length of a data line.

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

Parameters

data_line

A data line to compute length of.

 

Returns

The line length.

gwy_data_line_get_xpm ()

gdouble
gwy_data_line_get_xpm (GwyDataLine *data_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

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

Since: 2.42

gwy_data_line_get_xvm ()

gdouble
gwy_data_line_get_xvm (GwyDataLine *data_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

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

Since: 2.42

gwy_data_line_get_xtm ()

gdouble
gwy_data_line_get_xtm (GwyDataLine *data_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_data_line_get_xpm() and gwy_data_line_get_xvm().

Parameters

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

Since: 2.42

gwy_data_line_get_kth_peaks ()

gint
gwy_data_line_get_kth_peaks (GwyDataLine *data_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_data_line_count_peaks() for the description what is considered a peak.

For larger thresholds and/or short lines some sampling lengths may not contain 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

data_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 highers, 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 in peakvalues ).

Since: 2.50

gwy_data_line_count_peaks ()

gint
gwy_data_line_count_peaks (GwyDataLine *data_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

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

Since: 2.50

gwy_data_line_distribution ()

void
gwy_data_line_distribution (GwyDataLine *data_line,
                            GwyDataLine *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_data_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

data_line

A data line.

 

distribution

Data line to put the distribution of data_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.

 

Since: 2.8

gwy_data_line_dh ()

void
gwy_data_line_dh (GwyDataLine *data_line,
                  GwyDataLine *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

data_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_data_line_cdh ()

void
gwy_data_line_cdh (GwyDataLine *data_line,
                   GwyDataLine *target_line,
                   gdouble ymin,
                   gdouble ymax,
                   gint nsteps);

Computes cumulative distribution of heighs in interval [ymin , ymax ).

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

Parameters

data_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_data_line_da ()

void
gwy_data_line_da (GwyDataLine *data_line,
                  GwyDataLine *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

data_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_data_line_cda ()

void
gwy_data_line_cda (GwyDataLine *data_line,
                   GwyDataLine *target_line,
                   gdouble ymin,
                   gdouble ymax,
                   gint nsteps);

Computes cumulative 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

data_line

A data line.

 

target_line

Data line to store angle distribution function to. It will be resized to nsteps .

 

ymin

Angle distribution minimum value.

 

ymax

Angle distribution maximum value.

 

nsteps

Number of angular histogram steps.

 

gwy_data_line_acf ()

void
gwy_data_line_acf (GwyDataLine *data_line,
                   GwyDataLine *target_line);

Coputes autocorrelation function and stores the values in target_line

Up to version 2.53 it did not set the output units properly.

Parameters

data_line

A data line.

 

target_line

Data line to store autocorrelation function to. It will be resized to data_line size.

 

gwy_data_line_hhcf ()

void
gwy_data_line_hhcf (GwyDataLine *data_line,
                    GwyDataLine *target_line);

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

Up to version 2.53 it did not set the output units properly.

Parameters

data_line

A data line.

 

target_line

Data line to store height-height function to. It will be resized to data_line size.

 

gwy_data_line_psdf ()

void
gwy_data_line_psdf (GwyDataLine *data_line,
                    GwyDataLine *target_line,
                    gint windowing,
                    gint interpolation);

Calculates the power spectral density function of a data line.

Up to version 2.45 it destroyed the input data and did not set the output units properly.

Parameters

data_line

A data line.

 

target_line

Data line to store power spectral density function to. It will be resized to data_line size.

 

windowing

Windowing method to use.

 

interpolation

Interpolation type. Ignored since 2.8 as no resampling is performed.

 
© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS