cohesivm.database

This module contains the classes and utility functions for the data management.

class Dimensions[source]

Bases: object

Contains classes and methods to represent the dimensions of a physical object. The inner classes follow the Shape abstract base class.

classmethod parameters_from_string(dimensions_string: str) → Tuple[str, dict][source]

Parses a parameter tuple from the string representation. Can be used to create a Shape object or a matplotlib.patches.Patch object.

Parameters:: dimensions_string – String representation of a Shape object.
Returns:: A tuple of the name of the Shape class and the keyword arguments.

classmethod object_from_parameters(parameters: Tuple[str, dict]) → Shape[source]

Parses a Shape object from a parameters tuple which can be obtained from the parameters_from_string() method.

Parameters:: parameters – A tuple of the name of the Shape class and the keyword arguments.
Returns:: The parsed Shape object.

classmethod object_from_string(dimensions_string: str) → Shape[source]

Parses a Shape object from its string representation.

Parameters:: dimensions_string – String representation of a Shape object.
Returns:: The parsed Shape object.

class Shape[source]

Bases: ABC

Abstract base class. Stores the attributes which describe the dimensions. Implements a string representation and an equality comparison.

abstract area() → float[source]: Returns the area of the shape.

class Point[source]

Bases: Shape

A dimensionless point.

area() → float[source]: Returns the area of the shape.

class Line(length: float, unit: str = 'mm')[source]

Bases: Shape

A line defined by its length.

Parameters:

length – Length of the line.
unit – Scale unit of the length.

area() → float[source]: Returns the area of the shape.

class Rectangle(width: float, height: float | None = None, unit: str = 'mm')[source]

Bases: Shape

A rectangular shape defined by its width and height. The origin is in the bottom left corner.

Parameters:

width – Length of the rectangle in the x-direction.
height – Length of the rectangle in the y-direction. Can be omitted to define a square.
unit – Scale unit of the width and height.

property width: float: Length of the rectangle in the x-direction.

property height: float: Length of the rectangle in the y-direction.

property unit: str: Scale unit of the width and height.

area() → float[source]: Returns the area of the shape.

class Circle(radius: float, unit: str = 'mm')[source]

Bases: Shape

A circular shape defined by its radius. The origin is in the center.

Parameters:

radius – Length of the circle radius.
unit – Scale unit of the radius.

property radius: float: Length of the circle radius.

property unit: str: Scale unit of the radius.

area() → float[source]: Returns the area of the shape.

class Generic(x_coords: List[float], y_coords: List[float], unit: str = 'mm')[source]

Bases: Shape

A generic shape defined by its x and y coordinates.

Parameters:

x_coords – List of x coordinates.
y_coords – List of y coordinates.
unit – Scale unit of the coordinates.

property x_coords: List[float]: List of x coordinates.

property y_coords: List[float]: List of y coordinates.

property unit: str: Scale unit of the coordinates.

area() → float[source]: Use the Shoelace formula to calculate the area of the polygon. Only works for closed shapes.

class Metadata(measurement: str, measurement_settings: DatabaseDict, sample_id: str, device: str, channels: List[str], channels_settings: List[DatabaseDict], interface: str, interface_dimensions: str, contact_ids: List[str], contact_positions: List[Tuple[float, float]], pixel_dimensions: List[str], dcmi: Dict[str, str] | None = None)[source]

Bases: object

Contains the metadata of the experiment which is stored in the database. Follows the Dublin Core Metadata Initiative and uses standard values from the config.ini where applicable.

Parameters:

measurement – Name of the measurement procedure as implemented in the corresponding class.
measurement_settings – Dictionary containing the measurement settings.
sample_id – Unique identifier of the sample.
device – Name of the used device class.
channels – List of class names of the channels.
channels_settings – List of settings dictionaries of the channels.
interface – Name of the used interface class.
interface_dimensions – String representation of a Shape object which corresponds to the shape of the interface.
contact_ids – List of contact id strings.
contact_positions – List of the contact position tuples which correspond to the coordinates of the contacts on the interface.
pixel_dimensions – List of Shape strings which represent the sizes and shapes of the pixels on the sample.
dcmi – Optional dictionary of terms of the Dublin Core Metadata Initiative which will overwrite the default values.

property measurement: str: Name of the measurement procedure as implemented in the corresponding class.

property measurement_settings: DatabaseDict: Dictionary containing the measurement settings.

property settings_hash: str: The measurement_settings parsed into a string.

property sample_id: str: Unique identifier of the sample.

property device: str: Name of the used device class.

property channels: List[str]: List of class names of the channels.

property channels_settings: List[DatabaseDict]: List of settings dictionaries of the channels.

property interface: str: Name of the used interface class.

property interface_dimensions: str: String representation of a Shape object which corresponds to the shape of the interface.

property contact_ids: List[str]: List of contact id strings.

property contact_positions: List[Tuple[float, float]]: List of the contact position tuples which correspond to the coordinates of the contacts on the interface.

property contact_position_dict: Dict[str, Tuple[float, float]]: A dictionary mapping the contact_ids to the contact_positions.

property pixel_dimensions: List[str]: List of Shape strings which represent the sizes and shapes of the pixels on the sample.

property pixel_dimension_dict: Dict[str, str]: A dictionary mapping the contact_ids to the pixel_dimensions.

property dcmi: Dict[str, str]: Dictionary containing the applicable core terms of the Dublin Core Metadata Initiative.

static parse_settings_hash(settings: DatabaseDict) → str[source]

Parses the settings in form of a hash string.

Parameters:: settings – Dictionary containing the settings.
Returns:: Settings hash string.

class Database(path: str)[source]

Bases: object

Handles data management with methods for storing and retrieving data from an HDF5 file. A new file is created during initialization if no existing one is found.

Parameters:

path – String of the HDF5 file path which must have an ‘.hdf5’ or ‘.h5’ suffix.

Raises:

ValueError – If the suffix of path is not correct.
PermissionError – If the path cannot be written.
IsADirectoryError – If the path is not a file.

property path: Path: The file path of the HDF5 database file.

property timestamp: str: UTC datetime string in ISO format which is updated to the current time before it is returned.

property timestamp_size: int: The string length of the self.timestamp.

initialize_dataset(m: Metadata) → str[source]

Pre-structures the data in groups according to the metadata and returns the path of the dataset.

Parameters:: m – Metadata object which contains all the information to structure the dataset. The information is saved in the database alongside the data.
Returns:: Dataset path in the database.

delete_dataset(dataset: str) → None[source]

Deletes a dataset in the database.

Parameters:: dataset – Dataset path in the database.

delete_data(dataset: str, contact_id: str) → None[source]

Deletes a single data array from the specified dataset.

Parameters:

dataset – Dataset path in the database.
contact_id – ID of the contact, i.e., the identifier of the data array which should be deleted.

save_data(data: ndarray, dataset: str, contact_id: str = '0') → None[source]

Stores a data array in the database. Overrides existing data.

Parameters:

data – Data array to be stored which should be a structured Numpy array. The names of the fields should contain the unit of the quantity in parentheses at the end of the string, e.g., ‘Voltage (V)’
dataset – Dataset path in the database.
contact_id – ID of the contact from the contact_ids of the Interface object. Defaults to ‘0’.

load_data(dataset: str, contact_ids: str | Iterable[str]) → List[ndarray][source]

Loads individual data arrays from a dataset.

Parameters:

dataset – Dataset path in the database.
contact_ids – ID(s) of the contact(s) to load data from. Can be a single string or an iterable of strings.

Returns:

List of loaded data arrays corresponding to the specified dataset and contact IDs.

load_metadata(dataset: str) → Metadata[source]

Loads the metadata of a dataset.

Parameters:: dataset – Dataset path in the database.
Returns:: The metadata corresponding to the specified dataset.

load_dataset(dataset: str) → Dataset[source]

Loads an entire dataset including the metadata.

Parameters:: dataset – Dataset path in the database.
Returns:: A dictionary of contact IDs and loaded data arrays together with the corresponding metadata.

get_dataset_length(dataset: str) → int[source]

Returns the number of data arrays in a dataset.

Parameters:: dataset – Dataset path in the database.
Returns:: Number of data arrays.

get_measurements() → List[str][source]

Returns a list of measurement name strings which are available in the database.

Returns:: List of measurement name strings.

get_measurement_settings(dataset: str) → DatabaseDict[source]

Returns the measurement settings of the provided dataset.

Parameters:: dataset – Dataset path in the database.
Returns:: Dictionary of the measurement settings.

get_filters(measurement: str) → Dict[str, Set[DatabaseValue]][source]

Retrieve the unique filter values for a given measurement procedure in the database.

This method scans the specified measurement group in the database and collects the unique filter values for each filter attribute. The filters are returned as a dictionary where the keys represent the filter attribute names, and the values are sets of unique filter values as tuples.

Parameters:: measurement – The name of the measurement group in the database.
Returns:: A dictionary of filter attributes and their unique filter values.

filter_by_settings(measurement: str, settings: DatabaseDict) → List[str][source]

Filters the measurements by the specified settings.

Parameters:

measurement – String identifier of the measurement in the database.
settings – Dictionary containing the settings to search for.

Returns:

List of dataset paths matching the specified settings.

filter_by_settings_batch(measurement: str, settings_batch: Dict[str, List[DatabaseValue]]) → List[str][source]

Subsequently filters the measurements by the specified settings batch.

Parameters:

measurement – String identifier of the measurement in the database.
settings_batch – Dictionary mapping the setting names to value lists which are used to subsequently filter the measurements.

Returns:

List of dataset paths matching the specified settings batch.

get_sample_ids() → List[str][source]

Returns a list of sample_id strings which are available in the database under /SAMPLES.

Returns:: List of sample_id strings.

filter_by_sample_id(sample_id: str) → List[str][source]

Filters the measurements by the specified sample.

Parameters:: sample_id – String identifier of the sample in the database.
Returns:: List of dataset paths matching the specified sample id.