SurfaceTopography.Container package

Subpackages

Submodules

SurfaceTopography.Container.Averaging module

Compute properties as averages over individual results.

SurfaceTopography.Container.Averaging.log_average(self, function_name, unit, nb_points_per_decade=10, reliable=True, progress_callback=None, **kwargs)

Return average property on a logarithmic grid.

Parameters:

  • self (SurfaceContainer) – Container object containing the underlying data sets.

  • function_name (str) – Function for which to compute the average, e.g. ‘autocorrelation_from_profile’.

  • unit (str) – Unit of the distance array. All topographies are converted to this unit before the properties are computed.

  • nb_points_per_decade (int, optional) – Number of points per decade in length for automatic grid construction. (Default: 10)

  • reliable (bool, optional) – Only return data deemed reliable. (Default: True)

  • progress_callback (func, optional) – Function taking iteration and the total number of iterations as arguments for progress reporting. (Default: None)

SurfaceTopography.Container.Integration module

SurfaceTopography.Container.Integration.integrate_psd_from_profile(self, factor, unit, window=None, reliable=True)

Computes the integral of the 1D PSD weighted by “factor”

The integral is computed by adding up the discrete sum for each topography.

The summand for each topography is weighted by the number of topographies having this wavevector in their bandwidth

Hence for a container containing only one topogaphy, this method is identical to calling topography.integrate_psd_from_profile()

Continuum:

\[\frac{1}{2 \pi} \int_0^\infty dq_x factor(q_x) C^{1D}(q_x)\]

Discrete

\[m_\alpha = \sum_i \frac{1}{L_{x, i}} \sum_{q_x} \frac{factor(q_x) C^{1D}_{i}(q_x)}{N(q_x)}\]

Where the index \(i\) runs over all topographies and \(N(q_x)\) is the number of topographies having the wavevector q_x in their bandwidth

Parameters:

selfSurfaceContainer

Collection of Height containers

factor: callable

Function taking as argument the wavevector in the fast scan direction qx

func(np.ndarray: qx) -> np.ndarray

windowstr, optional

Window for eliminating edge effect. See scipy.signal.get_window. (Default: None)

reliablebool, optional

Only return data deemed reliable. (Default: True)

Returns:

weighted_integral: float

SurfaceTopography.Container.Integration.ciso_moment(self, order=1, cumulative=False, **kwargs)

trapz integration of the moments of the averaged isotropic PSD.

Containers only implement the 1D power-spectrum, so that we use the approximation mapping the 1d PSD to the isotropic PSD

\[C^\mathrm{iso} = \frac{\pi}{q} C^\mathrm{1D}\]
Parameters:

  • self (SurfaceContainer or HeightContainer) – Container with height information or collection of height containsers

  • order (float) – order of moment of the PDF to compute

  • method (see the documentation of the corresponding)

  • method

Return type:

float

SurfaceTopography.Container.Integration.c1d_moment(self, order=1, cumulative=False, **kwargs)

trapz integration of

Parameters:

  • self (SurfaceContainer or HeightContainer) – Container with height information or collection of height containsers

  • order (float) – order of moment of the PDF to compute

  • method (see the documentation of the corresponding)

  • method

Return type:

float

SurfaceTopography.Container.ScaleDependentStatistics module

SurfaceTopography.Container.ScaleDependentStatistics.scale_dependent_statistical_property(self, func, n, unit, nb_points_per_decade=10, distances=None, interpolation='linear', reliable=True, progress_callback=None, threshold=4)

Compute statistical properties of a topography container (i.e. of a set of topographies and line scans) at specific scales. These properties are statistics of derivatives carried out at specific scales, as computed using the derivative pipeline function of the topography and/or line scan.

The specific statistical properties is computed by the func argument. The output of func needs to be homogeneous, i.e. if an array is returned, this array must have the same size independent of the derivative data that is fed into func. The results of func are averaged over all topographies and/or line scans with each topography/line scan weighted equally. (The underlying assumption is that a topography/line scan represents a statistically independent dataset.)

All topographies/line scans are converted to the same unit given by the unit argument before analysis.

Parameters:

  • self (SurfaceContainer) – Container object containing the underlying data sets.

  • func (callable) –

    The function that computes the statistical properties:

    func(dx, dy=None) -> np.ndarray

    A function taking the derivative in x-direction and optionally the derivative in y-direction (only for topographies, i.e. maps). The function needs to be able to ignore the second argument as a container can be a mixture of topographies and line scans. The function can return a scalar value or an array, but the array size must be fixed.

  • n (int) – Order of derivative.

  • unit (str) – Unit of the distance array. All topographies are converted to this unit before the derivative is computed.

  • nb_points_per_decade (int, optional) – Number of points per decade in length for automatic grid construction. (Default: 10)

  • distances (float or np.ndarray, optional) – Characteristic distances at which the derivatives are computed. If this is an array, then the statistical property is computed at each of these distances. (Default: None)

  • interpolation (str, optional) – Interpolation method to use for computing derivatives at distances that do not equal an integer multiple of the grid spacing. Use ‘linear’ for a local liner interpolation or ‘fourier’ for global Fourier interpolation. Note that Fourier interpolation carries large errors for nonperiodic topographies and should be used with care. (Default: ‘linear’)

  • reliable (bool, optional) – Only incorporate data deemed reliable. (Default: True)

  • progress_callback (func, optional) – Function taking iteration and the total number of iterations as arguments for progress reporting. (Default: None)

  • threshold (int, optional) – Defines the minimal amount of data points of the probability distribution to calculate the statistical properties with func and returns a np.nan if the value is below the threshold. E.g. the scipy.stats.kstat function needs at least 4 data points to calculate the 4th cumulant function, otherwise it returns nan or inf (Default: 4)

Returns:

statistical_fingerprint – Array containing the result of func, average over all topographies and line scans. If multiple distances are provided, then this is a masked array that contains results for each distance. If no data exists for a certain distance, then the mask is set to true for that distance.

Return type:

np.ndarray or np.ma.masked_array

Examples

This example yields the the height-difference autocorrelation function in the x-direction, i.e. it should give a result identical to the average of autocorrelation_from_profile executed for all topographies/line scans in the container.

Note that the statistics function (the lambda expression below) needs to be able to accept one argument (for line scans) and two arguments (for topographies).

>>> s = c.scale_dependent_statistical_property(lambda x, y=None: np.var(x), n=1, distance=[0.1, 1.0, 10], unit='um')

SurfaceTopography.Container.SurfaceContainer module

class SurfaceTopography.Container.SurfaceContainer.SurfaceContainer

Bases: object

A list of topographies

apply(name, *args, **kwargs)
classmethod register_function(name, function)
class SurfaceTopography.Container.SurfaceContainer.InMemorySurfaceContainer(topographies=[])

Bases: SurfaceContainer

A list of topographies that whose data is stored in memory

__init__(topographies=[])
class SurfaceTopography.Container.SurfaceContainer.LazySurfaceContainer(readers=[])

Bases: SurfaceContainer

A list of readers with lazy loading of topography data

__init__(readers=[])
read_all()

Load all topographies into memory.

Returns:

container

Return type:

InMemorySurfaceContainer

SurfaceTopography.Container.common module

Bin for small common helper function and classes for containers.

SurfaceTopography.Container.common.bandwidth(self, unit)

Computes lower and upper bound of bandwidth, i.e. of the wavelengths or length scales occurring on any topography within the container. The lower end of the bandwidth is given by the mean of the spacing of the individual points on the line scan. The upper bound is given by the overall length of the line scan.

Parameters:

  • self (SurfaceContainer) – Container object containing the underlying data sets.

  • unit (str) – Unit for reporting the bandwidths.

Returns:

  • lower_bound (float) – Lower bound of the bandwidth.

  • upper_bound (float) – Upper bound of the bandwidth.

SurfaceTopography.Container.common.suggest_length_unit(self, scale)

Compute a suggestion for a unit to diplay container-wider information. The unit is chose to minimize number of digits to the left and right of the decimal point.

Parameters:

scale (str) – ‘linear’: displaying data on a linear axis ‘log’ displaying data on a log-space axis

Returns:

unit – Suggestion for the length unit

Return type:

str

Module contents