Utils#

API of classes, which are not part of the hyperspy.api namespace but used by HyperSpy signals.

class hyperspy.misc.utils.DictionaryTreeBrowser(dictionary=None, double_lines=False, lazy=True)#

Bases: object

A class to comfortably browse a dictionary using a CLI.

In addition to accessing the values using dictionary syntax the class enables navigating a dictionary that constains nested dictionaries as attribures of nested classes. Also it is an iterator over the (key, value) items. The __repr__ method provides pretty tree printing. Private keys, i.e. keys that starts with an underscore, are not printed, counted when calling len nor iterated.

Examples

>>> tree = DictionaryTreeBrowser()
>>> tree.set_item("Branch.Leaf1.color", "green")
>>> tree.set_item("Branch.Leaf2.color", "brown")
>>> tree.set_item("Branch.Leaf2.caterpillar", True)
>>> tree.set_item("Branch.Leaf1.caterpillar", False)
>>> tree
└── Branch
    ├── Leaf1
    │   ├── caterpillar = False
    │   └── color = green
    └── Leaf2
        ├── caterpillar = True
        └── color = brown
>>> tree.Branch
├── Leaf1
│   ├── caterpillar = False
│   └── color = green
└── Leaf2
    ├── caterpillar = True
    └── color = brown
>>> for label, leaf in tree.Branch:
...     print("%s is %s" % (label, leaf.color))
Leaf1 is green
Leaf2 is brown
>>> tree.Branch.Leaf2.caterpillar
True
>>> "Leaf1" in tree.Branch
True
>>> "Leaf3" in tree.Branch
False
>>>

add_dictionary(dictionary, double_lines=False)#: Add new items from dictionary.

add_node(node_path)#

Adds all the nodes in the given path if they don’t exist.

Parameters:

node_path: str: The nodes must be separated by full stops (periods).

Examples

>>> dict_browser = DictionaryTreeBrowser({})
>>> dict_browser.add_node('First.Second')
>>> dict_browser.First.Second = 3
>>> dict_browser
└── First
    └── Second = 3

as_dictionary()#: Returns its dictionary representation.

copy()#: Returns a shallow copy using copy.copy().

deepcopy()#: Returns a deep copy using copy.deepcopy().

export(filename, encoding='utf8')#

Export the dictionary to a text file

Parameters:

filenamestr: The name of the file without the extension that is txt by default
encodingstr: The encoding to be used.

get_item(item_path, default=None, full_path=True, wild=False, return_path=False)#

Given a path, return it’s value if it exists, or default value if missing. May also perform a search whether an item key exists and then returns the value or a list of values for multiple occurences of the key – optionally returns the full path(s) in addition to its value(s).

The nodes of the path are separated using periods.

Parameters:

item_pathstr: A string describing the path with each item separated by full stops (periods)
full_pathbool, default True: If True, the full path to the item has to be given. If False, a search for the item key is performed (can include additional nodes preceding they key separated by full stops).
wildbool: Only applies if full_path=False. If True, searches for any items where item matches a substring of the item key (case insensitive). Default is False.
return_pathbool: Only applies if full_path=False. Default False. If True, returns an additional list of paths to the item(s) that match key.
defaultNone or object, default None: The value to return if the path or item does not exist.

Examples

>>> dict = {'To' : {'be' : True}}
>>> dict_browser = DictionaryTreeBrowser(dict)
>>> dict_browser.get_item('To')
└── be = True
>>> dict_browser.get_item('To.be')
True
>>> dict_browser.get_item('To.be.or', 'default_value')
'default_value'
>>> dict_browser.get_item('be', full_path=False)
True

has_item(item_path, default=None, full_path=True, wild=False, return_path=False)#

Given a path, return True if it exists. May also perform a search whether an item exists and optionally returns the full path instead of boolean value.

The nodes of the path are separated using periods.

Parameters:

item_pathstr: A string describing the path with each item separated by full stops (periods).
full_pathbool, default True: If True, the full path to the item has to be given. If False, a search for the item key is performed (can include additional nodes preceding they key separated by full stops).
wildbool, default True: Only applies if full_path=False. If True, searches for any items where item matches a substring of the item key (case insensitive). Default is False.
return_pathbool, default False: Only applies if full_path=False. If False, a boolean value is returned. If True, the full path to the item is returned, a list of paths for multiple matches, or default value if it does not exist.
default: The value to return for path if the item does not exist (default is None).

Examples

>>> dict = {'To' : {'be' : True}}
>>> dict_browser = DictionaryTreeBrowser(dict)
>>> dict_browser.has_item('To')
True
>>> dict_browser.has_item('To.be')
True
>>> dict_browser.has_item('To.be.or')
False
>>> dict_browser.has_item('be', full_path=False)
True
>>> dict_browser.has_item('be', full_path=False, return_path=True)
'To.be'

keys()#: Returns a list of non-private keys.

process_lazy_attributes()#: Run the DictionaryTreeBrowser machinery for the lazy attributes.

set_item(item_path, value)#

iven the path and value, create the missing nodes in the path and assign the given value.

Parameters:

item_pathstr: A string describing the path with each item separated by a full stop (periods)
valueobject: The value to assign to the given path.

Examples

>>> dict_browser = DictionaryTreeBrowser({})
>>> dict_browser.set_item('First.Second.Third', 3)
>>> dict_browser
└── First
   └── Second
        └── Third = 3

class hyperspy.misc.utils.TupleSA(iterable=(), /)#

Bases: tuple

A tuple that can set the attributes of its items

get(*args)#

Get the attributes of its items

Parameters:

argslist: The names of the attributes to get.

Returns:

outputdict: The name of the attributes and their values.

set(**kwargs)#

Set the attributes of its items

Parameters:

kwargsdict: The name of the attributes and their values. If a value is iterable, then attribute of each item of the tuple will be set to each of the values.

hyperspy.misc.export_dictionary.export_to_dictionary(target, whitelist, dic, fullcopy=True)#

Exports attributes of target from whitelist.keys() to dictionary dic All values are references only by default.

Parameters:

targetobject

must contain the (nested) attributes of the whitelist.keys()

whitelistdict

A dictionary, keys of which are used as attributes for exporting. Key ‘self’ is only available with tag ‘id’, when the id of the target is saved. The values are either None, or a tuple, where:

the first item a string, which containts flags, separated by commas.
the second item is None if no ‘init’ flag is given, otherwise the object required for the initialization.

The flag conventions are as follows:

‘init’: object used for initialization of the target. The object is saved in the tuple in whitelist
‘fn’: the targeted attribute is a function, and may be pickled. A tuple of (thing, value) will be exported to the dictionary, where thing is None if function is passed as-is, and True if cloudpickle package is used to pickle the function, with the value as the result of the pickle.
‘id’: the id of the targeted attribute is exported (e.g. id(target.name))
‘sig’: The targeted attribute is a signal, and will be converted to a dictionary if fullcopy=True

dict

A dictionary where the object will be exported

bool

Copies of objects are stored, not references. If any found, functions will be pickled and signals converted to dictionaries

`peakfinders2D`#

hyperspy.utils.peakfinders2D.clean_peaks(peaks)#

Sort array of peaks and deal with no peaks being found.

Parameters:

peaksnumpy.ndarray: Array of found peaks.

Returns:

peaksnumpy.ndarray: Sorted array, first by peaks[:,1] (y-coordinate) then by peaks[:,0] (x-coordinate), of found peaks.
NO_PEAKSstr: Flag indicating no peaks found.

hyperspy.utils.peakfinders2D.find_local_max(z, **kwargs)#

Method to locate positive peaks in an image by local maximum searching.

This function wraps skimage.feature.peak_local_max() function and sorts the results for consistency with other peak finding methods.

Parameters:

znumpy.ndarray: Array of image intensities.
**kwargsdict: Keyword arguments to be passed to the skimage.feature.peak_local_max() function.

Returns:

numpy.ndarray: Peak pixel coordinates with shape (n_peaks, 2).

hyperspy.utils.peakfinders2D.find_peaks_dog(z, min_sigma=1.0, max_sigma=50.0, sigma_ratio=1.6, threshold=0.2, overlap=0.5, exclude_border=False)#

Method to locate peaks via the Difference of Gaussian Matrices method.

This function wraps skimage.feature.blob_dog() function and sorts the results for consistency with other peak finding methods.

Parameters:

znumpy.ndarray: 2-d array of intensities
min_sigma, max_sigma, sigma_ratio, threshold, overlap, exclude_border: Additional parameters to be passed to the skimage.feature.blob_dog() function

Returns:

peaksnumpy.ndarray: Peak pixel coordinates with shape (n_peaks, 2).

Notes

While highly effective at finding even very faint peaks, this method is: sensitive to fluctuations in intensity near the edges of the image.

hyperspy.utils.peakfinders2D.find_peaks_log(z, min_sigma=1.0, max_sigma=50.0, num_sigma=10, threshold=0.2, overlap=0.5, log_scale=False, exclude_border=False)#

Method to locate peaks via the Laplacian of Gaussian Matrices method.

This function wraps skimage.feature.blob_log() function and sorts the results for consistency with other peak finding methods.

Parameters:

znumpy.ndarray: Array of image intensities.
min_sigma, max_sigma, num_sigma, threshold, overlap, log_scale, exclude_border: Additional parameters to be passed to the skimage.feature.blob_log() function.

Returns:

peaksnumpy.ndarray: Peak pixel coordinates with shape (n_peaks, 2).

hyperspy.utils.peakfinders2D.find_peaks_max(z, alpha=3.0, distance=10)#

Method to locate positive peaks in an image by local maximum searching.

Parameters:

alphafloat: Only maxima above alpha * sigma are found, where sigma is the standard deviation of the image.
distanceint: When a peak is found, all pixels in a square region of side 2 * distance are set to zero so that no further peaks can be found in that region.

Returns:

peaksnumpy.ndarray: Peak pixel coordinates with shape (n_peaks, 2).

hyperspy.utils.peakfinders2D.find_peaks_minmax(z, distance=5.0, threshold=10.0)#

Method to locate the positive peaks in an image by comparing maximum and minimum filtered images.

Parameters:

znumpy.ndarray: Matrix of image intensities.
distancefloat: Expected distance between peaks.
thresholdfloat: Minimum difference between maximum and minimum filtered images.

Returns:

peaksnumpy.ndarray: Peak pixel coordinates with shape (n_peaks, 2).

hyperspy.utils.peakfinders2D.find_peaks_stat(z, alpha=1.0, window_radius=10, convergence_ratio=0.05)#

Method to locate positive peaks in an image based on statistical refinement and difference with respect to mean intensity.

Parameters:

znumpy.ndarray: Array of image intensities.
alphafloat: Only maxima above alpha * sigma are found, where sigma is the local, rolling standard deviation of the image.
window_radiusint: The pixel radius of the circular window for the calculation of the rolling mean and standard deviation.
convergence_ratiofloat: The algorithm will stop finding peaks when the proportion of new peaks being found is less than convergence_ratio.

Returns:

peaksnumpy.ndarray: Peak pixel coordinates with with shape (n_peaks, 2).

Notes

Implemented as described in the PhD thesis of Thomas White, University of Cambridge, 2009, with minor modifications to resolve ambiguities.

The algorithm is as follows:

Adjust the contrast and intensity bias of the image so that all pixels have values between 0 and 1.
For each pixel, determine the mean and standard deviation of all pixels inside a circle of radius 10 pixels centered on that pixel.
If the value of the pixel is greater than the mean of the pixels in the circle by more than one standard deviation, set that pixel to have an intensity of 1. Otherwise, set the intensity to 0.
Smooth the image by convovling it twice with a flat 3x3 kernel.
Let k = (1/2 - mu)/sigma where mu and sigma are the mean and standard deviations of all the pixel intensities in the image.
For each pixel in the image, if the value of the pixel is greater than mu + k*sigma set that pixel to have an intensity of 1. Otherwise, set the intensity to 0.
Detect peaks in the image by locating the centers of gravity of regions of adjacent pixels with a value of 1.
Repeat #4-7 until the number of peaks found in the previous step converges to within the user defined convergence_ratio.

hyperspy.utils.peakfinders2D.find_peaks_xc(z, template, distance=5, threshold=0.5, **kwargs)#

Find peaks in the cross correlation between the image and a template by using the find_peaks_minmax() function to find the peaks on the cross correlation result obtained using the skimage.feature.match_template() function.

Parameters:

znumpy.ndarray: Array of image intensities.
templatenumpy.ndarray: Array containing a single bright disc, similar to those to detect.
distancefloat: Expected distance between peaks.
thresholdfloat: Minimum difference between maximum and minimum filtered images.
**kwargsdict: Keyword arguments to be passed to the skimage.feature.match_template() function.

Returns:

peaksnumpy.ndarray: Array of peak coordinates with shape (n_peaks, 2).

hyperspy.utils.peakfinders2D.find_peaks_zaefferer(z, grad_threshold=0.1, window_size=40, distance_cutoff=50.0)#

Method to locate positive peaks in an image based on gradient thresholding and subsequent refinement within masked regions.

Parameters:

znumpy.ndarray: Matrix of image intensities.
grad_thresholdfloat: The minimum gradient required to begin a peak search.
window_sizeint: The size of the square window within which a peak search is conducted. If odd, will round down to even. The size must be larger than 2.
distance_cutofffloat: The maximum distance a peak may be from the initial high-gradient point.

Returns:

peaksnumpy.ndarray: Peak pixel coordinates with shape (n_peaks, 2).

Notes

Implemented as described in Zaefferer “New developments of computer-aided crystallographic analysis in transmission electron microscopy” J. Ap. Cryst. This version by Ben Martineau (2016)

Utils#

peakfinders2D#

`peakfinders2D`#