HDF5_BLS.Wrapper

class HDF5_BLS.Wrapper(filepath=None)

Bases: object

This object is used to store data and attributes in a unified structure.

filepath

The path to the HDF5 file

Type:

str

need_for_repack

A flag to check wether elements were deleted in the file using the “del” method. If so, a repacking of the file is needed to optimize memory usage.

Type:

bool

save

A flag to check wether the file needs to be saved or not. If the file needs to be saved, it means that the user has worked on a temporary file located in the module directory, that will be deleted when the class is closed.

Type:

bool

__init__(filepath=None)

Initializes the wrapper. If no filepath is given, a temporary HDF5 file is created in the temporary directory of the operating system. A parent “Brillouin” group is then created and the attribute “HDF5_BLS_version” is set to the current version of the library. If a filepath is given but the file does not exist, it is created. A parent “Brillouin” group is then created and the attribute “HDF5_BLS_version” is set to the current version of the library. If a filepath is given and the file exists, it is opened and a compatibility check is performed. If the file is not compatible with the current version of the library, a series of changes are applied to make it compatible.

Parameters:

filepath (str, optional) – The filepath of the HDF5 file to load, by default None means that a temporary file is created in the temporary directory of the operating system.

Example

>>> wrp = HDF5_BLS() # Creates a temporary HDF5 file in the temporary directory of the operating system
>>> wrp = HDF5_BLS("path/to/file.h5") # Creates a HDF5 file at the given path or opens an existing one at the given path

Methods

__init__([filepath])	Initializes the wrapper.
add_PSD(data[, parent_group, name, overwrite])	Adds a PSD array to the wrapper by creating a new group.
add_abscissa(data, parent_group[, name, ...])	Adds abscissa as a dataset to the "parent_group" group.
add_attributes(attributes[, parent_group, ...])	Adds attributes to the wrapper.
add_dictionary(dic, parent_group[, ...])	Adds a data dictionary to the wrapper.
add_dictionnary(dic[, parent_group, ...])	Adds a data dictionnary to the wrapper.
add_frequency(data[, parent_group, name, ...])	Adds a frequency array to the wrapper by creating a new group.
add_hdf5(filepath[, parent_group, overwrite])	Adds an HDF5 file to the wrapper by specifying in which group the data have to be stored.
add_other(data[, parent_group, name, overwrite])	Adds an "Other" dataset to the file at the given location.
add_raw_data(data, parent_group[, name, ...])	Adds a raw data array to the wrapper by creating a new group.
add_treated_data(parent_group[, name_group, ...])	Adds the arrays resulting from the treatment of the PSD to the wrapper by creating a new group.
change_brillouin_type(path, brillouin_type)	Changes the brillouin type of an element in the HDF5 file.
change_name(path, name)	Changes the name of an element in the HDF5 file.
clear_empty_attributes(path)	Deletes all the attributes that are empty at the given path.
close([delete_temp_file])	Closes the wrapper and deletes the temporary file if it exists
combine_datasets(datasets, parent_group, name)	Combines a list of elements into a unique dataset.
compatibility_changes()	Applies changes from previous versions of the wrapper to newest versions using the compat module.
copy_dataset(path, copy_path)	This function allows to copy a dataset from the file to a different location while keeping the last location.
create_group(name[, parent_group, ...])	Creates a group in the file under the given parent group with the given name and Brillouin type.
delete_element([path, file])	Deletes an element from the file and sets the need_for_repack flag to True.
export_brim(path_to)	Converts a brimX file to a brim file.
export_dataset(path, filepath[, export_type])	Exports the dataset at the given path as a numpy array.
export_group(path, filepath[, overwrite])	Exports the group at the given path as a HDF5 file.
export_image(path, filepath[, simple_image, ...])	Exports the dataset at the given path as an image.
get_attributes([path])	Returns the attributes associated to a given path.
get_children_elements([path, Brillouin_type])	Returns the children elements of a given path.
get_special_groups_hierarchy([path, ...])	Get all the groups with desired brillouin type that are hierarchically above a given path.
get_structure([filepath])	Returns the structure of an HDF5 file (by default the one stored in the object).
get_type([path, return_Brillouin_type])	Returns the type of the element
import_PSD(filepath[, parent_group, name, ...])	Adds a PSD and frequency array to the HDF5 file from a file.
import_other(filepath[, parent_group, name, ...])	Adds a raw data array to the wrapper from a file.
import_properties_data(filepath[, path, ...])	Imports properties from an excel or CSV file into a dictionary.
import_raw_data(filepath[, parent_group, ...])	Adds a raw data array to the HDF5 file from a file.
move(path, new_path)	Moves an element from one path to another.
move_channel_dimension_to_last(path[, ...])	Moves the channel dimension to the last dimension of the data to comply with the HDF5_BLS convention.
print_metadata([path])	Prints the metadata of a group or dataset in the console taking into account the hierarchy of the file.
print_structure([lvl])	Prints the structure of the file in the console
repack([force_repack])	Repacks the wrapper to minimize its size.
save_as_hdf5([filepath, remove_old_file, ...])	Saves the data and attributes to an HDF5 file.
save_properties_csv(filepath[, path])	Saves the attributes of the data in the HDF5 file to a CSV file.
save_stored_script([path, attribute_name, ...])	Export the script stored in the HDF5 file to a script file.
store_script([path, attribute_name, ...])	Read the full text of a script, store it on this object at the given path and under the given attribute name.
update_property(name, value, path[, ...])	Updates a property of the HDF5 file given a path to the dataset or group, the name of the property and its value.

Attributes

BRILLOUIN_TYPES_DATASETS
BRILLOUIN_TYPES_GROUPS

BRILLOUIN_TYPES_DATASETS = ['Abscissa', 'Amplitude', 'Amplitude_err', 'BLT', 'BLT_err', 'Frequency', 'Linewidth', 'Linewidth_err', 'Other', 'PSD', 'Raw_data', 'Shift', 'Shift_err']

BRILLOUIN_TYPES_GROUPS = ['Calibration_spectrum', 'Impulse_response', 'Measure', 'Root', 'Treatment']

add_PSD(data, parent_group='Brillouin', name=None, overwrite=False)

Adds a PSD array to the wrapper by creating a new group.

Parameters:

• data (np.ndarray) – The PSD array to add to the wrapper.

• parent_group (str, optional) – The parent group where to store the data of the HDF5 file. The format of this group should be “Brillouin/Measure”.

• name (str, optional) – The name of the frequency dataset we want to add, and as it will be displayed in the file by any HDF5 viewer. By default the name is “PSD”.

• overwrite (bool, optional) – A parameter to indicate whether the dataset should be overwritten if a dataset with same name already exist or not, by default False - not overwritten.

Raises:

WrapperError_StructureError – If the parent group does not exist in the HDF5 file.

add_abscissa(data, parent_group, name=None, unit='AU', dim_start=0, dim_end=None, overwrite=False)

Adds abscissa as a dataset to the “parent_group” group.

Parameters:

• data (np.ndarray) – The array corresponding to the abscissa that is to be addedto the wrapper.

• parent_group (str, optional) – The parent group where to store the data of the HDF5 file, by default the parent group is the top group “Data”. The format of this group should be “Brillouin/Measure”.

• name (str, optional) – The name of that is given to the abscissa dataset. If the name is not specified, it is set to “Abscissa_{dim_start}_{dim_end}”

• unit (str, optional) – The unit of the abscissa array, by default AU for Arbitrary Units

• dim_start (int, optional) – The first dimension of the abscissa array, by default 0

• dim_end (int, optional) – The last dimension of the abscissa array, by default the last number of dimension of the array

• overwrite (bool, optional) – A parameter to indicate whether the group should be overwritten if they already exist or not, by default False - attributes are not overwritten.

Raises:

WrapperError_StructureError – If the parent group does not exist in the HDF5 file.

add_attributes(attributes, parent_group='Brillouin', overwrite=False)

Adds attributes to the wrapper.

Parameters:

• attributes (dict) – The attributes to add to the wrapper. The keys of the dictionary should be the name of the attributes, and the values should be the values of the attributes.

• path (str, optional) – The parent group where to store the attributes of the HDF5 file. The format of this group should be “Brillouin/Measure”. By default parent_group is set to “Brillouin”.

• overwrite (bool, optional) – If True, the attributes will be overwritten if they already exist.

add_dictionary(dic, parent_group, create_group=False, brillouin_type_parent_group=None, overwrite=False)

Adds a data dictionary to the wrapper. This is the preferred way to add data using the GUI.

Parameters:

• dic (dict) – The data dictionary to add. The accepted keys for this dictionary are either the one given in the self.BRILLOUIN_TYPES_DATASET list, a key starting with ‘Abscissa’ or ‘Attributes’. All the element of the dictionary are also dictionnaries. Except for attributes, each dictionary has at least two keys: “Name” and “Data”. If an abscissa is to be added, then the keys “Dim_start”, “Dim_end” and “Units” need to be populated. For attributes, each key is the name of the attribute, and the value is the value of the attribute, which will automatically be converted to string if it is not a string.

• parent_group (str, optional) – The path in the file where to store the dataset.

• create_group (bool, optional) – If set to True, the parent group will be created if it does not exist. If False and the group does not exist, an error will be raised. Default is False.

• brillouin_type_parent_group (str, optional) – The type of the data group where the data are stored. This argument must be given if a new group is being created. If this argument is given and overwrite is set to True, then the brillouin type of the parent group will be overwritten. Otherwise, the original brillouin type of the parent group will be used if the group already exists.

• overwrite (bool, optional) – If set to True, any element of the file with a name corresponding to a name given in the dictionary will be overwritten. Similarly any existing argument will be overwritten and Brillouin type will be redefined. Default is False

Raises:

• WrapperError_StructureError – Raises an error if the parent group does not exist in the HDF5 file.

• WrapperError_Overwrite – Raises an error if the group already exists in the parent group.

• WrapperError_ArgumentType – Raises an error if arguments given to the function do not match the expected type.

Example

>>> wrp = HDF5_BLS() # Creates a temporary HDF5 file in the temporary directory of the operating system
>>> dic = {"Raw_data": {"Name": "Raw data", "Data": np.random.random((50, 50, 512))}}
>>> wrp.add_dictionary(dic, parent_group = "Brillouin/Group", create_group = True, brillouin_type_parent_group = "Measure") # Adds the dictionary to the "Brillouin/Group" group (which is here created with Brillouin_type "Measure")
>>> dic = {"PSD": {"Name": "Power Spectral Density", "Data": np.random.random((50, 50, 512))}, "Frequency": {"Name": "Frequency", "Data": np.arange(512)}}
>>> wrp.add_dictionary(dic, parent_group = "Brillouin/Group", create_group = True, brillouin_type_parent_group = "Measure") # Adds the PSD and Frequency arrays to "Brillouin/Group".

add_dictionnary(dic, parent_group=None, name_group=None, brillouin_type='Measure', overwrite=False)

Adds a data dictionnary to the wrapper. This is the preferred way to add data using the GUI.

Parameters:

• dic (dict) – The data dictionnary. Support for the following keys: - “Raw_data”: the raw data - “PSD”: a power spectral density array - “Frequency”: a frequency array associated to the power spectral density - “Abscissa_…”: An abscissa array for the measures where the name is written after the underscore. Each of these keys can either be a numpy array or a dictionnary with two keys: “Name” and “Data”. The “Name” key is the name that will be given to the dataset, while the “Data” key is the data itself. The “Abscissa_…” keys are forced to link to a dictionnary with five keys: “Name”, “Data”, “Unit”, “Dim_start”, “Dim_end”. If the abscissa applies to dimension 1 for example, the “Dim_start” key should be set to 1, and the “Dim_end” to 2.

• parent_group (str, optional) – The path to the parent path, by default None

• name_group (str, optional) – The name of the data group, by default the name is “Data_i”.

• brillouin_type (str, optional) – The type of the data group, by default the type is “Measure”. Other possible types are “Calibration_spectrum”, “Impulse_response”, … Please refer to the documentation of the Brillouin software for more information.

• overwrite (bool, optional) – If set to True, any name in the file corresponding to an element to be added will be overwritten. Default is False

Raises:

• WrapperError_StructureError – Raises an error if the parent group does not exist in the HDF5 file.

• WrapperError_Overwrite – Raises an error if the group already exists in the parent group.

• WrapperError_ArgumentType – Raises an error if arguments given to the function do not match the expected type.

• WrapperError_AttributeError – Raises an error if the keys of the dictionnary do not match the expected keys.

add_frequency(data, parent_group='Brillouin', name=None, overwrite=False)

Adds a frequency array to the wrapper by creating a new group.

Parameters:

• data (np.ndarray) – The frequency array to add to the wrapper.

• parent_group (str, optional) – The parent group where to store the data of the HDF5 file. The format of this group should be “Brillouin/Measure”.

• name (str, optional) – The name of the frequency dataset we want to add, and as it will be displayed in the file by any HDF5 viewer. By default the name is “Frequency”.

• overwrite (bool, optional) – A parameter to indicate whether the dataset should be overwritten if a dataset with same name already exist or not, by default False - not overwritten.

Raises:

WrapperError_StructureError – If the parent group does not exist in the HDF5 file.

add_hdf5(filepath, parent_group='Brillouin', overwrite=False)

Adds an HDF5 file to the wrapper by specifying in which group the data have to be stored. Default is the “Brillouin” group. If the specified group does not exist, it will be created.

Parameters:

• filepath (str) – The filepath of the hdf5 file to add.

• parent_group (str, optional) – The parent group where to store the data of the HDF5 file, by default the parent group is the top group “Brillouin”. The format of this group should be “Brillouin/Group/…”. If the parent group does not exist, it will be created.

• overwrite (bool, optional) – A boolean that indicates whether the data should be overwritten if it already exists, by default False

Raises:

• WrapperError_FileNotFound – Raises an error if the file could not be found.

• WrapperError_StructureError – Raises an error if the parent group does not exist in the HDF5 file.

• WrapperError_Overwrite – Raises an error if the group already exists in the parent group.

• WrapperError – Raises an error if the hdf5 file could not be added to the main HDF5 file.

Example

>>> wrp = HDF5_BLS() # Creates a temporary HDF5 file in the temporary directory of the operating system
>>> wrp.add_hdf5("path/to/file.h5", "Brillouin/Group") # Adds the HDF5 file at the given path to the "Brillouin/Group" group (which is here created)

add_other(data, parent_group='Brillouin', name=None, overwrite=False)

Adds an “Other” dataset to the file at the given location. If the location does not exist, it is created. If the name is not specified, it is set to “Data_i” with i chosen to not overwrite any other dataset. If the name is specified and exists in the file at the given location, the dataset is overwritten if overwrite is set to True, else, a WrapperError_Overwrite is raised.

Parameters:

• data (np.ndarray) – The dataset to add

• parent_group (str, optional) – The path to the group where to add the dataset, by default “Brillouin”

• name (str, optional) – The name of the dataset, by default “Data_i” with i chosen to not overwrite any other dataset

• overwrite (bool, optional) – A flag to overwrite any dataset with the same name, by default False

add_raw_data(data, parent_group, name=None, overwrite=False)

Adds a raw data array to the wrapper by creating a new group.

Parameters:

• data (np.ndarray) – The raw data array to add to the wrapper.

• parent_group (str, optional) – The parent group where to store the data of the HDF5 file. The format of this group should be “Brillouin/Measure”.

• name (str, optional) – The name of the frequency dataset we want to add, and as it will be displayed in the file by any HDF5 viewer. By default the name is “Raw data”.

• overwrite (bool, optional) – A parameter to indicate whether the dataset should be overwritten if a dataset with same name already exist or not, by default False - not overwritten.

Raises:

WrapperError_StructureError – If the parent group does not exist in the HDF5 file.

add_treated_data(parent_group, name_group=None, overwrite=False, **kwargs)

Adds the arrays resulting from the treatment of the PSD to the wrapper by creating a new group.

Parameters:

• parent_group (str, optional) – The parent group where to store the data of the HDF5 file. The format of this group should be “Brillouin/Measure”.

• name_group (str, optional) – The name of the group that will be created to store the treated data. By default the name is “Treat_i” with i the number of the treatment so that the name is unique.

• overwrite (bool, optional) – A parameter to indicate whether the dataset should be overwritten if a dataset with same name already exist or not, by default False - not overwritten.

• shift (np.ndarray, optional) – The shift array to add to the wrapper.

• linewidth (np.ndarray, optional) – The linewidth array to add to the wrapper.

• amplitude (np.ndarray, optional) – The amplitude array to add to the wrapper.

• blt (np.ndarray, optional) – The Loss Tangent array to add to the wrapper.

• shift_err (np.ndarray, optional) – The shift error array to add to the wrapper.

• linewidth_err (np.ndarray, optional) – The linewidth error array to add to the wrapper.

• amplitude_err (np.ndarray, optional) – The amplitude error array to add to the wrapper.

• blt_std (np.ndarray, optional) – The Loss Tangent error array to add to the wrapper.

• treat (HDF5_BLS_Treat.Treat) – The treatment object to add to the wrapper. If given, all other keyword arguments are ignored.

Raises:

WrapperError_StructureError – If the parent group does not exist in the HDF5 file.

change_brillouin_type(path, brillouin_type)

Changes the brillouin type of an element in the HDF5 file.

Parameters:

• path (str) – The path to the element to change the brillouin type of.

• brillouin_type (str) – The new brillouin type of the element.

Raises:

• WrapperError_StructureError – If the path is not a valid path.

• WrapperError_ArgumentType – If the type is not valid

change_name(path, name)

Changes the name of an element in the HDF5 file.

Parameters:

• path (str) – The path to the element to change the name of.

• name (str) – The new name of the element.

Raises:

WrapperError_StructureError – If the path does not lead to an element.

clear_empty_attributes(path)

Deletes all the attributes that are empty at the given path.

Parameters:

path (str) – The path to the element to delete the attributes from.

close(delete_temp_file=False)

Closes the wrapper and deletes the temporary file if it exists

Parameters:

delete_temp_file (bool, optional) – If True, the temporary file is deleted, by default False

combine_datasets(datasets, parent_group, name, overwrite=False)

Combines a list of elements into a unique dataset. All the datasets must have the same shape. They are added into a new dataset where the first dimension is the number of datasets, under the group “parent_group”. If the dataset already exists and overwrite is set to True, it is overwritten.

Parameters:

• datasets (list of str) – The list of paths in the file to the datasets to combine

• name (str) – The name of the new dataset

• overwrite (bool, optional) – If a dataset with the same name already exists, overwrite it, by default False

compatibility_changes()

Applies changes from previous versions of the wrapper to newest versions using the compat module.

copy_dataset(path, copy_path)

This function allows to copy a dataset from the file to a different location while keeping the last location.

Parameters:

• path (str) – The path to the dataset to copy.

• copy_path (str) – The path to the group where the dataset is to be copied to.

Return type:

None

create_group(name, parent_group=None, brillouin_type='Root', overwrite=False)

Creates a group in the file under the given parent group with the given name and Brillouin type. If overwrite is set to True, if a group with the same name exists in the selected parent group, the previous element is removed.

Parameters:

• name (str) – The name of the group to create

• parent_group (str, optional) – The parent group where to create the group, by default the parent group is the top group “Data”. The format of this group should be “Brillouin/Data”

• brillouin_type (str, optional) – The type of the group, by default “Root”. Can be “Root”, “Measure”, “Calibration_spectrum”, “Impulse_response”, “Treatment”, “Metadata”

• overwrite (bool, optional) – If set to True, any name in the file corresponding to an element to be added will be overwritten. Default is False

Raises:

WrapperError – If the group already exists

delete_element(path=None, file=None)

Deletes an element from the file and sets the need_for_repack flag to True.

Parameters:

• path (str) – The path to the element to delete

• file (h5py.File) – The file to delete the element from. By default this object is created in the function

Raises:

WrapperError – Raises an error if the path does not lead to an element.

export_brim(path_to: str)

Converts a brimX file to a brim file.

Parameters:

path_to (str) – The filepath to the exported Brim file.

export_dataset(path, filepath, export_type='.npy')

Exports the dataset at the given path as a numpy array.

Parameters:

• path (str) – The path to the dataset to export. Warning: only datasets of 2 or less dimensions can be exported to either .csv or .xlsx formats.

• filepath (str) – The path to the numpy array to export to.

• export_type (str) – The type of export to perform (currently supported: “.npy”, “.csv”, “.xlsx).

Return type:

None

export_group(path, filepath, overwrite=False)

Exports the group at the given path as a HDF5 file.

Parameters:

• path (str) – The path to the group to export.

• filepath (str) – The path to the HDF5 file to export to.

• overwrite (bool) – A boolean to specify if the file we export to needs to be rewritten if it already exists.

Return type:

None

export_image(path, filepath, simple_image=True, image_size=None, cmap='viridis', colorbar=False, colorbar_label=None, axis=False, xlabel=None, ylabel=None)

Exports the dataset at the given path as an image.

Parameters:

• path (str) – The path to the dataset to export.

• filepath (str) – The path to the image to export to.

• simple_image (bool, optional) – If set to True, the image is exported as a simple image with grayscale colormap. If false, the image is exported with the given colormap and options.

• image_size (tuple, optional) – The size of the image to export. If None, the size is set to the default figure size.

• cmap (str, optional) – The colormap to use for the image. Default is ‘viridis’. All the available colormaps can be found here: https://matplotlib.org/stable/tutorials/colors/colormaps.html

• colorbar (bool, optional) – If set to True, a colorbar is added to the image.

• axis (boolean, optional) – If set to True, the image is displayed with an extent given by the “MEASURE.Field_Of_View_(X,Y,Z)_(um)” attribute. If set to False, the image is displayed without any extent.

Return type:

None

get_attributes(path=None)

Returns the attributes associated to a given path. The attributes are retireved hierarchically, meaning that the attributes of all the groups above the given path are also retrieved, and their value is only changed if they are redefined at a lower level.

Parameters:

path (str, optional) – The path to the data, by default None which means the attributes are read from the root of the file (the Brillouin group).

Returns:

attr – The attributes of the data

Return type:

dict

get_children_elements(path=None, Brillouin_type=None)

Returns the children elements of a given path. If Brillouin_type is specified, only the children elements with the given Brillouin_type are returned.

Parameters:

• path (str, optional) – The path to the element, by default None which means the root of the file (“Brillouin” group)

• Brillouin_type (str, optional) – The type of the element, by default None which means all the elements are returned

Returns:

The list of children elements

Return type:

list

get_special_groups_hierarchy(path=None, brillouin_type=None)

Get all the groups with desired brillouin type that are hierarchically above a given path.

Parameters:

• path (str, optional) – The path to the group, by default None which means the root group is used.

• brillouin_type (str, optional) – The type of the group, by default None which means “Root” is used

Returns:

The list of all the groups with desired brillouin type that are hierarchically above a given path.

Return type:

list

get_structure(filepath=None)

Returns the structure of an HDF5 file (by default the one stored in the object).

Parameters:

filepath (str, optional) – The filepath to the HDF5 file, by default None which means the filepath stored in the object is the one observed.

Returns:

The structure of the file with the types of each element in the “Brillouin_type” key.

Return type:

dict

Raises:

WrapperError_StructureError – Raises an error if one of the elements has no

get_type(path=None, return_Brillouin_type=False)

Returns the type of the element

Parameters:

path (str, optional) – The path to the element, by default None which means the root of the file (“Brillouin” group)

Returns:

The type of the element

Return type:

str

import_PSD(filepath, parent_group='Brillouin', name=None, creator=None, parameters=None, reshape=None, overwrite=False)

Adds a PSD and frequency array to the HDF5 file from a file.

Parameters:

• filepath (str) – The filepath to the raw data file to import.

• parent_group (str, optional) – The parent group where to store the data of the HDF5 file. The format of this group should be “Brillouin/Measure”.

• name (str, optional) – The name of the dataset, by default None.

• creator (str, optional) – The structure of the file that has to be loaded. If None, a LoadError can be raised.

• parameters (dict, optional) – The parameters that are to be used to import the data correctly. If None, a LoadError can be raised.

• reshape (tuple, optional) – The new shape of the array, by default None means that the shape is not changed

• overwrite (bool, optional) – A parameter to indicate whether the dataset should be overwritten if a dataset with same name already exist or not, by default False - not overwritten.

import_other(filepath, parent_group='Brillouin', name=None, creator=None, parameters=None, reshape=None, overwrite=False)

Adds a raw data array to the wrapper from a file.

Parameters:

• filepath (str) – The filepath to the raw data file to import.

• parent_group (str, optional) – The parent group where to store the data of the HDF5 file. The format of this group should be “Brillouin/Measure”.

• name (str, optional) – The name of the dataset, by default None.

• creator (str, optional) – The structure of the file that has to be loaded. If None, a LoadError can be raised.

• parameters (dict, optional) – The parameters that are to be used to import the data correctly. If None, a LoadError can be raised.

• reshape (tuple, optional) – The new shape of the array, by default None means that the shape is not changed

• overwrite (bool, optional) – A parameter to indicate whether the dataset should be overwritten if a dataset with same name already exist or not, by default False - not overwritten.

import_properties_data(filepath, path=None, overwrite=False, delete_child_attributes=False)

Imports properties from an excel or CSV file into a dictionary.

Parameters:

• filepath (str) – The filepath to the csv storing the properties of the measure. This csv is based on the spreadsheet found in the “spreadsheet” folder of the repository.

• path (str) – The path to the data in the HDF5 file.

• overwrite (bool, optional) – A boolean that indicates whether the attributes should be overwritten if they already exist, by default False.

• delete_child_attributes (bool, optional) – If True, all the attributes of the children elements with same name as the ones to be updated are deleted. Default is False.

import_raw_data(filepath, parent_group='Brillouin', name=None, creator=None, parameters=None, reshape=None, overwrite=False)

Adds a raw data array to the HDF5 file from a file.

Parameters:

• filepath (str) – The filepath to the raw data file to import.

• parent_group (str, optional) – The parent group where to store the data of the HDF5 file. The format of this group should be “Brillouin/Measure”.

• name (str, optional) – The name of the dataset, by default None.

• creator (str, optional) – The structure of the file that has to be loaded. If None, a LoadError can be raised.

• parameters (dict, optional) – The parameters that are to be used to import the data correctly. If None, a LoadError can be raised.

• reshape (tuple, optional) – The new shape of the array, by default None means that the shape is not changed

• overwrite (bool, optional) – A parameter to indicate whether the dataset should be overwritten if a dataset with same name already exist or not, by default False - not overwritten.

move(path, new_path)

Moves an element from one path to another. If the new group does not exist, it is created.

Parameters:

• path (str) – The path to the element to move.

• new_path (str) – The new path to move the element to.

Raises:

WrapperError_StructureError – If the path does not lead to an element.

move_channel_dimension_to_last(path, channel_dimension=None)

Moves the channel dimension to the last dimension of the data to comply with the HDF5_BLS convention.

Parameters:

• path (str) – The path to the dataset to move the channel dimension to the last dimension.

• channel_dimension (int, optional) – The dimension of the channel. Default is None, which means the channel dimension is the last dimension.

print_metadata(path=None)

Prints the metadata of a group or dataset in the console taking into account the hierarchy of the file.

Parameters:

lvl (int, optional) – The level of indentation, by default 0.

print_structure(lvl=0)

Prints the structure of the file in the console

Parameters:

lvl (int, optional) – The level of indentation, by default 0.

repack(force_repack=False)

Repacks the wrapper to minimize its size.

Parameters:

force_repack (bool) – Flag to force the repacking of the HDF5 file even if not necessary

save_as_hdf5(filepath=None, remove_old_file=True, overwrite=False)

Saves the data and attributes to an HDF5 file. In practice, moves the temporary hdf5 file to a new location and removes the old file if specified.

Parameters:

filepath (str, optional) – The filepath where to save the hdf5 file. Default is None, which means the file is saved in the same location as the current file.

Raises:

• WrapperError_Overwrite – If the file already exists.

• WrapperError – Raises an error if the file could not be saved

save_properties_csv(filepath, path=None)

Saves the attributes of the data in the HDF5 file to a CSV file.

Parameters:

• filepath (str) – The filepath to the csv storing the properties of the measure.

• path (str, optional) – The path to the data in the HDF5 file, by default None leads to the top group “Brillouin”

save_stored_script(path: str = None, attribute_name: str = None, save_filepath: str = None)

Export the script stored in the HDF5 file to a script file.

Parameters:

• path (str, optional) – The path to the script in the HDF5 file, if None is given, return.

• name_attribute (str, optional) – The name of the attribute containing the script, if None is given, return.

• save_filepath (str, optional) – The filepath to save the script to, if None is given, return.

Raises:

WrapperError_StructureError – Raises an error if the path does not exist in the file. Raises an error if the name of the attribute is not correct.

store_script(path: str = None, attribute_name: str = None, script_filepath: str = None)

Read the full text of a script, store it on this object at the given path and under the given attribute name.

Parameters:

• path (str, optional) – Path inside the HDF5 file to store the script. If None, the root of the file is used.

• attribute_name (str, optional) – Name of the attribute to store the script under. If None, the script is stored under the “Script” attribute.

• script_filepath (str, optional) – Path to the script file to store. If None, the caller’s filename is inferred.

Raises:

• RuntimeError – If the caller filename can’t be inferred (interactive shells / notebooks) and no path given.

• FileNotFoundError / UnicodeDecodeError – If the script file can’t be read.

update_property(name, value, path, apply_to_all=None)

Updates a property of the HDF5 file given a path to the dataset or group, the name of the property and its value.

Parameters:

• name (str) – The name of the property to update.

• value (str) – The value of the property to update.

• path (str) – The path of the property to update. Defaults to None sets the property at the root level.