qudi.util.datastorage.DataStorageBase

class qudi.util.datastorage.DataStorageBase(*, root_dir=None, include_global_metadata=True, image_format=ImageFormat.PNG)

Bases: builtins.object

Base helper class to store/load (measurement)data to/from disk. Subclasses handle saving and loading of measurement data (including metadata) for specific file formats. Metadata is represented as dictionary (key-value pairs). It is also possible to set so called “global metadata” using this or any subclass of this class. Global metadata is shared and accessible throughout all instances of these storage objects within the Python process.

If the storage type is file based and root_dir is not initialized, each call to save_data must provide the full save path information and not just a file name or name tag.

__init__(*, root_dir=None, include_global_metadata=True, image_format=ImageFormat.PNG)

Parameters:

root_dirstr, optional

Root directory for this storage instance to work in.

include_global_metadatabool, optional

Flag indicating whether to save global metadata.

image_formatImageFormat, optional

Image file format Enum for saving thumbnails.

Methods

__init__(*[, root_dir, ...])	Parameters:
add_global_metadata(name[, value, overwrite])	Set a single global metadata key-value pair or alternatively multiple ones as dict.
get_global_metadata()	Return a copy of the global metadata dict.
get_unified_metadata([local_metadata])	Helper method to return a dictionary containing provided local metadata as well as global metadata depending on the include_global_metadata flag.
load_data(*args, **kwargs)	This method must be implemented in a subclass.
remove_global_metadata(names)	Remove a global metadata key-value pair by key.
save_data(data, *[, metadata, notes, ...])	This method must be implemented in a subclass.
save_thumbnail(mpl_figure, file_path)	Save a matplotlib figure visualizing the saved data in the configured image format.

__init__(*, root_dir=None, include_global_metadata=True, image_format=ImageFormat.PNG)

Parameters:

root_dirstr, optional

Root directory for this storage instance to work in.

include_global_metadatabool, optional

Flag indicating whether to save global metadata.

image_formatImageFormat, optional

Image file format Enum for saving thumbnails.

classmethod add_global_metadata(name, value=None, *, overwrite=False)

Set a single global metadata key-value pair or alternatively multiple ones as dict. Metadata added this way will persist for all data storage instances in this process until being selectively removed by calls to “remove_global_metadata”.

classmethod get_global_metadata()

Return a copy of the global metadata dict.

get_unified_metadata(local_metadata=None)

Helper method to return a dictionary containing provided local metadata as well as global metadata depending on the include_global_metadata flag.

Parameters:

local_metadatadict

Metadata to include in addition to global metadata.

include_global_metadatabool, optional

Flag indicating whether to include global metadata.

Returns:

dict

New dictionary containing local metadata and global metadata.

abstract load_data(*args, **kwargs)

This method must be implemented in a subclass. It should provide the facility to load a saved data set including the metadata/experiment parameters and column headers (if possible). Many storage classes can even implement this method as a static method.

For file-based storage objects, the only parameter should be file_path.

Parameters:

file_pathstr

Path to the file to be loaded.

Returns:

np.ndarray

Data as a numpy array.

dict

User metadata.

dict

General header data.

classmethod remove_global_metadata(names)

Remove a global metadata key-value pair by key. Does not raise an error if the key is not found.

abstract save_data(data, *, metadata=None, notes=None, nametag=None, timestamp=None, **kwargs)

This method must be implemented in a subclass. It should provide the facility to save an entire measurement as a whole along with experiment metadata (to include e.g. in the file header). The user can either specify an explicit filename or a generic one will be created. If optional nametag and/or timestamp is provided, this will be used to create the generic filename (only if the filename parameter is omitted).

Parameters:

datanumpy.ndarray

Data array to be saved (must be 1D or 2D for text files).

notesstr, optional

String that is included in the metadata “as-is” without a key.

metadatadict, optional

Named metadata to be saved in the data header / metadata.

nametagstr, optional

Nametag to include in the generic filename.

timestampdatetime.datetime, optional

Timestamp to construct a generic filename from.

filenamestr, optional

Explicit filename to use for saving the data.

Returns:

tuple

Full file path (str), timestamp used (datetime.datetime), saved data shape (tuple).

save_thumbnail(mpl_figure, file_path)

Save a matplotlib figure visualizing the saved data in the configured image format. It is recommended to use the same file path as the corresponding data file (if applicable) and exclude the file extension (which will be added according to the image format).

Parameters:

mpl_figurematplotlib.figure.Figure

The matplotlib figure object to save as an image.

file_pathstr

Full file path to use without the file extension.

Returns:

str

Full absolute path of the saved image.