qudi.util.datastorage.TextDataStorage

class qudi.util.datastorage.TextDataStorage(*, root_dir, comments='# ', delimiter='\t', file_extension='.dat', column_formats=None, **kwargs)

Bases: qudi.util.datastorage.DataStorageBase

Helper class to store (measurement)data on disk as text file. Data will always be saved in a tabular format with column headers. Single/Multiple rows are appendable.

__init__(*, root_dir, comments='# ', delimiter='\t', file_extension='.dat', column_formats=None, **kwargs)

Initialize storage configuration for saving files.

Parameters:

root_dirstr, optional

Root directory for this storage instance to save files into.

commentsstr, optional

String to put at the beginning of comment and header lines.

delimiterstr, optional

Column delimiter used in text files.

file_extensionstr, optional

File extension to use for text files.

column_formatsstr or sequence, optional

Value format specifier (mini-language) for each column. If a single string is provided, it will be used for all columns.

column_headersstr or sequence, optional

Sequence of strings containing column headers. If a single string is given, write it to the file header without formatting.

column_dtypestype or str or sequence, optional

The column data types to expect.

**kwargs

Additional keyword arguments for further customization.

Notes

For additional keyword arguments, see the documentation for __init__.

Methods

__init__(*, root_dir[, comments, delimiter, ...])	Initialize storage configuration for saving files.
add_global_metadata(name[, value, overwrite])	Set a single global metadata key-value pair or alternatively multiple ones as dict.
append_file(data, file_path)	Append single or multiple rows to an existing data file.
create_header([timestamp, metadata, notes, ...])
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(file_path)	See load_data() for more information.
new_file(*[, timestamp, metadata, notes, ...])	Create a new data file on disk and write header string to it.
remove_global_metadata(names)	Remove a global metadata key-value pair by key.
save_data(data, *[, timestamp, metadata, ...])	See save_data() for more information.
save_thumbnail(mpl_figure, file_path)	Save a matplotlib figure visualizing the saved data in the configured image format.

Attributes

delimiter
file_extension

__init__(*, root_dir, comments='# ', delimiter='\t', file_extension='.dat', column_formats=None, **kwargs)

Initialize storage configuration for saving files.

Parameters:

root_dirstr, optional

Root directory for this storage instance to save files into.

commentsstr, optional

String to put at the beginning of comment and header lines.

delimiterstr, optional

Column delimiter used in text files.

file_extensionstr, optional

File extension to use for text files.

column_formatsstr or sequence, optional

Value format specifier (mini-language) for each column. If a single string is provided, it will be used for all columns.

column_headersstr or sequence, optional

Sequence of strings containing column headers. If a single string is given, write it to the file header without formatting.

column_dtypestype or str or sequence, optional

The column data types to expect.

**kwargs

Additional keyword arguments for further customization.

Notes

For additional keyword arguments, see the documentation for __init__.

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”.

append_file(data, file_path)

Append single or multiple rows to an existing data file.

Parameters:

datanumpy.ndarray

Data array to be appended. For 1D arrays, it represents a single row. For 2D arrays, it represents multiple rows.

file_pathstr

File path to append to.

Returns:

tuple

Number of rows written (int). Number of columns written (int).

create_header(timestamp=None, metadata=None, notes=None, column_headers=None, column_dtypes=None)

property delimiter

!! processed by numpydoc !!

property file_extension

!! processed by numpydoc !!

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.

static load_data(file_path)

See load_data() for more information.

Parameters:

file_pathstr, optional

Path to the file to load data from.

new_file(*, timestamp=None, metadata=None, notes=None, nametag=None, column_headers=None, column_dtypes=None, filename=None)

Create a new data file on disk and write header string to it. Will overwrite old files silently if they have the same path.

Parameters:

metadatadict, optional

Named metadata values to be saved in the data header.

notesstr, optional

String that is included in the file header “as-is”.

nametagstr, optional

Nametag to include in the generic filename.

timestampdatetime.datetime, optional

Timestamp to use. Will create one if missing.

filenamestr, optional

Custom filename to use (nametag, timestamp, and configured file_extension will not be included for file naming).

Returns:

tuple

Full file path (str), timestamp used (datetime.datetime).

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.

save_data(data, *, timestamp=None, metadata=None, notes=None, nametag=None, column_headers=None, column_dtypes=None, filename=None)

See save_data() for more information.

Parameters:

column_headersstr or list, optional

Data column header strings or a single string.

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.