## linestats

linestats — One-dimensional statistical functions

## Synopsis

    #include <libprocess/gwyprocess.h>

    gdouble             gwy_data_line_get_max               (GwyDataLine *data_line);
    gdouble             gwy_data_line_get_min               (GwyDataLine *data_line);
    gdouble             gwy_data_line_get_avg               (GwyDataLine *data_line);
    gdouble             gwy_data_line_get_rms               (GwyDataLine *data_line);
    gdouble             gwy_data_line_get_tan_beta0         (GwyDataLine *data_line);
    gdouble             gwy_data_line_get_sum               (GwyDataLine *data_line);
    gdouble             gwy_data_line_part_get_max          (GwyDataLine *data_line,
                                                             gint from,
                                                             gint to);
    gdouble             gwy_data_line_part_get_min          (GwyDataLine *data_line,
                                                             gint from,
                                                             gint to);
    gdouble             gwy_data_line_part_get_avg          (GwyDataLine *data_line,
                                                             gint from,
                                                             gint to);
    gdouble             gwy_data_line_part_get_rms          (GwyDataLine *data_line,
                                                             gint from,
                                                             gint to);
    gdouble             gwy_data_line_part_get_tan_beta0    (GwyDataLine *data_line,
                                                             gint from,
                                                             gint to);
    gdouble             gwy_data_line_part_get_sum          (GwyDataLine *data_line,
                                                             gint from,
                                                             gint to);
    gdouble             gwy_data_line_get_modus             (GwyDataLine *data_line,
                                                             gint histogram_steps);
    gdouble             gwy_data_line_part_get_modus        (GwyDataLine *data_line,
                                                             gint from,
                                                             gint to,
                                                             gint histogram_steps);
    gdouble             gwy_data_line_get_median            (GwyDataLine *data_line);
    gdouble             gwy_data_line_part_get_median       (GwyDataLine *data_line,
                                                             gint from,
                                                             gint to);
    gdouble             gwy_data_line_get_length            (GwyDataLine *data_line);
    void                gwy_data_line_distribution          (GwyDataLine *data_line,
                                                             GwyDataLine *distribution,
                                                             gdouble ymin,
                                                             gdouble ymax,
                                                             gboolean normalize_to_unity,
                                                             gint nstats);
    void                gwy_data_line_dh                    (GwyDataLine *data_line,
                                                             GwyDataLine *target_line,
                                                             gdouble ymin,
                                                             gdouble ymax,
                                                             gint nsteps);
    void                gwy_data_line_cdh                   (GwyDataLine *data_line,
                                                             GwyDataLine *target_line,
                                                             gdouble ymin,
                                                             gdouble ymax,
                                                             gint nsteps);
    void                gwy_data_line_da                    (GwyDataLine *data_line,
                                                             GwyDataLine *target_line,
                                                             gdouble ymin,
                                                             gdouble ymax,
                                                             gint nsteps);
    void                gwy_data_line_cda                   (GwyDataLine *data_line,
                                                             GwyDataLine *target_line,
                                                             gdouble ymin,
                                                             gdouble ymax,
                                                             gint nsteps);
    void                gwy_data_line_acf                   (GwyDataLine *data_line,
                                                             GwyDataLine *target_line);
    void                gwy_data_line_hhcf                  (GwyDataLine *data_line,
                                                             GwyDataLine *target_line);
    void                gwy_data_line_psdf                  (GwyDataLine *data_line,
                                                             GwyDataLine *target_line,
                                                             gint windowing,
                                                             gint interpolation);

## Description

## Details

### gwy_data_line_get_max ()

    gdouble             gwy_data_line_get_max               (GwyDataLine *data_line);

Finds the maximum value of a data line.

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

`data_line` : | A data line.
Returns : | The minimum value.

### gwy_data_line_get_avg ()

    gdouble             gwy_data_line_get_avg               (GwyDataLine *data_line);

Computes average value of a data line.

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

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

`data_line` : | A data line.
Returns : | Root mean square slope within a given interval.

Since 2.2

### gwy_data_line_get_sum ()

    gdouble             gwy_data_line_get_sum               (GwyDataLine *data_line);

Computes sum of all values in a data line.

`data_line` : | A data line.
Returns : | sum of all the values.

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

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

`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_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.

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

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

`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_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.

`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_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.

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

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

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

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

`data_line` : | A data line to compute length of.
Returns : | The line length.

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

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

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

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

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

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

`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`

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

`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.7 it destroyed the input data and did not set the output units properly.

`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 reampling is performed.