MaskStack

class Stoner.Image.MaskStack(*args, **kargs)[source]

Bases: MaskStackMixin, KerrStackMixin, ImageStack

Represent a set of masks for Kerr images.

Attributes Summary

basenames

Return a list of just the filename parts of the objectFolder.

clone

Clone just does a deepcopy as a property for compatibility with Stoner.Core.DataFile.

debug

Just read the local debug value.

defaults

Build a single list of all of our defaults by iterating over the __mro__, caching the result.

depth

Give the maximum number of levels of group below the current objectFolder.

directory

Just alias directory to root now.

each

Return a Stoner.folders.each.item proxy object.

fields

Produce an array of field values from the metadata.

files

Return an iterator of potentially unloaded named objects.

groups

Subfolders are held in an ordered dictionary of groups.

images

Iterate over just the images in the Folder.

imarray

Produce the 3D stack of images - as [image,x,y].

instance

Return a default instance of the type of object in the folder.

is_empty

Return True if the folder is empty.

key

Override the parent class key to use the directory attribute.

layout

Return a tuple that describes the number of files and groups in the folder.

loaded

Iterate only over those members of the folder in memory.

loader

Return a callable that will load the files on demand.

ls

List just the names of the objects in the folder.

lsgrp

Return a list of the groups as a generator.

max_size

Get the biggest image dimensions in the stack.

metadata

Return a Stoner.folders.metadata.MetadataProxy object.

mindepth

Give the minimum number of levels of group below the current objectFolder.

not_empty

Iterate over the objectFolder that checks whether the loaded metadataObject objects have any data.

not_loaded

Return an array of True/False for whether we've loaded a metadataObject yet.

objects

Return the objects in the folder are stored in a regexpDict.

pattern

Provide support for getting the pattern attribute.

root

Return the real folder root.

setas

Return the proxy for the setas attribute for each object in the folder.

shape

Return the stack shape - after re-ordering the indices.

size

Return the size of an individual image or False if not all images are the same size.

trunkdepth

Return the number of levels of group before a group with files is found.

type

Return the (sub)class of the Stoner.Core.metadataObject instances.

Methods Summary

HcMap([threshold, correct_drift, baseimage, ...])

Produce a map of the switching field at every pixel in the stack.

add_group(key)

Add a new group to the current baseFolder with the given key.

align(*args, **kargs)

Align each image in the folder to the reference image.

all()

Iterate over all the files in the Folder and all it's sub Folders recursely.

append(value)

Append an item to the folder object.

apply_all(func, *args, **kargs)

Apply function to all images in the stack.

as_stack()

Return a ImageStack of the images in the current group.

asfloat([normalise, clip, clip_negative])

Convert stack to floating point type.

average([weights, _box, _metadata])

Get an array of average pixel values for the stack.

average_Hcmap([weights, ignore_zeros])

Get an array of average pixel values for the stack.

clear()

Clear the subgroups.

compress([base, key, keep_terminal])

Compresses all empty groups from the root up until the first non-empty group is located.

convert(dtype[, force_copy, uniform, normalise])

Convert an image to the requested data-type.

correct_drifts(refindex[, threshold, ...])

Align images to correct for image drift.

count(value)

Provide a count method like a sequence.

crop_stack(box)

Crop the imagestack to a box.

crop_text()

Crop the bottom text area from a standard Kermit image across the complete stack.

denoise_thresh([denoise_weight, thresh, invert])

Apply denoise then threshold images.

dtype_limits([clip_negative])

Return intensity limits, i.e. (min, max) tuple, of imarray dtype.

extend(values)

S.extend(iterable) -- extend sequence by appending elements from the iterable

fetch()

Preload the contents of the DiskBasedFolderMixin.

file(name, value[, create, pathsplit])

recursely add groups in order to put the named value into a virtual tree of baseFolder.

filter([filter, invert, copy, recurse, prune])

Filter the current set of files by some criterion.

filterout(filter[, copy, recurse, prune])

Synonym for self.filter(filter,invert=True).

find_threshold([testim, mask])

Try to find the threshold value at which the image switches.

flatten([depth])

Compresses all the groups and sub-groups iunto a single flat file list.

from_tiff(filename, **kargs)

Create a new ImageArray from a tiff file.

get(name[, default])

Return either a sub-group or named object from this folder.

getlist(**kargs)

Scan the current directory, optionally recursively to build a list of filenames.

group(key)

Sort Files into a series of objectFolders according to the value of the key.

hysteresis([mask])

Make a hysteresis loop of the average intensity in the given images.

index(value[, start, end])

Provide an index method like a sequence.

index_to_field(index_map)

Convert an image of index values into an image of field values.

insert(index, value)

Implement the insert method with the option to append as well.

items()

Return the key,value pairs for the subbroups of this folder.

keep_latest()

Filter out earlier revisions of files with the same name.

keys()

Return the keys used to access the sub-=groups of this folder.

loadgroup()

Load all files from this group into memory.

make_name([value])

Construct a name from the value object if possible.

mask_select()

Run the ImageFile.mask.select() on each image.

mean([_box, _metadata])

Calculate the mean value of all the images in the stack.

montage(*args, **kargs)

Call the plot method for each metadataObject, but switching to a subplot each time.

on_load_process(tmp)

Carry out processing on a newly loaded file to set means and extra metadata.

pop([name, default])

Return and remove either a subgroup or named object from this folder.

popitem()

Return the most recent subgroup from this folder.

prune([name])

Remove any empty groups from the objectFolder (and subgroups).

remove(value)

S.remove(value) -- remove first occurrence of value.

reverse()

S.reverse() -- reverse IN PLACE

save([root])

Save the entire data folder out to disc using the groups as a directory tree.

select(*args, **kargs)

Select a subset of the objects in the folder based on flexible search criteria on the metadata.

setdefault(k[, d])

Return or set a subgroup or named object.

show()

Pass through to Stoner.Image.ImageFolder.view().

slice_metadata(key[, output])

Return an array of the metadata values for each item/file in the top level group.

sort([key, reverse, recurse])

Sort the files by some key.

stable_mask([tolerance, comparison])

Produce a mask of areas of the image that are changing little over the stack.

stddev([weights, _box, _metadata])

Calculate weighted standard deviation for stack.

stderr([weights, _box, _metadata])

Calculate standard error in the stack average.

subtract(background)

Subtract a background image (or index) from all images in the stack.

switch_index([saturation_end, saturation_value])

Construct a map of switching points in a hysteresis stack.

to_tiff(filename)

Save the ImageArray as a tiff image with metadata.

unflatten()

Take the file list an unflattens them according to the file paths.

unload([name])

Remove the instance from memory without losing the name in the Folder.

update(other)

Update this folder with a dictionary or another folder.

values()

Return the sub-groups of this folder.

walk_groups(walker, **kargs)

Walk through a hierarchy of groups and calls walker for each file.

zip_groups(groups)

Return a list of tuples of metadataObjects drawn from the specified groups.

Attributes Documentation

basenames

Return a list of just the filename parts of the objectFolder.

clone

Clone just does a deepcopy as a property for compatibility with Stoner.Core.DataFile.

debug

Just read the local debug value.

defaults

Build a single list of all of our defaults by iterating over the __mro__, caching the result.

depth

Give the maximum number of levels of group below the current objectFolder.

directory

Just alias directory to root now.

each

Return a Stoner.folders.each.item proxy object.

This is for calling attributes of the member type of the folder.

fields

Produce an array of field values from the metadata.

files

Return an iterator of potentially unloaded named objects.

groups

Subfolders are held in an ordered dictionary of groups.

images

Iterate over just the images in the Folder.

imarray

Produce the 3D stack of images - as [image,x,y].

instance

Return a default instance of the type of object in the folder.

is_empty

Return True if the folder is empty.

key

Override the parent class key to use the directory attribute.

layout

Return a tuple that describes the number of files and groups in the folder.

loaded

Iterate only over those members of the folder in memory.

loader

Return a callable that will load the files on demand.

ls

List just the names of the objects in the folder.

lsgrp

Return a list of the groups as a generator.

max_size

Get the biggest image dimensions in the stack.

metadata

Return a Stoner.folders.metadata.MetadataProxy object.

This allows for operations on combined metadata.

mindepth

Give the minimum number of levels of group below the current objectFolder.

not_empty

Iterate over the objectFolder that checks whether the loaded metadataObject objects have any data.

Returns the next non-empty DatFile member of the objectFolder.

Note

not_empty will also silently skip over any cases where loading the metadataObject object will raise and exception.

not_loaded

Return an array of True/False for whether we’ve loaded a metadataObject yet.

objects

Return the objects in the folder are stored in a regexpDict.

pattern

Provide support for getting the pattern attribute.

root

Return the real folder root.

setas

Return the proxy for the setas attribute for each object in the folder.

shape

Return the stack shape - after re-ordering the indices.

size

Return the size of an individual image or False if not all images are the same size.

trunkdepth

Return the number of levels of group before a group with files is found.

type

Return the (sub)class of the Stoner.Core.metadataObject instances.

Methods Documentation

HcMap(threshold=0.5, correct_drift=False, baseimage=0, quiet=True, saturation_end=True, saturation_white=True, extra_info=False)

Produce a map of the switching field at every pixel in the stack.

It needs the stack to start saturated one way and end saturated the other way.

Keyword Arguments:
  • threshold (float) – the threshold value for the intensity switching. This will need to be tuned for each stack

  • correct_drift (bol) – whether to correct drift on the image stack before proceding

  • baseimage (int or ImageArray) – we use drift correction from the baseimage.

  • saturation_end (bool) – last image in stack is closest to saturation

  • saturation_white (bool) – bright pixels are saturated dark pixels are not yet switched

  • quiet – bool choose wether to output status updates as print messages

  • extra_info (bool) – choose whether to return intermediate calculation steps as an extra dictionary

Returns:

(ImageArray) – The map of field values for switching of each pixel in the stack

add_group(key)

Add a new group to the current baseFolder with the given key.

Parameters:

key (string) – A hashable value to be used as the dictionary key in the groups dictionary

Returns:

A copy of the objectFolder

Note

If key already exists in the groups dictionary then no action is taken.

Todo

Propagate any extra attributes into the groups.

align(*args, **kargs)

Align each image in the folder to the reference image.

Parameters:

ref (str, int, ImageFile, ImageArray or 2D array) – The reference image to align to. If a string or an int, then this is used to lookup the corresponding member of the ImageFolder which is then used. ImageFiles, ImageArrays and 2D arrays are used directly as reference images.

Keyword Arguments:
  • method (str) – The method is passed to the Stone.Image.ImageArray.align method to control how the image alignment is done. By default the ‘Scharr’ method is used.

  • box (int, float, tuple of ints or floats) – Specifies a subset of the images to be used to calculate the alignment with.

  • scale (int) – Magnification factor to scale the image by before doing the alignment for better sub=pixel alignments.

Returns:

The aligned ImageFolder.

all()

Iterate over all the files in the Folder and all it’s sub Folders recursely.

Yields:

(path/filename,file)

append(value)

Append an item to the folder object.

apply_all(func, *args, **kargs)

Apply function to all images in the stack.

Parameters:
  • func (string or callable) – if string it must be a function reachable by ImageArray

  • quiet (bool) – if False print ‘.’ for every iteration

Note

Further args, kargs are passed through to the function

as_stack()

Return a ImageStack of the images in the current group.

asfloat(normalise=True, clip=False, clip_negative=False, **kargs)

Convert stack to floating point type.

Keyword Arguments:
  • normalise (bool) – normalise the image to the max value of current int type

  • clip (bool) – clip resulting range to values between -1 and 1

  • clip_negative (bool) – clip range further to 0,1

Notes

Analogous behaviour to ImageFile.asfloat()

If currently an int type and normalise then floats will be normalised to the maximum allowed value of the int type. If currently a float type then no change occurs. If clip_negative then clip values outside the range 0,1

average(weights=None, _box=False, _metadata='first')

Get an array of average pixel values for the stack.

Pass through to numpy average

Keyword Arguments:
  • _box (crop box) – Specifies the region of the array to be averaged. Default - entire image

  • _metadata (str) – Specifies how to generate metadata for the averaged image. - “first”: Just ise the first image’s metadata - “common”: Find the common metadata across all images - “none’: no metadata from images.

Returns:

average(ImageArray) – average values

average_Hcmap(weights=None, ignore_zeros=False)

Get an array of average pixel values for the stack.

Return average of pixel values in the stack.

Keyword Arguments:

zeros (ignore) – Weight zero values in an image as 0 in the averaging.

Returns:

average(ImageArray) – average values

clear()

Clear the subgroups.

compress(base=None, key='.', keep_terminal=False)

Compresses all empty groups from the root up until the first non-empty group is located.

Returns:

A copy of the now flattened DatFolder

convert(dtype, force_copy=False, uniform=False, normalise=True)

Convert an image to the requested data-type.

Warnings are issued in case of precision loss, or when negative values are clipped during conversion to unsigned integer types (sign loss).

Floating point values are expected to be normalized and will be clipped to the range [0.0, 1.0] or [-1.0, 1.0] when converting to unsigned or signed integers respectively.

Numbers are not shifted to the negative side when converting from unsigned to signed integer types. Negative values will be clipped when converting to unsigned integers.

Parameters:
  • image (ndarray) – Input image.

  • dtype (dtype) – Target data-type.

  • force_copy (bool) – Force a copy of the data, irrespective of its current dtype.

  • uniform (bool) – Uniformly quantize the floating point range to the integer range. By default (uniform=False) floating point values are scaled and rounded to the nearest integers, which minimizes back and forth conversion errors.

  • normalise (bool) – When converting from int types to float normalise the resulting array by the maximum allowed value of the int type.

References

  1. DirectX data conversion rules. http://msdn.microsoft.com/en-us/library/windows/desktop/dd607323%28v=vs.85%29.aspx

2, Data Conversions.

In “OpenGL ES 2.0 Specification v2.0.25”, pp 7-8. Khronos Group, 2010.

3, Proper treatment of pixels as integers. A.W. Path.

In “Graphics Gems I”, pp 249-256. Morgan Kaufmann, 1990.

4, Dirty Pixels. J. Blinn.

In “Jim Blinn’s corner: Dirty Pixels”, pp 47-57. Morgan Kaufmann, 1998.

correct_drifts(refindex, threshold=0.005, upsample_factor=50, box=None)

Align images to correct for image drift.

Pass through to ImageArray.corret_drift.

Arg:
refindex: int or str

index or name of the reference image to use for zero drift

Keyword Arguments:
  • threshold (float) – see ImageArray.correct_drift

  • upsample_factor (int) – see ImageArray.correct_drift

  • box – see ImageArray.correct_drift

count(value)

Provide a count method like a sequence.

Parameters:

value (str, regexp, or Stoner.Core.metadataObject) – The thing to count matches for.

Returns:

(int) – The number of matching metadataObject instances.

Notes

If name is a string, then matching is based on either exact matches of the name, or if it includes a * or ? then the basis of a globbing match. name may also be a regular expressiuon, in which case matches are made on the basis of the match with the name of the metadataObject. Finally, if name is a metadataObject, then it matches for an equyality test.

crop_stack(box)

Crop the imagestack to a box.

Parameters:

box (array or list of type int) – [xmin,xmax,ymin,ymax]

Returns:

(ImageStack) – cropped images

crop_text()

Crop the bottom text area from a standard Kermit image across the complete stack.

Returns: (ImageArray):

cropped image

denoise_thresh(denoise_weight=0.1, thresh=0.5, invert=False)

Apply denoise then threshold images.

Returns:

(ndarray) MaskStack – True for values greater than thresh, False otherwise else return True for values between thresh and 1

dtype_limits(clip_negative=True)

Return intensity limits, i.e. (min, max) tuple, of imarray dtype.

Keyword Arguments:

clip_negative (bool) – If True, clip the negative range (i.e. return 0 for min intensity) even if the image dtype allows negative values.

Returns:

(imin,imax) (tuple) – Lower and upper intensity limits.

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

fetch()

Preload the contents of the DiskBasedFolderMixin.

With multiprocess enabled this will parallel load the contents of the folder into memory.

file(name, value, create=True, pathsplit=None)

recursely add groups in order to put the named value into a virtual tree of baseFolder.

Parameters:
  • name (str) – A name (which may be a nested path) of the object to file.

  • value (metadataObject) – The object to be filed - it should be an instance of baseFolder.type.

Keyword Aprameters:
create(bool):

Whether to create missing groups or to raise an error (default True to create groups).

pathsplit(str or None):

Character to use to split the name into path components. Defaults to using os.path.split()

Returns:

(baseFolder) – A reference to the group where the value was eventually filed

filter(filter=None, invert=False, copy=False, recurse=False, prune=True)

Filter the current set of files by some criterion.

Parameters:

filter (string or callable) – Either a string flename pattern or a callable function which takes a single parameter x which is an instance of a metadataObject and evaluates True or False

Keyword Arguments:
  • invert (bool) – Invert the sense of the filter (done by doing an XOR with the filter condition

  • copy (bool) – If set True then the DataFolder is copied before being filtered. Default is False - work in place.

  • recurse (bool) – If True, apply the filter recursely to all groups. Default False

  • prune (bool) – If True, execute a baseFolder.prune() to remove empty groups after filering

Returns:

The current objectFolder object

filterout(filter, copy=False, recurse=False, prune=True)

Synonym for self.filter(filter,invert=True).

Parameters:

filter (string or callable) – Either a string flename pattern or a callable function which takes a single parameter x which is an instance of a metadataObject and evaluates True or False

Keyword Arguments:
  • copy (bool) – If set True then the DataFolder is copied before being filtered. Default is False - work in place.

  • recurse (bool) – If True, apply the filter recursely to all groups. Default False

  • prune (bool) – If True, execute a baseFolder.prune() to remove empty groups after filering

Returns:

The current objectFolder object with the files in the file list filtered.

find_threshold(testim=None, mask=None)

Try to find the threshold value at which the image switches.

Takes it as the median value of the testim. Masks values where the difference is less than tolerance in case part of the image is irrelevant.

flatten(depth=None)

Compresses all the groups and sub-groups iunto a single flat file list.

Keyword Arguments:
  • ) (depth) –

  • level. (Only flatten ub-=groups that are within (depth of the deepest) –

Returns:

A copy of the now flattened DatFolder

classmethod from_tiff(filename, **kargs)

Create a new ImageArray from a tiff file.

get(name, default=None)

Return either a sub-group or named object from this folder.

getlist(**kargs)

Scan the current directory, optionally recursively to build a list of filenames.

Keyword Arguments:
  • recursive (bool) – Do a walk through all the directories for files

  • directory (string or False) – Either a string path to a new directory or False to open a dialog box or not set in which case existing directory is used.

  • flatten (bool) – After scanning the directory tree, flaten all the subgroupos to make a flat file list. (this is the previous behaviour of objectFolder.getlist())

Returns:

A copy of the current DataFoder directory with the files stored in the files attribute

getlist() scans a directory tree finding files that match the pattern. By default it will recurse through the entire directory tree finding sub directories and creating groups in the data folder for each sub directory.

group(key)

Sort Files into a series of objectFolders according to the value of the key.

Parameters:

key (string or callable or list) – Either a simple string or callable function or a list. If a string then it is interpreted as an item of metadata in each file. If a callable function then takes a single argument x which should be an instance of a metadataObject and returns some vale. If key is a list then the grouping is done recursely for each element in key.

Returns:

A copy of the current objectFolder object in which the groups attribute is a dictionary of objectFolder objects with sub lists of files

Notes

If ne of the grouping metadata keys does not exist in one file then no exception is raised - rather the fiiles will be returned into the grou with key None. Metadata keys that are generated from the filename are supported.

hysteresis(mask=None)

Make a hysteresis loop of the average intensity in the given images.

Keyword Argument:
mask(ndarray or list):

boolean array of same size as an image or imarray or list of masks for each image. If True then don’t include that area in the intensity averaging.

hyst(Data):

‘Field’, ‘Intensity’, 2 column array

index(value, start=None, end=None)

Provide an index method like a sequence.

Parameters:

value (str, regexp, or Stoner.Core.metadataObject) – The thing to search for.

Keyword Arguments:

start,end (int) – Limit the index search to a sub-range as per Python 3.5+ list.index

Returns:

(int) – The index of the first matching metadataObject instances.

Notes

If name is a string, then matching is based on either exact matches of the name, or if it includes a * or ? then the basis of a globbing match. name may also be a regular expressiuon, in which case matches are made on the basis of the match with the name of the metadataObject. Finally, if name is a metadataObject, then it matches for an equyality test.

index_to_field(index_map)

Convert an image of index values into an image of field values.

insert(index, value)

Implement the insert method with the option to append as well.

items()

Return the key,value pairs for the subbroups of this folder.

keep_latest()

Filter out earlier revisions of files with the same name.

The CM group LabVIEW software will avoid overwriting files when measuring by inserting !#### where #### is an integer revision number just before the filename extension. This method will look for instances of several files which differ in name only by the presence of the revision number and will kepp only the highest revision number. This is useful if several measurements of the same experiment have been carried out, but only the last file is the correct one.

Returns:

A copy of the DataFolder.

keys()

Return the keys used to access the sub-=groups of this folder.

loadgroup()

Load all files from this group into memory.

make_name(value=None)

Construct a name from the value object if possible.

mask_select()

Run the ImageFile.mask.select() on each image.

mean(_box=False, _metadata='first')

Calculate the mean value of all the images in the stack.

Keyword Arguments:
  • _box (crop box) – Specifies the region of the array to be averaged. Default - entire image

  • _metadata (str) – Specifies how to generate metadata for the averaged image. - “first”: Just ise the first image’s metadata - “common”: Find the common metadata across all images - “none’: no metadata from images.

Actually a synonym for self.average with not weights

montage(*args, **kargs)

Call the plot method for each metadataObject, but switching to a subplot each time.

Parameters:
Keyword Arguments:
  • extra (callable(i,j,d)) – A callable that can carry out additional processing per plot after the plot is done

  • figsize (tuple(x,y)) – Size of the figure to create

  • dpi (float) – dots per inch on the figure

  • edgecolor,facecolor (matplotlib colour) – figure edge and frame colours.

  • frameon (bool) – Turns figure frames on or off

  • FigureClass (class) – Passed to matplotlib figure call.

  • plots_per_page (int) – maximum number of plots per figure.

Returns:

A list of matplotlib.pyplot.Axes instances.

Notes

If the underlying type of the Stoner.Core.metadataObject instances in the PlotFolder lacks a plot method, then the instances are converted to Stoner.Core.Data.

Each plot is generated as sub-plot on a page. The number of rows and columns of subplots is computed from the aspect ratio of the figure and the number of files in the PlotFolder.

on_load_process(tmp)

Carry out processing on a newly loaded file to set means and extra metadata.

pop(name=- 1, default=None)

Return and remove either a subgroup or named object from this folder.

popitem()

Return the most recent subgroup from this folder.

prune(name=None)

Remove any empty groups from the objectFolder (and subgroups).

Returns:

A copy of thte pruned objectFolder.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

save(root=None)

Save the entire data folder out to disc using the groups as a directory tree.

Calls the save method for each file in turn.

Parameters:

root (string) – The root directory to start creating files and subdirectories under. If set to None or not specified, the current folder’s directory attribute will be used.

Returns:

A list of the saved files

select(*args, **kargs)

Select a subset of the objects in the folder based on flexible search criteria on the metadata.

Parameters:

args (various) – A single positional argument if present is interpreted as follows:

  • If a callable function is given, the entire metadataObject is presented to it. If it evaluates True then that metadataObject is selected. This allows arbitrary select operations

  • If a dict is given, then it and the kargs dictionary are merged and used to select the metadataObjects

Keyword Arguments:
  • recurse (bool) – Also recursively slect through the sub groups

  • kargs (varuous) –

    Arbitrary keyword arguments are interpreted as requestion matches against the corresponding metadata values. The keyword argument may have an additional __operator appended to it which is interpreted as follows:

    • eq metadata value equals argument value (this is the default test for scalar argument)

    • ne metadata value doe not equal argument value

    • gt metadata value doe greater than argument value

    • lt metadata value doe less than argument value

    • ge metadata value doe greater than or equal to argument value

    • le metadata value doe less than or equal to argument value

    • contains metadata value contains argument value

    • in metadata value is in the argument value (this is the default test for non-tuple iterable

      arguments)

    • startswith metadata value startswith argument value

    • endswith metadata value endwith argument value

    • icontains,*iin*, istartswith,*iendswith* as above but case insensitive

    • between metadata value lies between the minimum and maximum values of the argument (the default test for 2-length tuple arguments)

    • ibetween,*ilbetween*,*iubetween* as above but include both,lower or upper values

  • rich. (The syntax is inspired by the Django project for selecting, but is not quite as) –

Returns:

(baseFGolder) – A new baseFolder instance that contains just the matching metadataObjects.

Note

If any of the tests is True, then the metadataObject will be selected, so the effect is a logical OR. To achieve a logical AND, you can chain two selects together:

d.select(temp__le=4.2,vti_temp__lt=4.2).select(field_gt=3.0)

will select metadata objects that have either temp or vti_temp metadata values below 4.2 AND field metadata values greater than 3.

There are a few cases where special treatment is needed:

  • If you need to select on a aparameter called recurse, pass a dictionary of {“recurse”:value} as the sole positional argument.

  • If you need to select on a metadata value that ends in an operator word, then append __eq in the keyword name to force the equality test.

  • If the metadata keys to select on are not valid python identifiers, then pass them via the first positional dictionary value.

If the metadata item being checked exists in a regular expression file pattern for the folder, then the files are not loaded and the metadata is evaluated based on the filename. This can speed up operations where a file load is not required.

setdefault(k, d=None)

Return or set a subgroup or named object.

show()

Pass through to Stoner.Image.ImageFolder.view().

slice_metadata(key, output='smart')

Return an array of the metadata values for each item/file in the top level group.

Parameters:

key (str, regexp or list of str) – the meta data key(s) to return

Keyword Parameters:
output (str):

Output format - values are - dict: return an array of dictionaries - list: return a list of lists - array: return a numpy array - Data: return a Stoner.Data object - smart: (default) return either a list if only one key or a list of dictionaries

Returns:

(array of metadata) – If single key is given and is an exact match then returns an array of the matching values. If the key results in a regular expression match, then returns an array of dictionaries of all matching keys. If key is a list ir other iterable, then return a 2D array where each column corresponds to one of the keys.

Todo

Add options to recurse through all groups? Put back RCT’s values only functionality?

sort(key=None, reverse=False, recurse=True)

Sort the files by some key.

Keyword Arguments:
  • key (string, callable or None) – Either a string or a callable function. If a string then this is interpreted as a metadata key, if callable then it is assumed that this is a a function of one parameter x that is a Stoner.Core.metadataObject object and that returns a key value. If key is not specified (default), then a sort is performed on the filename

  • reverse (bool) – Optionally sort in reverse order

  • recurse (bool) – If True (default) sort the sub-groups as well.

Returns:

A copy of the current objectFolder object

stable_mask(tolerance=0.01, comparison=(0, - 1))

Produce a mask of areas of the image that are changing little over the stack.

comparison is an optional tuple that gives the index of two images to compare, otherwise first and last used. tolerance is the difference tolerance

stddev(weights=None, _box=False, _metadata='first')

Calculate weighted standard deviation for stack.

Keyword Arguments:
  • _box (crop box) – Specifies the region of the array to be averaged. Default - entire image

  • _metadata (str) – Specifies how to generate metadata for the averaged image. - “first”: Just ise the first image’s metadata - “common”: Find the common metadata across all images - “none’: no metadata from images.

This is a biased standard deviation, may not be appropriate for small sample sizes

stderr(weights=None, _box=False, _metadata='first')

Calculate standard error in the stack average.

Keyword Arguments:
  • _box (crop box) – Specifies the region of the array to be averaged. Default - entire image

  • _metadata (str) – Specifies how to generate metadata for the averaged image. - “first”: Just ise the first image’s metadata - “common”: Find the common metadata across all images - “none’: no metadata from images.

subtract(background)

Subtract a background image (or index) from all images in the stack.

Parameters:

background (int, str or 2D array) – Background image to index

Returns:

(ImageStack) – The modified image stack.

Notes

Method changed for v0.10 to not normalise or clip the data. The background image is scaled by the ratio of the mean pixel values of the unmasked region in the background image.

switch_index(saturation_end=True, saturation_value=True)

Construct a map of switching points in a hysteresis stack.

Given a stack of boolean masks representing a hystersis loop find the stack index of the saturation field for each pixel.

Take the final mask as all switched (or the first mask if saturation_end is False). Work back through the masks taking the first time a pixel switches as its coercive field (ie the last time it switches before reaching saturation). Elements that start switched at the lowest measured field or never switch are given a zero index.

At the moment it’s set up to expect masks to be false when the sample is saturated at a high field

Keyword Arguments:
  • saturation_end (bool) – True if the last image is closest to the fully saturated state. False if you want the first image

  • saturation_value (bool) – if True then a pixel value True means that switching has occurred (ie magnetic saturation would be all True)

Returns:

switch_ind

MxN ndarray of int

index that each pixel switches at

switch_progession: MxNx(P-1) ndarray of bool

stack of masks showing when each pixel saturates

to_tiff(filename)

Save the ImageArray as a tiff image with metadata.

Parameters:

filename (str) – Filename to save file as.

Note

PIL can save in modes “L” (8bit unsigned int), “I” (32bit signed int), or “F” (32bit signed float). In general max info is preserved for “F” type so if forcetype is not specified then this is the default. For boolean type data mode “L” will suffice and this is chosen in all cases. The type name is added as a string to the metadata before saving.

unflatten()

Take the file list an unflattens them according to the file paths.

Returns:

A copy of the objectFolder

unload(name=None)

Remove the instance from memory without losing the name in the Folder.

Parameters:

name (string,int or None) – Specifies the entry to unload from memory. If set to None all loaded entries are unloaded.

Returns:

(DataFolder) – returns a copy of itself.

update(other)

Update this folder with a dictionary or another folder.

values()

Return the sub-groups of this folder.

walk_groups(walker, **kargs)

Walk through a hierarchy of groups and calls walker for each file.

Parameters:

walker (callable) – A callable object that takes either a metadataObject instance or a objectFolder instance.

Keyword Arguments:
  • group (bool) – (default False) determines whether the walker function will expect to be given the objectFolder representing the lowest level group or individual metadataObject objects from the lowest level group

  • replace_terminal (bool) – If group is True and the walker function returns an instance of metadataObject then the return value is appended to the files and the group is removed from the current objectFolder. This will unwind the group hierarchy by one level.

  • obly_terminal (bool) – Only execute the walker function on groups that have no sub-groups inside them (i.e. are terminal groups)

  • walker_args (dict) – A dictionary of static arguments for the walker function.

Notes

The walker function should have a prototype of the form:

walker(f,list_of_group_names,**walker_args)

where f is either a objectFolder or metadataObject.

zip_groups(groups)

Return a list of tuples of metadataObjects drawn from the specified groups.

Parameters:

groups (list of strings) – A list of keys of groups in the Lpy:class:objectFolder

Returns:

A list of tuples of groups of files – [(grp_1_file_1,grp_2_file_1….grp_n_files_1),(grp_1_file_2, grp_2_file_2….grp_n_file_2)….(grp_1_file_m,grp_2_file_m…grp_n_file_m)]