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
- 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_path
str
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 whereitem
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 matchkey
.- default
None
orobject
, defaultNone
The value to return if the path or item does not exist.
- item_path
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_path
str
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 whereitem
matches a substring of the item key (case insensitive). Default isFalse
.- 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
).
- item_path
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:
Examples
>>> dict_browser = DictionaryTreeBrowser({}) >>> dict_browser.set_item('First.Second.Third', 3) >>> dict_browser └── First └── Second └── Third = 3
- 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:
- target
object
must contain the (nested) attributes of the whitelist.keys()
- whitelist
dict
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
- target
peakfinders2D
#
- hyperspy.utils.peakfinders2D.clean_peaks(peaks)#
Sort array of peaks and deal with no peaks being found.
- Parameters:
- peaks
numpy.ndarray
Array of found peaks.
- peaks
- Returns:
- peaks
numpy.ndarray
Sorted array, first by peaks[:,1] (y-coordinate) then by peaks[:,0] (x-coordinate), of found peaks.
- NO_PEAKS
str
Flag indicating no peaks found.
- peaks
- 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:
- z
numpy.ndarray
Array of image intensities.
- **kwargs
dict
Keyword arguments to be passed to the
skimage.feature.peak_local_max()
function.
- z
- 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:
- z
numpy.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
- z
- Returns:
- peaks
numpy.ndarray
Peak pixel coordinates with shape (n_peaks, 2).
- peaks
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:
- z
numpy.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.
- z
- Returns:
- peaks
numpy.ndarray
Peak pixel coordinates with shape (n_peaks, 2).
- peaks
- 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:
- Returns:
- peaks
numpy.ndarray
Peak pixel coordinates with shape (n_peaks, 2).
- peaks
- 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:
- z
numpy.ndarray
Matrix of image intensities.
- distance
float
Expected distance between peaks.
- threshold
float
Minimum difference between maximum and minimum filtered images.
- z
- Returns:
- peaks
numpy.ndarray
Peak pixel coordinates with shape (n_peaks, 2).
- peaks
- 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:
- z
numpy.ndarray
Array of image intensities.
- alpha
float
Only maxima above alpha * sigma are found, where sigma is the local, rolling standard deviation of the image.
- window_radius
int
The pixel radius of the circular window for the calculation of the rolling mean and standard deviation.
- convergence_ratio
float
The algorithm will stop finding peaks when the proportion of new peaks being found is less than convergence_ratio.
- z
- Returns:
- peaks
numpy.ndarray
Peak pixel coordinates with with shape (n_peaks, 2).
- peaks
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 theskimage.feature.match_template()
function.- Parameters:
- z
numpy.ndarray
Array of image intensities.
- template
numpy.ndarray
Array containing a single bright disc, similar to those to detect.
- distance
float
Expected distance between peaks.
- threshold
float
Minimum difference between maximum and minimum filtered images.
- **kwargs
dict
Keyword arguments to be passed to the
skimage.feature.match_template()
function.
- z
- Returns:
- peaks
numpy.ndarray
Array of peak coordinates with shape (n_peaks, 2).
- peaks
- 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:
- z
numpy.ndarray
Matrix of image intensities.
- grad_threshold
float
The minimum gradient required to begin a peak search.
- window_size
int
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_cutoff
float
The maximum distance a peak may be from the initial high-gradient point.
- z
- Returns:
- peaks
numpy.ndarray
Peak pixel coordinates with shape (n_peaks, 2).
- peaks
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)