Profile¶

class surfalize.profile.Profile(height_data, step, length_um=None)¶

Bases: BaseTopography

Representation of a 1D-profile characterised by a 1d array of height data and an associated stepsize along the lateral axis.

The class implements methods to calculate profile roughness parameters defined in ISO 4287/ISO 21920 as well as the functional parameters defined in ISO 13565-2. Moreover, it implements methods for data processing and correction that are analogous to their Surface counterparts.

Overview over available roughness parameters:

Height parameters: Ra, Rq, Rp, Rv, Rz, Rt, Rsk, Rku
Hybrid parameters: Rdq
Functional parameters: Rk, Rpk, Rvk, Rmr1, Rmr2, Rxp, Rmr(c), Rmc(mr)
Functional volume parameters: Vmp, Vmc, Vvv, Vvc

Contrary to areal parameters, which are always evaluated over the entire definition area, several profile parameters (Rp, Rv, Rz) are defined by ISO 4287 on a sampling length and averaged over the number of sampling lengths contained in the evaluation length (typically five). These methods therefore expose an ‘n_sections’ argument that controls the number of sampling lengths the evaluation length is divided into, which defaults to 5 according to ISO 4287/ISO 4288. To evaluate these parameters on the entire evaluation length instead, specify n_sections=1.

Overview of data operations:

Zeroing: Setting lowest height value to zero
Centering: Centering height values around the mean
Cropping: Cropping to a specified interval
Zooming: Magnification by factor around the center
Levelling: Leveling by least squares line
Detrending: Removal of polynomial trends
Filtering: Applying lowpass, highpass or bandpass filters
Removing outliers: Remove outliers by mean of median filters
Thresholding: Thresholding based on material ratio
Filling non-measured points: Interpolating non-measured points

Parameters:

height_datandarray: A 1d numpy array containing the height data.
stepfloat: Interval between two datapoints along the lateral axis.
length_umfloat | None, default None: Length of the profile in µm. If None, the length is calculated from the number of datapoints and the stepsize.

Attributes:

data: The 1d height data array.
has_masked_points: Returns true if the topography contains masked points.
has_missing_points: Returns true if the topography contains non-measured points.
size: Returns the number of datapoints of the profile.

Methods

`Ra`()	Calculates the arithmetic mean deviation Ra over the evaluation length.
`Rak1`()	Calculates the area of the hills Rak1 in %·µm, the area of the triangle obtained during the reduction process of the protruding hills.
`Rak2`()	Calculates the area of the dales Rak2 in %·µm, the area of the triangle obtained during the reduction process of the protruding dales.
`Rdc`([p, q])	Calculates the material ratio height difference Rdc, the difference in height between the p and q material ratio with p < q.
`Rdq`()	Calculates the root mean square slope Rdq over the evaluation length.
`Rk`()	Calculates the core roughness depth Rk according to ISO 13565-2 in µm.
`Rku`()	Calculates the kurtosis Rku over the evaluation length.
`Rmc`(mr)	Calculates the height (c) in µm for a given material ratio (mr).
`Rmr`(c)	Calculates the ratio of the material length at a specified height c (in µm) to the evaluation length.
`Rmr1`()	Calculates the material ratio Rmr1 according to ISO 13565-2 in %.
`Rmr2`()	Calculates the material ratio Rmr2 according to ISO 13565-2 in %.
`Rmrk1`()	Calculates Rmrk1 in %, the material ratio of the hills.
`Rmrk2`()	Calculates Rmrk2 in %, the material ratio of the dales.
`Rp`([n_sections])	Calculates the maximum peak height Rp.
`Rpk`()	Calculates the reduced peak height Rpk according to ISO 13565-2 in µm.
`Rpkx`()	Calculates the maximum peak height Rpkx in µm, the height of the highest point above the core profile before the reduction process.
`Rq`()	Calculates the root mean square deviation Rq over the evaluation length.
`Rsk`()	Calculates the skewness Rsk over the evaluation length.
`Rt`()	Calculates the total height Rt as the sum of the maximum peak height and the maximum pit depth over the entire evaluation length.
`Rv`([n_sections])	Calculates the maximum pit depth Rv.
`Rvk`()	Calculates the reduced valley depth Rvk according to ISO 13565-2 in µm.
`Rvkx`()	Calculates the maximum pit depth Rvkx in µm, the depth of the deepest point below the core profile before the reduction process.
`Rxp`([p, q])	Calculates the difference in height between the p and q material ratio.
`Rz`([n_sections])	Calculates the maximum height Rz.
`Vm`(p)	Calculates the material volume per unit area at a given material ratio p (Vm(p)) according to ISO 25178-2.
`Vmc`([p, q])	Calculates the difference in material volume between the p and q material ratio.
`Vmp`([p])	Calculates the peak material volume at p.
`Vv`(p)	Calculates the void volume per unit area at a given material ratio p (Vv(p)) according to ISO 25178-2.
`Vvc`([p, q])	Calculates the difference in void volume between p and q material ratio.
`Vvv`([q])	Calculates the dale volume at p material ratio.
`center`([inplace])	Centers the data around its mean value.
`clear_cache`()	Clears the cache for the entire instance.
`create_cache_entry`(method, entry, args, kwargs)	Manually creates a cache entry for the specified method.
`crop`(interval[, in_units, inplace])	Crop the profile to the interval specified by the interval parameter.
`detrend_polynomial`([degree, inplace, ...])	Detrend a 1d array of height data using a polynomial, handling NaN values.
`fill_nonmeasured`([method, inplace])	Fills the non-measured points by interpolation.
`filter`(filter_type, cutoff[, cutoff2, ...])	Filters the topography by applying a Gaussian filter.
`get_abbott_firestone_curve`()	Instantiates and returns an AbbottFirestoneCurve object.
`invert`([inplace])	Inverts the topography, creating a negative.
`level`([return_trend, inplace])	Levels the profile by subtraction of a least squares fit line.
`max`()	Computes the maximum height value, ignoring invalid points.
`mean`()	Computes the mean height value, ignoring invalid points.
`median`()	Computes the median height value, ignoring invalid points.
`min`()	Computes the minimum height value, ignoring invalid points.
`period`()	Calculates the dominant spatial period of the profile based on the Fourier transform.
`plot_2d`([ax])	Plots the profile.
`plot_abbott_curve`([nbars, save_to])	Plots the Abbott-Firestone curve.
`plot_functional_parameter_study`([save_to])	Plots a visual study of the functional parameters derived from the Abbott-Firestone curve.
`remove_outliers`([n, method, inplace])	Removes outliers based on the n-sigma criterion.
`roughness_parameters`([parameters])	Computes multiple roughness parameters at once and returns them in a dictionary.
`show`()	Shows the plot of the profile.
`std`()	Computes the standard deviation of the height values, ignoring invalid points.
`threshold`([threshold, inplace])	Removes data outside of threshold percentage of the material ratio curve.
`zero`([inplace])	Sets the minimum height to zero.
`zoom`(factor[, inplace])	Magnifies the profile by the specified factor around its center.

AVAILABLE_PARAMETERS = ('Ra', 'Rq', 'Rp', 'Rv', 'Rz', 'Rsk', 'Rku', 'Rdq', 'Rk', 'Rpk', 'Rvk', 'Rpkx', 'Rvkx', 'Rak1', 'Rak2', 'Rmr1', 'Rmr2', 'Rxp', 'Rdc', 'Vmp', 'Vmc', 'Vvv', 'Vvc', 'Rt', 'period')¶

DEFAULT_N_SECTIONS = 5¶

ISO_PARAMETERS = ('Ra', 'Rq', 'Rp', 'Rv', 'Rz', 'Rsk', 'Rku', 'Rdq', 'Rk', 'Rpk', 'Rvk', 'Rpkx', 'Rvkx', 'Rak1', 'Rak2', 'Rmr1', 'Rmr2', 'Rxp', 'Rdc', 'Vmp', 'Vmc', 'Vvv', 'Vvc')¶

NON_ISO_PARAMETERS = ('Rt', 'period')¶

Ra()¶

Calculates the arithmetic mean deviation Ra over the evaluation length.

Returns:

Rafloat

Rak1()¶

Calculates the area of the hills Rak1 in %·µm, the area of the triangle obtained during the reduction process of the protruding hills.

Returns:

Rak1float

Rak2()¶

Calculates the area of the dales Rak2 in %·µm, the area of the triangle obtained during the reduction process of the protruding dales.

Returns:

Rak2float

Rdc(p=2.5, q=50)¶

Calculates the material ratio height difference Rdc, the difference in height between the p and q material ratio with p < q. This generalizes Rxp; the default values of p and q match Rxp.

Parameters:

pfloat, default 2.5: material ratio p in %.
qfloat, default 50: material ratio q in %.

Returns:

Height differencefloat

Rdq()¶

Calculates the root mean square slope Rdq over the evaluation length.

Returns:

Rdqfloat

Rk()¶

Calculates the core roughness depth Rk according to ISO 13565-2 in µm.

Returns:

Rkfloat

Rku()¶

Calculates the kurtosis Rku over the evaluation length. It is the quotient of the mean quartic value of the ordinate values and the fourth power of Rq.

Returns:

Rkufloat

Rmc(mr)¶

Calculates the height (c) in µm for a given material ratio (mr).

Parameters:

mrfloat: material ratio in %.

Returns:

heightfloat

Rmr(c)¶

Calculates the ratio of the material length at a specified height c (in µm) to the evaluation length.

Parameters:

cfloat: height in µm.

Returns:

material ratiofloat

Rmr1()¶

Calculates the material ratio Rmr1 according to ISO 13565-2 in %.

Returns:

Rmr1float

Rmr2()¶

Calculates the material ratio Rmr2 according to ISO 13565-2 in %.

Returns:

Rmr2float

Rmrk1()¶

Calculates Rmrk1 in %, the material ratio of the hills. This is the parameter formerly named Rmr1.

Returns:

Rmrk1float

Rmrk2()¶

Calculates Rmrk2 in %, the material ratio of the dales. This is the parameter formerly named Rmr2.

Returns:

Rmrk2float

Rp(n_sections=5)¶

Calculates the maximum peak height Rp. According to ISO 4287, Rp is defined on a sampling length and averaged over the number of sampling lengths contained in the evaluation length. The number of sampling lengths is specified by the n_sections argument and defaults to 5 according to ISO 4287/4288. Specify n_sections=1 to evaluate Rp on the entire evaluation length.

Parameters:

n_sectionsint, default 5: Number of sampling lengths the evaluation length is divided into.

Returns:

Rpfloat

Rpk()¶

Calculates the reduced peak height Rpk according to ISO 13565-2 in µm.

Returns:

Rpkfloat

Rpkx()¶

Calculates the maximum peak height Rpkx in µm, the height of the highest point above the core profile before the reduction process.

Returns:

Rpkxfloat

Rq()¶

Calculates the root mean square deviation Rq over the evaluation length.

Returns:

Rqfloat

Rsk()¶

Calculates the skewness Rsk over the evaluation length. It is the quotient of the mean cube value of the ordinate values and the cube of Rq.

Returns:

Rskfloat

Rt()¶

Calculates the total height Rt as the sum of the maximum peak height and the maximum pit depth over the entire evaluation length.

Returns:

Rtfloat

Rv(n_sections=5)¶

Calculates the maximum pit depth Rv. According to ISO 4287, Rv is defined on a sampling length and averaged over the number of sampling lengths contained in the evaluation length. The number of sampling lengths is specified by the n_sections argument and defaults to 5 according to ISO 4287/4288. Specify n_sections=1 to evaluate Rv on the entire evaluation length.

Parameters:

n_sectionsint, default 5: Number of sampling lengths the evaluation length is divided into.

Returns:

Rvfloat

Rvk()¶

Calculates the reduced valley depth Rvk according to ISO 13565-2 in µm.

Returns:

Rvkfloat

Rvkx()¶

Calculates the maximum pit depth Rvkx in µm, the depth of the deepest point below the core profile before the reduction process.

Returns:

Rvkxfloat

Rxp(p=2.5, q=50)¶

Calculates the difference in height between the p and q material ratio.

Parameters:

pfloat: material ratio p in %.
qfloat: material ratio q in %.

Returns:

Height differencefloat

Rz(n_sections=5)¶

Calculates the maximum height Rz. According to ISO 4287, Rz is defined on a sampling length as the sum of the maximum peak height and the maximum pit depth and averaged over the number of sampling lengths contained in the evaluation length. The number of sampling lengths is specified by the n_sections argument and defaults to 5 according to ISO 4287/4288. Specify n_sections=1 to evaluate Rz on the entire evaluation length, which is equivalent to the total height Rt.

Parameters:

n_sectionsint, default 5: Number of sampling lengths the evaluation length is divided into.

Returns:

Rzfloat

crop(interval, in_units=True, inplace=False)¶

Crop the profile to the interval specified by the interval parameter.

Parameters:

intervaltuple[float, float]: The crop interval, as a (x0, x1) tuple.
in_unitsbool, default True: If true, the interval is interpreted as physical units (µm). If false, the interval is interpreted in datapoint indices.
inplacebool, default False: If False, create and return new Profile object with processed data. If True, changes data inplace and return self.

Returns:

profilesurfalize.Profile

property data¶: The 1d height data array. The returned array is a read-only view: mutating it in place (e.g. profile.data[i] = x) is disallowed because it would not invalidate the cached roughness parameters. Assign a new array (profile.data = new_array) to replace the data, which recomputes length_um and clears the cache.

detrend_polynomial(degree=1, inplace=False, return_trend=False)¶

Detrend a 1d array of height data using a polynomial, handling NaN values.

Parameters:

degreeint, default 1: Polynomial degree.
inplacebool, default False: If False, create and return new Profile object with processed data. If True, changes data inplace and return self.
return_trendbool, default False: return the trend as a Profile object alongside the detrended profile if True.

Returns:

Profile or tuple of Profiles

fill_nonmeasured(method='nearest', inplace=False)¶

Fills the non-measured points by interpolation.

Parameters:

method{‘linear’, ‘nearest’, ‘cubic’}, default ‘nearest’: Method by which to perform the interpolation. See scipy.interpolate.griddata for details.
inplacebool, default False: If False, create and return new Profile object with processed data. If True, changes data inplace and return self.

Returns:

profilesurfalize.Profile

level(return_trend=False, inplace=False)¶

Levels the profile by subtraction of a least squares fit line.

Parameters:

return_trendbool, default False: return the trend as a Profile object alongside the detrended profile if True.
inplacebool, default False: If False, create and return new Profile object with processed data. If True, changes data inplace and return self.

Returns:

Profile

period()¶

Calculates the dominant spatial period of the profile based on the Fourier transform.

Returns:

periodfloat

plot_2d(ax=None)¶

Plots the profile.

Parameters:

axmatplotlib axis, default None: If specified, the plot will be drawn on the specified axis.

Returns:

plt.Figure, plt.Axes

show()¶

Shows the plot of the profile.

Returns:

None

property size¶

Returns the number of datapoints of the profile.

Returns:

int

zoom(factor, inplace=False)¶

Magnifies the profile by the specified factor around its center.

Parameters:

factorfloat: Factor by which the profile is magnified.
inplacebool, default False: If False, create and return new Profile object with processed data. If True, changes data inplace and return self.

Returns:

profilesurfalize.Profile