SurfaceTopography.Support package

Submodules

SurfaceTopography.Support.Bibliography module

Tracing bibliography through function calls.

class SurfaceTopography.Support.Bibliography.doi(*args)

Bases: object

To add bibliographic information, simply decorate the function:

``` @doi(‘10.1088/2051-672X/aa51f8’) def power_spectrum(topography):

…

```

The DOIs can be requested by passing a doi argument with an empty set to the function:

` dois = set() power_spectrum(topography, dois=dois) print(dois) # Prints the relevant bibliographic information `

Note that the dois need to be evaluated directly after the function call. Any additional function calls will continue to populate the set with bibliography information.

dois = {}

__init__(*args)

SurfaceTopography.Support.Deprecation module

SurfaceTopography.Support.Deprecation.deprecated(version=None, alternative=None): Emit a deprecation warning for a function.

SurfaceTopography.Support.Interpolation module

Interpolation classes

SurfaceTopography.Support.JSON module

SurfaceTopography.Support.JSON.nan_to_none(obj)

SurfaceTopography.Support.JSON.duration_iso_string(duration)

class SurfaceTopography.Support.JSON.ExtendedJSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Customized JSON encoder that gracefully handles: * numpy arrays, which will be converted to JSON arrays * NaNs and Infs, which will be converted to null * dates and times

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)

encode(obj, *args, **kwargs)

Return a JSON string representation of a Python data structure.

>>> from json.encoder import JSONEncoder
>>> JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

SurfaceTopography.Support.Regression module

Functions for regression of noisy data and resampling/averaging from one grid to another. Currently implemented are simple bin averages and Gaussian process regression.

SurfaceTopography.Support.Regression.make_grid(collocation, min_value, max_value, nb_points=None, nb_points_per_decade=10, dectol=0.01)

Create collocation points.

Parameters:

collocation ({'log', 'quadratic', 'linear', array_like}) – Resampling grid. Specifying ‘log’ yields collocation points equally spaced on a log scale, ‘quadratic’ yields bins with similar number of data points and ‘linear’ yields linear bins. Alternatively, it is possible to explicitly specify the bin edges. If bin edges are explicitly specified, then the other arguments to this function are ignored.
min_value (float) – Minimum value. Note that for log-spaced collocation points, this is the first value - the leftmost bin edge with always be zero.
max_value (float) – Maximum value.
nb_points (int, optional) – Number of bins for averaging. Bins are automatically determined if set to None. (Default: None)
nb_points_per_decade (int, optional) – Number of points per decade for log-spaced collocation points. (Default: None)
dectol (float, optional) – Tolerance for left and right bin edge in terms of decades added to the edges. (Default: 0.01)

Returns:

collocation_points (np.ndarray) – List of collocation points.
bin_edges (np.ndarray) – List of bins edges; collocations points are located within the respective bin. This array contains one more data point than the collocation_points array.

SurfaceTopography.Support.Regression.gaussian_kernel(x1, x2, length_scale=1, signal_variance=1)

SurfaceTopography.Support.Regression.gaussian_log_kernel(x1, x2, length_scale=1, signal_variance=1)

SurfaceTopography.Support.Regression.suggest_kernel_for_grid(collocation, nb_collocation_points, min_value, max_value)

Suggest a kernel function for Gaussian process regression with test locations on a specific grid. The length scale (smoothening scale) of the kernel is set to the characteristic spacing between the sampling output points.

Parameters:

collocation ({'log', 'quadratic', 'linear', array_like}) – Resampling grid. Specifying ‘log’ yields collocation points equally spaced on a log scale, ‘quadratic’ yields bins with similar number of data points and ‘linear’ yields linear bins. Alternatively, it is possible to explicitly specify the bin edges. If bin edges are explicitly specified, then the other arguments to this function are ignored.
nb_collocation_points (int) – Number of collocation points.
min_value (float) – Minimum value. Note that for log-spaced collocation points, this is the first value - the leftmost bin edge with always be zero.
max_value (float) – Maximum value.

Returns:

kernel – Kernel function.

Return type:

func

SurfaceTopography.Support.Regression.bin_average(collocation_points, bin_edges, x, values)

Average values over bins. Returns NaN for bins without data.

Parameters:

collocation_points (np.ndarray) – Collocation points.
bin_edges (array_like) – Edges of bins.
x (array_like) – Collocation points for values array.
values (array_like) – Function values/variates.

Returns:

resampled_collocation_points (np.ndarray) – Collocation points, resampled as average over input x if data is present.
resampled_values (np.ndarray) – Resampled/averaged values.
resampled_variance (np.ndarray) – Variance of resampled data.

SurfaceTopography.Support.Regression.gaussian_process_regression(output_x, x, values, kernel=<function gaussian_kernel>, noise_variance=1e-06)

Gaussian process regression for resampling a simple function.

Parameters:

output_x (array_like) – Collocation points for resampled values.
x (array_like) – Collocation points for values array.
values (array_like) – Function values/variates.
kernel (func, optional) – Kernel function/covariance model. (Default: gaussian_kernel)
noise_variance (float, optional) – Noise variance. (Default: 1e-6)

Returns:

resampled_values – Resampled/averaged values.

Return type:

np.ndarray

SurfaceTopography.Support.Regression.resample(x, values, collocation='log', nb_points=None, min_value=None, max_value=None, nb_points_per_decade=10, method='bin-average')

Resample noisy function data set onto a specific grid.

Parameters:

x (array_like) – Evaluation points.
values (array_like) – Function values.
collocation ({'log', 'quadratic', 'linear', array_like}, optional) – Resampling grid. Specifying ‘log’ yields collocation points equally spaced on a log scale, ‘quadratic’ yields bins with similar number of data points and ‘linear’ yields linear bins. Alternatively, it is possible to explicitly specify the bin edges. If bin_edges are explicitly specified, then rmax and nbins is ignored. (Default: ‘log’)
nb_points (int, optional) – Number of bins for averaging. Bins are automatically determined if set to None. (Default: None)
min_value (float, optional) – Minimum value, is automatically determined from the range of the data if not provided. (Default: None)
max_value (float, optional) – Maximum value, is automatically determined from the range of the data if not provided. (Default: None)
nb_points_per_decade (int, optional) – Number of points per decade for log-spaced collocation points. (Default: None)
method (str, optional) – Method can be ‘bin-average’ for simple bin averaging and ‘gaussian-process’ for Gaussian process regression. (Default: ‘bin-average’)

Returns:

collocation_points (np.ndarray) – Points where the data has been collected.
bin_edges (np.ndarray) – Bin edges.
resampled_values (np.ndarray) – Resampled values.
resampled_variance (np.ndarray) – Variance of resampled data.

SurfaceTopography.Support.Regression.resample_radial(data, physical_sizes=None, collocation='log', nb_points=None, min_radius=0, max_radius=None, nb_points_per_decade=5, full=True, method='bin-average')

Compute radial average of quantities reported on a 2D grid and collect results of collocation points.

Parameters:

data (array_like) – 2D-array of values to be averaged.
physical_sizes ((float, float), optional) – Physical size of the 2D grid. (Default: Size is equal to number of grid points.)
collocation ({'log', 'quadratic', 'linear', array_like}, optional) – Resampling grid. Specifying ‘log’ yields collocation points equally spaced on a log scale, ‘quadratic’ yields bins with similar number of data points and ‘linear’ yields linear bins. Alternatively, it is possible to explicitly specify the bin edges. If bin_edges are explicitly specified, then rmax and nbins is ignored. (Default: ‘log’)
nb_points (int, optional) – Number of bins for averaging. Bins are automatically determined if set to None. (Default: None)
min_radius (float, optional) – Minimum radius. (Default: 0)
max_radius (float, optional) – Maximum radius, is automatically determined from the range of the data if not provided. (Default: None)
nb_points_per_decade (int, optional) – Number of points per decade for log-spaced collocation points. (Default: None)
full (bool, optional) – Number of quadrants contained in data. True: Full radial average from 0 to 2*pi. False: Only the one quarter of the full circle is present. Radial average from 0 to pi/2. (Default: True)
method (str, optional) – Method can be ‘bin-average’ for simple bin averaging and ‘gaussian-process’ for Gaussian process regression. (Default: ‘bin-average’)

Returns:

collocation_points (np.ndarray) – Points where the data has been collected.
bin_edges (np.ndarray) – Bin edges.
resampled_values (np.ndarray) – Resampled values.
resampled_variance (np.ndarray) – Variance of resampled data.

SurfaceTopography.Support.UnitConversion module

SurfaceTopography.Support.UnitConversion.is_length_unit(s): Returns true if the unit is a length unit (m, mm, etc)

SurfaceTopography.Support.UnitConversion.get_unit_conversion_factor(from_unit, to_unit)

Compute factor for conversion from from_unit to to_unit.

Parameters:

from_unit (str) – Name of source unit
to_unit (str) – Name of targe unit

Returns:

fac – Unit conversion factors. A quantity in from_unit is converted to to_unit by multiplication with this factor.

Return type:

float

SurfaceTopography.Support.UnitConversion.mangle_length_unit_utf8(unit)

Convert unit string to normalized UTF-8 unit string, e.g. converts ‘um’ to ‘µm’ and makes sure ‘µ’ is MICRO SIGN (00B5) and not GREEK SMALL LETTER MU (03BC).

Parameters:: unit (str) – Name of unit
Returns:: output_unit – Mangled name of unit
Return type:: str

SurfaceTopography.Support.UnitConversion.mangle_length_unit_ascii(unit)

Convert unit string to ASCII representation, e.g. converts ‘µm’ to ‘um’.

Parameters:: unit (str) – Name of unit
Returns:: output_unit – Mangled name of unit
Return type:: str

SurfaceTopography.Support.UnitConversion.suggest_length_unit(scale, lower_in_meters, upper_in_meters)

Suggest a length unit for representing data in a certain range. E.g. data in the range from 1e-3 to 1e-2 m is best represented by um.

Parameters:

scale (str) – ‘linear’: displaying data on a linear axis ‘log’ displaying data on a log-space axis
lower_in_meters (float) – Lower bound of range in meters
upper_in_meters (float) – Upper bound of range in meters

Returns:

unit – Suggestion for the length unit

Return type:

str

SurfaceTopography.Support.UnitConversion.suggest_length_unit_for_data(scale, data, unit)

Suggest a length unit for representing a data set.

Parameters:

scale (str) – ‘linear’: displaying data on a linear axis ‘log’ displaying data on a log-space axis
data (array_like) – Data set that needs representing (e.g. in a color bar)
unit (str) – Unit of the data set

Returns:

unit – Suggestion for the length unit

Return type:

str

SurfaceTopography.Support.UnitConversion.find_length_unit_in_string(s): Check the string s contains any length information

Module contents

SurfaceTopography.Support.toiter(obj): If obj is scalar, wrap it into a list

SurfaceTopography.Support.fromiter(result, obj): If obj is scalar, return first element of result list

SurfaceTopography.Support.build_tuple(quantities, **kwargs)

Build a custom tuple, where each of the characters in quantities represents a certain datum.

Parameters:

quantities (str) – String with quantities, e.g. ‘dhj’ returns a 3-tuple with the datums associated with the characters ‘d’, ‘h’ and ‘j’.
**kwargs (dict) – Individual datums, e.g. d=…, h=…, j=….

Returns:

datum – Tuple of length quantities.

Return type:

tuple