Module gwy :: Class DataLine
[hide private]
[frames] | no frames]

Class DataLine

source code

One-dimensional data representation

DataLine represents 1D data arrays in Gwyddion. It is used for most of the data processing functions connected with 1D data, graphs, etc.

Instance Methods [hide private]
 
__init__(res, real, nullme)
Creates a new data line.
source code
 
check_compatibility(data_line2, check)
Checks whether two data lines are compatible.
source code
 
correct_laplace(mask_line)
Fills missing values in a data line using Laplace data correction.
source code
 
copy_units_to_data_field(data_field)
Sets lateral and value units of a data field to match a data line.
source code
 
new_alike(nullme)
Creates a new data line similar to an existing one.
source code
 
data_changed()
Emits signal "data_changed" on a data line.
source code
 
new_resampled(res, interpolation)
Creates a new data line by resampling an existing one.
source code
 
resample(res, interpolation)
Resamples a data line.
source code
 
resize(from_, to)
Resizes (crops) a data line.
source code
 
part_extract(from_, len)
Extracts a part of a data line to a new data line.
source code
 
copy(b)
Copies the contents of a data line to another already allocated data line of the same size.
source code
 
get_res()
Gets the number of data points in a data line.
source code
 
get_real()
Gets the physical size of a data line.
source code
 
set_real(real)
Sets the real data line size.
source code
 
get_offset()
Gets the offset of data line origin.
source code
 
set_offset(offset)
Sets the offset of a data line origin.
source code
 
get_si_unit_x()
Returns lateral SI unit of a data line.
source code
 
get_si_unit_y()
Returns value SI unit of a data line.
source code
 
set_si_unit_x(si_unit)
Sets the SI unit corresponding to the lateral (X) dimension of a data line.
source code
 
set_si_unit_y(si_unit)
Sets the SI unit corresponding to the "height" (Z) dimension of a data line.
source code
 
get_value_format_x(style)
Finds value format good for displaying coordinates of a data line.
source code
 
get_value_format_y(style)
Finds value format good for displaying values of a data line.
source code
 
itor(pixpos)
Transforms pixel coordinate to real (physical) coordinate.
source code
 
rtoi(realpos)
Transforms real (physical) coordinate to pixel coordinate.
source code
 
get_val(i)
Gets value at given position in a data line.
source code
 
set_val(i, value)
Sets the value at given position in a data line.
source code
 
get_dval(x, interpolation)
Gets interpolated value at arbitrary data line point indexed by pixel coordinates.
source code
 
get_dval_real(x, interpolation)
Gets interpolated value at arbitrary data line point indexed by real coordinates.
source code
 
invert(x, z)
Reflects amd/or inverts a data line.
source code
 
clear()
Fills a data line with zeroes.
source code
 
fill(value)
Fills a data line with specified value.
source code
 
multiply(value)
Multiplies all values in a data line with a specified value.
source code
 
add(value)
Adds a specified value to all values in a data line.
source code
 
part_clear(from_, to)
Fills a data line part with zeroes.
source code
 
part_fill(from_, to, value)
Fills specified part of data line with specified number
source code
 
part_multiply(from_, to, value)
Multiplies all values in a part of data line by specified value.
source code
 
part_add(from_, to, value)
Adds specified value to all values in a part of a data line.
source code
 
threshold(threshval, bottom, top)
Sets all the values to bottom or top value depending on whether the original values are below or above threshold value
source code
 
part_threshold(from_, to, threshval, bottom, top)
Sets all the values within interval to bottom or top value depending on whether the original values are below or above threshold value.
source code
 
get_line_coeffs()
Finds line leveling coefficients.
source code
 
line_level(av, bv)
Performs line leveling.
source code
 
rotate(angle, interpolation)
Performs line rotation.
source code
 
line_rotate(angle, interpolation)
Performs line rotation.
source code
 
get_der(i)
Computes central derivaltion at given index in a data line.
source code
 
cumulate()
Transforms a distribution in a data line to cummulative distribution.
source code
 
sqrt()
Applies sqrt() to each element in a data line.
source code
 
dwt(wt_coefs, direction, minsize)
Performs steps of the wavelet decomposition.
source code
 
fft(isrc, rdest, idest, windowing, direction, interpolation, preserverms, level)
Calculates Fast Fourier Transform of a data line.
source code
 
part_fft(isrc, rdest, idest, from_, len, windowing, direction, interpolation, preserverms, level)
Calculates Fast Fourier Transform of a part of a data line.
source code
 
fft_raw(isrc, rdest, idest, direction)
Calculates Fast Fourier Transform of a data line.
source code
 
get_max()
Finds the maximum value of a data line.
source code
 
get_min()
Finds the minimum value of a data line.
source code
 
get_min_max()
Finds the minimum and maximum values of a data line.
source code
 
min_pos_i() source code
 
max_pos_i() source code
 
min_pos_r() source code
 
max_pos_r() source code
 
get_avg()
Computes average value of a data line.
source code
 
get_rms()
Computes root mean square value of a data line.
source code
 
get_tan_beta0()
Computes root mean square slope in a data line.
source code
 
get_variation()
Computes the total variation of a data line.
source code
 
get_sum()
Computes sum of all values in a data line.
source code
 
get_ra()
Computes the mean absolute deviation of a data line.
source code
 
get_skew()
Computes the skew of a data line.
source code
 
get_kurtosis()
Computes the kurtosis of a data line.
source code
 
part_get_max(from_, to)
Finds the maximum value of a part of a data line.
source code
 
part_get_min(from_, to)
Finds the minimum value of a part of a data line.
source code
 
part_get_min_max(from_, to)
Finds the minimum and maximum values of a part of a data line.
source code
 
part_get_avg(from_, to)
Computes mean value of all values in a part of a data line.
source code
 
part_get_rms(from_, to)
Computes root mean square value of a part of a data line.
source code
 
part_get_tan_beta0(from_, to)
Computes root mean square slope in a part of a data line.
source code
 
part_get_variation(from_, to)
Computes the total variation of a part of a data line.
source code
 
part_get_sum(from_, to)
Computes sum of all values in a part of a data line.
source code
 
part_get_ra(from_, to)
Computes mean absolute deviation value of a part of a data line.
source code
 
part_get_skew(from_, to)
Computes skew value of a part of a data line.
source code
 
part_get_kurtosis(from_, to)
Computes kurtosis value of a part of a data line.
source code
 
get_modus(histogram_steps)
Finds approximate modus of a data line.
source code
 
part_get_modus(from_, to, histogram_steps)
Finds approximate modus of a data line part.
source code
 
get_median()
Finds median of a data line.
source code
 
part_get_median(from_, to)
Finds median of a data line part.
source code
 
get_length()
Calculates physical length of a data line.
source code
 
get_xpm(m, k)
Calculates a peak roughness quantity for a data line.
source code
 
get_xvm(m, k)
Calculates a valley roughness quantity for a data line.
source code
 
get_xtm(m, k)
Calculates a total roughness quantity for a data line.
source code
 
distribution(distribution, ymin, ymax, normalize_to_unity, nstats)
Calculates the distribution of data line values.
source code
 
dh(target_line, ymin, ymax, nsteps)
Computes distribution of heights in interval [ymin, ymax).
source code
 
cdh(target_line, ymin, ymax, nsteps)
Computes cumulative distribution of heighs in interval [ymin, ymax).
source code
 
da(target_line, ymin, ymax, nsteps)
Computes distribution of angles in interval [ymin, ymax).
source code
 
cda(target_line, ymin, ymax, nsteps)
Computes cumulative distribution of angles in interval [ymin, ymax).
source code
 
acf(target_line)
Coputes autocorrelation function and stores the values in target_line
source code
 
hhcf(target_line)
Computes height-height correlation function and stores results in target_line.
source code
 
psdf(target_line, windowing, interpolation)
Calculates the power spectral density function of a data line.
source code
 
get_data()
Extract the data of a data line.
source code
 
set_data(data)
Sets the entire contents of a data line.
source code
 
part_fit_polynom(n, from_, to)
Fits a polynomial through a part of a data line.
source code
 
fit_polynom(n)
Fits a polynomial through a data line.
source code
 
part_subtract_polynom(coeffs, from_, to)
Subtracts a polynomial from a part of a data line.
source code
 
subtract_polynom(coeffs)
Subtracts a polynomial from a data line.
source code
 
duplicate()
Convenience macro doing gwy_serializable_duplicate() with all the necessary typecasting.
source code
 
get_data_pointer()
Gets pointer to data which the data line contains.
source code
Method Details [hide private]

__init__(res, real, nullme)
(Constructor)

source code 

Creates a new data line.

Parameters:
  • res - Resolution, i.e., the number of samples. (int)
  • real - Real physical dimension. (float)
  • nullme - Whether the data line should be initialized to zeroes. If False, the data will not be initialized. (bool)
Returns:
A newly created data line. (DataLine)

check_compatibility(data_line2, check)

source code 

Checks whether two data lines are compatible.

Parameters:
  • data_line2 - Another data line. (DataLine)
  • check - The compatibility tests to perform. Expected values: DATA_COMPATIBILITY_RES, DATA_COMPATIBILITY_REAL, DATA_COMPATIBILITY_MEASURE, DATA_COMPATIBILITY_LATERAL, DATA_COMPATIBILITY_VALUE, DATA_COMPATIBILITY_ALL. (DataCompatibilityFlags)
Returns:
Zero if all tested properties are compatible. Flags corresponding to failed tests if data lines are not compatible. (DataCompatibilityFlags)

correct_laplace(mask_line)

source code 

Fills missing values in a data line using Laplace data correction.

Both data lines must have the same number of values.

For one-dimensional data the missing data interpolation is explicit. Interior missing segments are filled with linear dependence between the edge points. Missing segments with one end open are filled with the edge value.

Parameters:
  • mask_line - Mask of places to be corrected. (DataLine)
Returns:
True if the line contained any data at all. If there are no data the False is returned and data_line is filled with zeros. (bool)

Since: 2.45

copy_units_to_data_field(data_field)

source code 

Sets lateral and value units of a data field to match a data line.

Parameters:
  • data_field - A data field to set units of. (DataField)

new_alike(nullme)

source code 

Creates a new data line similar to an existing one.

Use DataLine.duplicate() if you want to copy a data line including data.

Parameters:
  • nullme - Whether the data line should be initialized to zeroes. If False, the data will not be initialized. (bool)
Returns:
A newly created data line. (DataLine)

new_resampled(res, interpolation)

source code 

Creates a new data line by resampling an existing one.

This method is equivalent to DataLine.duplicate() followed by DataLine.resample(), but it is more efficient.

Parameters:
  • res - Desired resolution. (int)
  • interpolation - Interpolation method to use. Expected values: INTERPOLATION_NONE, INTERPOLATION_ROUND, INTERPOLATION_LINEAR, INTERPOLATION_BILINEAR, INTERPOLATION_KEY, INTERPOLATION_BSPLINE, INTERPOLATION_OMOMS, INTERPOLATION_NNA, INTERPOLATION_SCHAUM. (InterpolationType)
Returns:
A newly created data line. (DataLine)

Since: 2.1

resample(res, interpolation)

source code 

Resamples a data line.

In other words changes the size of one dimensional field related with data line. The original values are used for resampling using a requested interpolation alorithm.

Parameters:
  • res - Desired resolution. (int)
  • interpolation - Interpolation method to use. Expected values: INTERPOLATION_NONE, INTERPOLATION_ROUND, INTERPOLATION_LINEAR, INTERPOLATION_BILINEAR, INTERPOLATION_KEY, INTERPOLATION_BSPLINE, INTERPOLATION_OMOMS, INTERPOLATION_NNA, INTERPOLATION_SCHAUM. (InterpolationType)

resize(from_, to)

source code 

Resizes (crops) a data line.

Extracts a part of data line in range from..(to-1), recomputing real sizes.

Parameters:
  • from_ - (int)
  • to - Where to finish + 1. (int)

part_extract(from_, len)

source code 

Extracts a part of a data line to a new data line.

Parameters:
  • from_ - (int)
  • len - Length of extracted segment. (int)
Returns:
The extracted area as a newly created data line. (DataLine)

copy(b)

source code 

Copies the contents of a data line to another already allocated data line of the same size.

Parameters:

Warning: Semantic of method differs from DataField.copy(), it copies only data. It will be probably changed.

get_res()

source code 

Gets the number of data points in a data line.

Returns:
Resolution (number of data points). (int)

get_real()

source code 

Gets the physical size of a data line.

Returns:
Real size of data line. (float)

set_real(real)

source code 

Sets the real data line size.

Parameters:
  • real - value to be set (float)

get_offset()

source code 

Gets the offset of data line origin.

Returns:
Offset value. (float)

set_offset(offset)

source code 

Sets the offset of a data line origin.

Note offsets don't affect any calculation, nor functions like DataLine.rtoi().

Parameters:
  • offset - New offset value. (float)

get_si_unit_x()

source code 

Returns lateral SI unit of a data line.

Returns:
SI unit corresponding to the lateral (X) dimension of the data line. Its reference count is not incremented. (SIUnit)

get_si_unit_y()

source code 

Returns value SI unit of a data line.

Returns:
SI unit corresponding to the "height" (Z) dimension of the data line. Its reference count is not incremented. (SIUnit)

set_si_unit_x(si_unit)

source code 

Sets the SI unit corresponding to the lateral (X) dimension of a data line.

It does not assume a reference on si_unit, instead it adds its own reference.

Parameters:
  • si_unit - SI unit to be set. (SIUnit)

set_si_unit_y(si_unit)

source code 

Sets the SI unit corresponding to the "height" (Z) dimension of a data line.

It does not assume a reference on si_unit, instead it adds its own reference.

Parameters:
  • si_unit - SI unit to be set. (SIUnit)

get_value_format_x(style)

source code 

Finds value format good for displaying coordinates of a data line.

Parameters:
  • style - Unit format style. Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX. (SIUnitFormatStyle)
Returns:
Tuple consisting of 2 values (value, format). ((SIValueFormat), (SkipArg))

get_value_format_y(style)

source code 

Finds value format good for displaying values of a data line.

Note this functions searches for minimum and maximum value in data_line, therefore it's relatively slow.

Parameters:
  • style - Unit format style. Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX. (SIUnitFormatStyle)
Returns:
Tuple consisting of 2 values (value, format). ((SIValueFormat), (SkipArg))

itor(pixpos)

source code 

Transforms pixel coordinate to real (physical) coordinate.

That is it maps range [0..resolution] to range [0..real-size]. It is not suitable for conversion of matrix indices to physical coordinates, you have to use DataLine.itor(data_line, pixpos + 0.5) for that.

Parameters:
  • pixpos - Pixel coordinate. (float)
Returns:
pixpos in real coordinates. (float)

rtoi(realpos)

source code 

Transforms real (physical) coordinate to pixel coordinate.

That is it maps range [0..real-size] to range [0..resolution].

Parameters:
  • realpos - Real coordinate. (float)
Returns:
realpos in pixel coordinates. (float)

get_val(i)

source code 

Gets value at given position in a data line.

Do not access data with this function inside inner loops, it's slow. Get raw data buffer with DataLine.get_data_const() and access it directly instead.

Parameters:
  • i - Position in the line (index). (int)
Returns:
Value at given index. (float)

set_val(i, value)

source code 

Sets the value at given position in a data line.

Do not set data with this function inside inner loops, it's slow. Get raw data buffer with DataLine.get_data() and write to it directly instead.

Parameters:
  • i - Position in the line (index). (int)
  • value - Value to set. (float)

get_dval(x, interpolation)

source code 

Gets interpolated value at arbitrary data line point indexed by pixel coordinates.

Note pixel values are centered in intervals [j, j+1], so to get the same value as DataLine.get_val(data_line, j) returns, it's necessary to add 0.5: DataLine.get_dval(data_line, j+0.5, interpolation).

See also DataLine.get_dval_real() that does the same, but takes real coordinates.

Parameters:
  • x - Position in data line in range [0, resolution]. If the value is outside this range, the nearest border value is returned. (float)
  • interpolation - Interpolation method to use. (int)
Returns:
Value interpolated in the data line. (float)

get_dval_real(x, interpolation)

source code 

Gets interpolated value at arbitrary data line point indexed by real coordinates.

See also DataLine.get_dval() for interpolation explanation.

Parameters:
  • x - real coordinates position (float)
  • interpolation - interpolation method used (int)
Returns:
Value interpolated in the data line. (float)

invert(x, z)

source code 

Reflects amd/or inverts a data line.

In the case of value reflection, it's inverted about mean value.

Parameters:
  • x - Whether to invert data point order. (bool)
  • z - Whether to invert in Z direction (i.e., invert values). (bool)

fill(value)

source code 

Fills a data line with specified value.

Parameters:
  • value - Value to fill data line with. (float)

multiply(value)

source code 

Multiplies all values in a data line with a specified value.

Parameters:
  • value - Value to multiply data line with. (float)

add(value)

source code 

Adds a specified value to all values in a data line.

Parameters:
  • value - Value to be added. (float)

part_clear(from_, to)

source code 

Fills a data line part with zeroes.

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)

part_fill(from_, to, value)

source code 

Fills specified part of data line with specified number

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
  • value - Value to fill data line part with. (float)

part_multiply(from_, to, value)

source code 

Multiplies all values in a part of data line by specified value.

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
  • value - Value multiply data line part with. (float)

part_add(from_, to, value)

source code 

Adds specified value to all values in a part of a data line.

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
  • value - Value to be added (float)

threshold(threshval, bottom, top)

source code 

Sets all the values to bottom or top value depending on whether the original values are below or above threshold value

Parameters:
  • threshval - Threshold value. (float)
  • bottom - Lower replacement value. (float)
  • top - Upper replacement value. (float)
Returns:
total number of values above threshold (int)

part_threshold(from_, to, threshval, bottom, top)

source code 

Sets all the values within interval to bottom or top value depending on whether the original values are below or above threshold value.

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
  • threshval - Threshold value. (float)
  • bottom - Lower replacement value. (float)
  • top - Upper replacement value. (float)
Returns:
total number of values above threshold within interval (int)

get_line_coeffs()

source code 

Finds line leveling coefficients.

The coefficients can be used for line leveling using relation data[i] := data[i] - (av + bv*i);

Returns:
Tuple consisting of 2 values (av, bv). ((float), (float))

line_level(av, bv)

source code 

Performs line leveling.

See DataLine.get_line_coeffs() for deails.

Parameters:
  • av - Height coefficient. (float)
  • bv - Slope coefficient. (float)

rotate(angle, interpolation)

source code 

Performs line rotation.

This is operation similar to leveling, but it does not change the angles between line segments (on the other hand it introduces other deformations due to discretization).

Parameters:
  • angle - Angle of rotation (in radians), counterclockwise. (float)
  • interpolation - Interpolation method to use (can be only of two-point type). Expected values: INTERPOLATION_NONE, INTERPOLATION_ROUND, INTERPOLATION_LINEAR, INTERPOLATION_BILINEAR, INTERPOLATION_KEY, INTERPOLATION_BSPLINE, INTERPOLATION_OMOMS, INTERPOLATION_NNA, INTERPOLATION_SCHAUM. (InterpolationType)

Since: 2.7

line_rotate(angle, interpolation)

source code 

Performs line rotation.

Use DataLine.rotate() instead.

Parameters:
  • angle - Angle of rotation (in radians), counterclockwise. (float)
  • interpolation - Interpolation method to use (can be only of two-point type). (int)

get_der(i)

source code 

Computes central derivaltion at given index in a data line.

Parameters:
  • i - Pixel coordinate. (int)
Returns:
Derivation at given position. (float)

cumulate()

source code 

Transforms a distribution in a data line to cummulative distribution.

Each element becomes sum of all previous elements in the line, including self.

dwt(wt_coefs, direction, minsize)

source code 

Performs steps of the wavelet decomposition.

The smallest low pass coefficients block is equal to minsize. Run with minsize = dline->res/2 to perform one step of decomposition or minsize = 4 to perform full decomposition (or anything between).

Parameters:
  • wt_coefs - Data line where the wavelet transform coefficients are stored. (DataLine)
  • direction - Transform direction. Expected values: TRANSFORM_DIRECTION_BACKWARD, TRANSFORM_DIRECTION_FORWARD. (TransformDirection)
  • minsize - size of minimal transform result block (int)

fft(isrc, rdest, idest, windowing, direction, interpolation, preserverms, level)

source code 

Calculates Fast Fourier Transform of a data line.

A windowing or data leveling can be applied if requested.

Parameters:
  • isrc - Imaginary input data line. (DataLine)
  • rdest - Real output data line. It will be resized to the size of the input data line. (DataLine)
  • idest - Imaginary output data line. It will be resized to the size of the input data line. (DataLine)
  • windowing - Windowing mode. Expected values: WINDOWING_NONE, WINDOWING_HANN, WINDOWING_HAMMING, WINDOWING_BLACKMANN, WINDOWING_LANCZOS, WINDOWING_WELCH, WINDOWING_RECT, WINDOWING_NUTTALL, WINDOWING_FLAT_TOP, WINDOWING_KAISER25. (WindowingType)
  • direction - FFT direction. Expected values: TRANSFORM_DIRECTION_BACKWARD, TRANSFORM_DIRECTION_FORWARD. (TransformDirection)
  • interpolation - Interpolation type. Ignored since 2.8 as no resampling is performed. Expected values: INTERPOLATION_NONE, INTERPOLATION_ROUND, INTERPOLATION_LINEAR, INTERPOLATION_BILINEAR, INTERPOLATION_KEY, INTERPOLATION_BSPLINE, INTERPOLATION_OMOMS, INTERPOLATION_NNA, INTERPOLATION_SCHAUM. (InterpolationType)
  • preserverms - True to preserve RMS value while windowing. (bool)
  • level - 0 to perform no leveling, 1 to subtract mean value, 2 to subtract line (the number can be interpreted as the first polynomial degree to keep, but only the enumerated three values are available). (int)

part_fft(isrc, rdest, idest, from_, len, windowing, direction, interpolation, preserverms, level)

source code 

Calculates Fast Fourier Transform of a part of a data line.

A windowing or data leveling can be applied if requested.

Parameters:
  • isrc - Imaginary input data line. Since 2.7 it can be None for real-to-complex transforms. (DataLine)
  • rdest - Real output data line, it will be resized to len. (DataLine)
  • idest - Imaginary output data line, it will be resized to len. (DataLine)
  • from_ - (int)
  • len - Lenght of data line part, it must be at least 2. (int)
  • windowing - Windowing mode. Expected values: WINDOWING_NONE, WINDOWING_HANN, WINDOWING_HAMMING, WINDOWING_BLACKMANN, WINDOWING_LANCZOS, WINDOWING_WELCH, WINDOWING_RECT, WINDOWING_NUTTALL, WINDOWING_FLAT_TOP, WINDOWING_KAISER25. (WindowingType)
  • direction - FFT direction. Expected values: TRANSFORM_DIRECTION_BACKWARD, TRANSFORM_DIRECTION_FORWARD. (TransformDirection)
  • interpolation - Interpolation type. Ignored since 2.8 as no resampling is performed. Expected values: INTERPOLATION_NONE, INTERPOLATION_ROUND, INTERPOLATION_LINEAR, INTERPOLATION_BILINEAR, INTERPOLATION_KEY, INTERPOLATION_BSPLINE, INTERPOLATION_OMOMS, INTERPOLATION_NNA, INTERPOLATION_SCHAUM. (InterpolationType)
  • preserverms - True to preserve RMS value while windowing. (bool)
  • level - 0 to perform no leveling, 1 to subtract mean value, 2 to subtract line (the number can be interpreted as the first polynomial degree to keep, but only the enumerated three values are available). (int)

fft_raw(isrc, rdest, idest, direction)

source code 

Calculates Fast Fourier Transform of a data line.

No leveling, windowing nor scaling is performed.

Since 2.8 the dimensions need not to be from the set of sizes returned by gwy_fft_find_nice_size().

Parameters:
  • isrc - Imaginary input data line. Since 2.7 it can be None for real-to-complex transform. (DataLine)
  • rdest - Real output data line. It will be resized to the size of the input data line. (DataLine)
  • idest - Imaginary output data line. It will be resized to the size of the input data line. (DataLine)
  • direction - FFT direction. Expected values: TRANSFORM_DIRECTION_BACKWARD, TRANSFORM_DIRECTION_FORWARD. (TransformDirection)

Since: 2.1

get_max()

source code 

Finds the maximum value of a data line.

Returns:
The maximum value. (float)

get_min()

source code 

Finds the minimum value of a data line.

Returns:
The minimum value. (float)

get_min_max()

source code 

Finds the minimum and maximum values of a data line.

Since 2.42

Returns:
Tuple consisting of 2 values (min, max). ((float), (float))

get_avg()

source code 

Computes average value of a data line.

Returns:
Average value (float)

get_rms()

source code 

Computes root mean square value of a data line.

Returns:
Root mean square deviation of values. (float)

get_tan_beta0()

source code 

Computes root mean square slope in a data line.

Returns:
Root mean square slope within a given interval. (float)

Since: 2.2

get_variation()

source code 

Computes the total variation of a data line.

See DataLine.part_get_variation() for definition and discussion.

Returns:
The total variation. (float)

Since: 2.42

get_sum()

source code 

Computes sum of all values in a data line.

Returns:
sum of all the values. (float)

get_ra()

source code 

Computes the mean absolute deviation of a data line.

Returns:
The mean absolute deviation of height values. (float)

Since: 2.42

get_skew()

source code 

Computes the skew of a data line.

Returns:
The skew of height values. (float)

Since: 2.42

get_kurtosis()

source code 

Computes the kurtosis of a data line.

Returns:
The kurtosis of height values. (float)

Since: 2.42

part_get_max(from_, to)

source code 

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

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
Maximum within given interval. (float)

part_get_min(from_, to)

source code 

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

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
Minimum within given interval. (float)

part_get_min_max(from_, to)

source code 

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

Since 2.42

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
Tuple consisting of 2 values (min, max). ((float), (float))

part_get_avg(from_, to)

source code 

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

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
Average value within given interval. (float)

part_get_rms(from_, to)

source code 

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

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
Root mean square deviation of heights within a given interval (float)

part_get_tan_beta0(from_, to)

source code 

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:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
Root mean square slope within a given interval. (float)

Since: 2.2

part_get_variation(from_, to)

source code 

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

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
The total variation within a given interval. (float)

Since: 2.42

part_get_sum(from_, to)

source code 

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

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
Sum of all values within the interval. (float)

part_get_ra(from_, to)

source code 

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

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
Mean absolute deviation of heights within a given interval. (float)

part_get_skew(from_, to)

source code 

Computes skew value of a part of a data line.

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
Skew of heights within a given interval. (float)

part_get_kurtosis(from_, to)

source code 

Computes kurtosis value of a part of a data line.

Note this function returns, similary to data field statistics, kurtosis that is zero for the Gaussian distribution (not 3).

Parameters:
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
Kurtosis of heights within a given interval. (float)

get_modus(histogram_steps)

source code 

Finds approximate modus of a data line.

See DataLine.part_get_modus() for details and caveats.

Parameters:
  • histogram_steps - Number of histogram steps used for modus searching, pass a nonpositive number to autosize. (int)
Returns:
The modus. (float)

part_get_modus(from_, to, histogram_steps)

source code 

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:
  • from_ - (int)
  • to - The index in data_line to stop (noninclusive). (int)
  • histogram_steps - Number of histogram steps used for modus searching, pass a nonpositive number to autosize. (int)
Returns:
The modus. (float)

get_median()

source code 

Finds median of a data line.

Returns:
The median. (float)

Since: 2.1

part_get_median(from_, to)

source code 

Finds median of a data line part.

Parameters:
  • from_ - (int)
  • to - The index in data_line to stop (noninclusive). (int)
Returns:
The median. (float)

Since: 2.1

get_length()

source code 

Calculates physical length of a data line.

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

Returns:
The line length. (float)

get_xpm(m, k)

source code 

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:
  • m - Number of sampling lengths. (int)
  • k - Number of peaks to consider. (int)
Returns:
The peak roughness quantity defined by m and k. (float)

Since: 2.42

get_xvm(m, k)

source code 

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:
  • m - Number of sampling lengths. (int)
  • k - Number of valleys to consider. (int)
Returns:
The valley roughness quantity defined by m and k. (float)

Since: 2.42

get_xtm(m, k)

source code 

Calculates a total roughness quantity for a data line.

The total quantity is just the sum of the corresponding quantities obtained by DataLine.get_xpm() and DataLine.get_xvm().

Parameters:
  • m - Number of sampling lengths. (int)
  • k - Number of peaks and valleys to consider. (int)
Returns:
The total roughness quantity defined by m and k. (float)

Since: 2.42

distribution(distribution, ymin, ymax, normalize_to_unity, nstats)

source code 

Calculates the distribution of data line values.

This function is quite similar to DataLine.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:
  • 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). (DataLine)
  • ymin - Start of value range, pass ymin = ymax = 0.0 for the full range. (float)
  • ymax - End of value range. (float)
  • 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). (bool)
  • nstats - The requested number of histogram bins, pass a non-positive number to automatically choose a suitable number of bins. (int)

Since: 2.8

dh(target_line, ymin, ymax, nsteps)

source code 

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:
  • target_line - Data line to store height distribution function to. It will be resized to nsteps. (DataLine)
  • ymin - Height distribution minimum value. (float)
  • ymax - Height distribution maximum value. (float)
  • nsteps - Number of histogram steps. (int)

cdh(target_line, ymin, ymax, nsteps)

source code 

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:
  • target_line - Data line to store height distribution function to. It will be resized to nsteps. (DataLine)
  • ymin - Height distribution minimum value. (float)
  • ymax - Height distribution maximum value. (float)
  • nsteps - Number of histogram steps. (int)

da(target_line, ymin, ymax, nsteps)

source code 

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:
  • target_line - Data line to store angle distribution function to. (DataLine)
  • ymin - Angle distribution minimum value. (float)
  • ymax - Angle distribution maximum value. (float)
  • nsteps - Mumber of angular histogram steps. (int)

cda(target_line, ymin, ymax, nsteps)

source code 

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:
  • target_line - Data line to store angle distribution function to. It will be resized to nsteps. (DataLine)
  • ymin - Angle distribution minimum value. (float)
  • ymax - Angle distribution maximum value. (float)
  • nsteps - Number of angular histogram steps. (int)

acf(target_line)

source code 

Coputes autocorrelation function and stores the values in target_line

Parameters:
  • target_line - Data line to store autocorrelation function to. It will be resized to data_line size. (DataLine)

hhcf(target_line)

source code 

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

Parameters:
  • target_line - Data line to store height-height function to. It will be resized to data_line size. (DataLine)

psdf(target_line, windowing, interpolation)

source code 

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:
  • target_line - Data line to store power spectral density function to. It will be resized to data_line size. (DataLine)
  • windowing - Windowing method to use. (int)
  • interpolation - Interpolation type. Ignored since 2.8 as no resampling is performed. (int)

get_data()

source code 

Extract the data of a data line.

The returned list contains a copy of the data. Changing its contents does not change the data line's data.

Returns:
List containing extracted data line data. (list)

set_data(data)

source code 

Sets the entire contents of a data line.

The length of data must be equal to the number of elements of the data line.

Parameters:
  • data - Sequence of floating point values. (list)

part_fit_polynom(n, from_, to)

source code 

Fits a polynomial through a part of a data line.

Please see DataLine.fit_polynom() for more details.

Parameters:
  • n - Polynom degree. (int)
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)
Returns:
The coefficients of the polynomial (coeffs when it was not None, otherwise a newly allocated array). (list)

fit_polynom(n)

source code 

Fits a polynomial through a data line.

Note n is polynomial degree, so the size of coeffs is n+1. X-values are indices in the data line.

For polynomials of degree 0 and 1 it's better to use DataLine.get_avg() and DataLine.get_line_coeffs() because they are faster.

Parameters:
  • n - Polynom degree. (int)
Returns:
The coefficients of the polynomial (coeffs when it was not None, otherwise a newly allocated array). (list)

part_subtract_polynom(coeffs, from_, to)

source code 

Subtracts a polynomial from a part of a data line.

Parameters:
  • coeffs - An array of size n+1 with polynomial coefficients to. (list)
  • from_ - (int)
  • to - Index the line part ends at + 1. (int)

subtract_polynom(coeffs)

source code 

Subtracts a polynomial from a data line.

Parameters:
  • coeffs - An array of size n+1 with polynomial coefficients to. (list)

duplicate()

source code 

Convenience macro doing gwy_serializable_duplicate() with all the necessary typecasting.

Returns:
(DataLine)

get_data_pointer()

source code 

Gets pointer to data which the data line contains.

Returns:
integer pointing to the raw data of the data field (long)