PYME.IO.MetaDataHandler module¶
Defines metadata handlers for the saving of acquisiton metadata to a variety of file formats, as well as keeping track of metadata sources.
Metadata sources¶
Metadata sources are simply functions, which when called, write information into a provided handler. e.g.:
def metadataGenerator(mdhandler):
mdhandler['a.key'] = value
These generator functions are registered by adding them to one of two lists exposed by this module: provideStartMetadata or provideStopMetadata. depending on whether it makes more sense to record the metadata at the start or stop of an acquisition.
A good example can be found in PYME.Acquire.Hardware.Camera.AndorIXon.AndorIXon.
MetaData Handlers¶
- NestedClassMDHandler
An in-memory metadatahandler used to buffer metadata or to store values prior to the file format being known.
- HDFMDHandler
For local pytables/hdf5 datasets
- QueueMDHandler
For use with data hosted in a taskqueue
- XMLMDHandler
For use with PYMEs XML metadata format - typically used with .tiff files or other data for which it is difficult to embed metadata.
- SimpleMDHandler
Saves and reads metadata as a python script (a series of md[key]=value statements). Used where you might want to construct or modify metadata by hand - e.g. with foreign source data.
The format of a metadata handler is defined by the MDHandlerBase class.
- class PYME.IO.MetaDataHandler.CachingMDHandler(mdToCache)¶
Bases:
MDHandlerBase- getEntry(entryName)¶
Returns the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- Returns
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- getEntryNames()¶
Returns a list of defined entries.
- Returns
- nameslist of string
The keys which are defined in the metadata.
- classmethod recreate(cache)¶
- setEntry(entryName, value)¶
Sets the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- class PYME.IO.MetaDataHandler.CopyOnWriteMDHandler(orig_md)¶
Bases:
MDHandlerBase- getEntry(entryName)¶
Returns the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- Returns
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- getEntryNames()¶
Returns a list of defined entries.
- Returns
- nameslist of string
The keys which are defined in the metadata.
- setEntry(entryName, value)¶
Sets the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- class PYME.IO.MetaDataHandler.DictMDHandler(mdToCopy=None, writable=True)¶
Bases:
MDHandlerBaseSimple implementation using a dict.
Should eventually replace most instances of NestedClassMDHandler
Adds a writable flag to enable read-only metadata (currently unused, but gives us the option of enforcing good behaviour in, e.g., recipe modules, in the future). TODO - propagate writable flag up to base?
- getEntry(entryName)¶
Returns the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- Returns
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- getEntryNames()¶
Returns a list of defined entries.
- Returns
- nameslist of string
The keys which are defined in the metadata.
- setEntry(entryName, value)¶
Sets the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- set_readonly()¶
- class PYME.IO.MetaDataHandler.HDFMDHandler(h5file, mdToCopy=None)¶
Bases:
MDHandlerBase- getEntry(entryName)¶
Returns the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- Returns
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- getEntryNames()¶
Returns a list of defined entries.
- Returns
- nameslist of string
The keys which are defined in the metadata.
- setEntry(entryName, value)¶
Sets the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- class PYME.IO.MetaDataHandler.MDHandlerBase¶
Bases:
MutableMappingBase class from which all metadata handlers are derived.
Metadata attributes can be read and set using either a dictionary like interface, or by calling the getEntry and setEntry methods.
Note
Derived classes MUST override getEntry, setEntry, and getEntryNames.
- GetSimpleString()¶
Writes out metadata in simplfied format.
- Returns
- mdstringstring
The metadata in a simple, human readable format.
See also
- WriteSimple(filename)¶
Dumps metadata to file in simplfied format.
- Parameters
- filenamestring
The the filename to write to. Should end in .md.
See also
- copyEntriesFrom(mdToCopy)¶
Copies entries from another metadata object into this one. Duplicate keys will be overwritten.
- Parameters
- mdToCopyan instance of a metadata handler
The metadata handler from which to copy entries.
- getEntry(name)¶
Returns the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- Returns
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- getEntryNames()¶
Returns a list of defined entries.
- Returns
- nameslist of string
The keys which are defined in the metadata.
- getOrDefault(name, default)¶
Returns the entry for a given name, of a default value if the key is not present.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- defaultobject
What to return if the name is not defined
- Returns
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- keys()¶
Alias for getEntryNames to make us look like a dictionary
- mergeEntriesFrom(mdToCopy)¶
Copies entries from another metadata object into this one. Values are only copied if they are not already defined locally.
- Parameters
- mdToCopyan instance of a metadata handler
The metadata handler from which to copy entries.
- record_pyme_version()¶
Write version info to metadata
- setEntry(name, value)¶
Sets the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- static tformat(timeval)¶
- to_JSON()¶
- property voxelsize_nm¶
- class PYME.IO.MetaDataHandler.NestedClassMDHandler(mdToCopy=None)¶
Bases:
MDHandlerBase- getEntry(entryName)¶
Returns the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- Returns
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- getEntryNames()¶
Returns a list of defined entries.
- Returns
- nameslist of string
The keys which are defined in the metadata.
- setEntry(entryName, value)¶
Sets the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- class PYME.IO.MetaDataHandler.OMEXMLMDHandler(XMLData=None, mdToCopy=None)¶
Bases:
XMLMDHandler- getXML(data=None)¶
- writeXML(filename)¶
- class PYME.IO.MetaDataHandler.QueueMDHandler(tq, queueName, mdToCopy=None)¶
Bases:
MDHandlerBase- copyEntriesFrom(mdToCopy)¶
Copies entries from another metadata object into this one. Duplicate keys will be overwritten.
- Parameters
- mdToCopyan instance of a metadata handler
The metadata handler from which to copy entries.
- getEntry(entryName)¶
Returns the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- Returns
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- getEntryNames()¶
Returns a list of defined entries.
- Returns
- nameslist of string
The keys which are defined in the metadata.
- setEntry(entryName, value)¶
Sets the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- class PYME.IO.MetaDataHandler.SimpleMDHandler(filename=None, mdToCopy=None)¶
Bases:
NestedClassMDHandlersimple metadata format - consists of a python script with a .md extension which adds entrys using the dictionary syntax to a metadata handler called md
- write(filename)¶
- class PYME.IO.MetaDataHandler.VoxelSize(x, y, z)¶
Bases:
tupleCreate new instance of VoxelSize(x, y, z)
- units = 'nm'¶
- property x¶
Alias for field number 0
- property y¶
Alias for field number 1
- property z¶
Alias for field number 2
- class PYME.IO.MetaDataHandler.XMLMDHandler(filename=None, mdToCopy=None)¶
Bases:
MDHandlerBase- getEntry(entryName)¶
Returns the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- Returns
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- getEntryNames()¶
Returns a list of defined entries.
- Returns
- nameslist of string
The keys which are defined in the metadata.
- setEntry(entryName, value)¶
Sets the entry for a given name.
- Parameters
- namestring
The entry name. This name should be heirachical, and deliminated with dots e.g. ‘Camera.EMCCDGain’
- valueobject
The value stored for the given key. This can, in principle, be anything that can be pickled. strings, ints, bools and floats are all stored in a human readable form in the textual metadata representations, wheras more complex objects are base64 encoded.
- writeXML(filename)¶
- PYME.IO.MetaDataHandler.from_json(json_string)¶
- PYME.IO.MetaDataHandler.get_camera_physical_roi_origin(mdh)¶
Get the camera roi offset to use for positioning. For a standard camera this is the same as the ROI pixel origin, but for cameras with an image splitting device this may not be the case. For these cameras, return a position relative to the left-most ROI.
TODO: This currently works for the HTSMS multiview setup, expand to also work with the dual-view splitters used on other setups.
- Parameters
- mdh
- Returns
- PYME.IO.MetaDataHandler.get_camera_roi_origin(mdh)¶
helper function to allow us to transition to 0 based ROIs.
Returns the first of these it finds: - [Camera.ROIOriginX, Camera.ROIOriginY] - [Camera.ROIPosX -1, Camera.ROIPosY-1] - [0,0]
NOTE: this is not yet widely supported in calling code (ie you should still write ROIPosX, ROIPosY, although it is safe to write both the old and new versions.
- Parameters
- mdhmetadata handler
- Returns
- ROIOriginX, ROIOriginY
- PYME.IO.MetaDataHandler.get_voxelsize_nm(mdh)¶
Helper function to obtain the voxel size, in nm, from the metadata (to replace the many 1e3*mdh[‘voxelsize.x’] calls)
NOTE: supplies a default z voxelsize of 0 if none in metadata.
- Parameters
- mdh
- Returns
- PYME.IO.MetaDataHandler.instanceinlist(cls, list)¶
- PYME.IO.MetaDataHandler.load_json(filename)¶
- PYME.IO.MetaDataHandler.localisation_origin_nm(mdh)¶
Get the origin of localisation data.
Effectively a shortcut for origin_nm(), but discarding the z-component as whilst x and y co-ordinates in localisation data are referenced to the ROI, the z component is absolute.
- PYME.IO.MetaDataHandler.origin_nm(mdh, default_pixel_size=1.0)¶
origin, in nm of the image ROI from the camera upper left hand pixel - used for overlaying with different ROIs.
- Parameters
- mdhPYME.IO.MetaDataHandler
- default_pixel_sizefloat, optional
Safe to ignore. Parameter only exists for a niche case in ImageStack, when no pixel size is defined. Should probably change to emit a warning if we actually use this fallback.
- Returns
- tuple
x, y, z origin in nanometers
Notes
Use with localisation / point data: When used with localization data, origin_nm() returns the origin of the pixel data in the raw image series used to derive the localisations. Whilst x and y localisations are referenced to the ROI (and hence share an origin with the pixel data) z localisations are absolute (technically referenced to the 0 position of the z-piezo). As a result, the z-component of origin_nm() should be ignored when used with localisation data, which does not require z origin correction.
transferred from image.ImageStack.origin so that it can be used for tabular data too.