Utilities#

Utility functions for MDA file processing and data manipulation.

This module provides various utility functions for handling MDA files, data conversion, and general utility operations.

get_file_info(file_path)

Get file information.

get_scan(mda_file_data)

Extracts scan positioners and detectors from an MDA file data object and prepares datasets.

mda2ftm(selection)

Converts a field selection from MDA_MVC (MVC) format to SelectFieldsTableModel (TM) format.

ftm2mda(selection)

Converts a field selection from SelectFieldsTableModel (TM) format to MDA_MVC (MVC) format.

byte2str(byte_literal)

Converts a byte literal to a UTF-8 encoded string.

num2fstr(x)

Return a string with the adequate precision and format.

getUiFileName(py_file_name)

UI file name matches the Python file, different extension.

human_readable_size(size[, decimal_places])

Convert size in bytes to human readable format.

iso2dt(iso_date_time)

Convert ISO8601 time string to datetime object.

iso2ts(iso_date_time)

Convert ISO8601 time string to timestamp.

myLoadUi(ui_file[, baseinstance])

Load a .ui file for use in building a GUI.

removeAllLayoutWidgets(layout)

Remove all existing widgets from QLayout.

run_in_thread(func)

(decorator) run func in thread

ts2dt(timestamp)

Convert timestamp to datetime object.

ts2iso(timestamp)

Convert timestamp to ISO8601 time string.
mdaviz.utils.byte2str(byte_literal)[source]#

Converts a byte literal to a UTF-8 encoded string. If the input is not a byte literal, it is returned as is without any conversion.

Parameters:

  • byte_literal (bytes | Any): The byte literal to be decoded or any input to be returned as is if not bytes.

Returns:

  • str | Any: The decoded string if the input is a byte literal, otherwise the original input.

mdaviz.utils.extract_file_prefix(file_name: str, scan_number: int | None) → str | None[source]#

Create a pattern that matches the prefix followed by an optional separator and the scan number with possible leading zeros.

The separators considered here are underscore (_), hyphen (-), dot (.), and space ( )

Parameters:

file_name (str): Name of the file scan_number (int | None): Scan number to extract prefix for

Returns:

str | None: Extracted prefix or None if no match

mdaviz.utils.ftm2mda(selection: dict | None) → dict[source]#

Converts a field selection from SelectFieldsTableModel (TM) format to MDA_MVC (MVC) format.

The TM format {1: ‘X’, 2: ‘Y’, 4: ‘Y’, 4: ‘I0’} is transformed into MVC format {‘Y’: [2, 3], ‘X’: 1, ‘I0’: 4}. Used to update MDA_MVC selection state (self.selectionField()) based on changes in SelectFieldsTableModel.

Parameters:

selection (dict | None): The selection in TM format to be converted.

Returns:

dict: The selection converted to MVC format.

mdaviz.utils.getUiFileName(py_file_name: str) → str[source]#

UI file name matches the Python file, different extension.

Parameters:

py_file_name (str): Python file name

Returns:

str: Corresponding UI file name

mdaviz.utils.get_det(mda_file_data)[source]#

Extracts scan positioners and detectors from an MDA file data object.

This function processes an mda.scanDim object to extract its scanPositioner and scanDetector instances. It organizes these instances into a dictionary, with their indexes as keys in the order of p0, P1,... Px, D01, D02,... DX. p0 is a default scanPositioner object representing the point index. If additional positioners exist, they follow p0 in sequence. The first detector is labeled D01 and subsequent detectors follow in numerical order.

Parameters:

  • mda_file_data: An instance of an mda.scanDim object, which contains the MDA file data to be processed.

Returns:

A tuple containing:

  • A dictionary (d) where keys are indexes, mapping to either scanPositioner or scanDetector objects. The dictionary is structured as {0: p0, 1: P1, ..., np: D01, np+1: D02, ..., np+nd: DX}.

  • The index (first_pos) of the first positioner in the returned dictionary. This is 1 if a positioner other than the default index positioner exists, otherwise 0.

  • The index (first_det) of the first detector in the returned dictionary, which directly follows the last positioner.

Notes:

  • p0 is created by default and corresponds to the point index, described as an ‘Index’ scanPositioner object with predefined properties.

  • np is the total number of positioners, nd the number of detectors, and npts the number of data points actually acquired.

mdaviz.utils.get_file_info(file_path: Path) → dict[source]#

Get file information. This is an alias for get_file_info_full for backward compatibility.

Parameters:

file_path (Path): Path to the MDA file

Returns:

dict: Complete file information

mdaviz.utils.get_file_info_full(file_path: Path) → dict[source]#

Get complete file information by loading the full MDA data.

This is the original get_file_info function, renamed for clarity. Use this only when detailed file information is needed.

Parameters:

file_path (Path): Path to the MDA file

Returns:

dict: Complete file information including all metadata and data

mdaviz.utils.get_file_info_lightweight(file_path: Path) → dict[source]#

Get lightweight file information without loading full MDA data.

This function extracts only the essential metadata needed for the folder view without loading the complete file data, making it much faster for large folders.

Parameters:

file_path (Path): Path to the MDA file

Returns:

dict: Dictionary containing lightweight file information with keys:

  • Name: File name

  • Prefix: File prefix (if extractable)

  • Number: Scan number (if available)

  • Points: Number of data points (if available)

  • Dimension: Scan dimension (if available)

  • Positioner: First positioner name (if available)

  • Date: File date (if available)

  • Size: Human readable file size

mdaviz.utils.get_md(mda_file_metadata: dict) → dict[source]#

Process MDA file metadata to convert bytes to strings and clean up structure.

Parameters:

mda_file_metadata (dict): Raw metadata from MDA file

Returns:

dict: Processed metadata with string keys and cleaned values

mdaviz.utils.get_scan(mda_file_data)[source]#

Extracts scan positioners and detectors from an MDA file data object and prepares datasets.

Processes an mda.scanDim object to extract scanPositioner and scanDetector instances, organizing them into a dictionary with additional metadata like data, units, and names. A default scanPositioner object representing the point index (p0) is included. If additional positioners exist, they follow p0 in sequence. The first detector is labeled D01 and subsequent detectors follow in numerical order: p0, p1,… px, d01, d02,… dX.

Parameters:

  • mda_file_data: An instance of an mda.scanDim object to be processed.

Returns:

A tuple containing:

  • A dictionary keyed by index, each mapping to a sub-dictionary containing the scan object along with its data, unit, name and type. Structure: {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...','type':...}}.

  • The index (first_pos) of the first positioner in the returned dictionary. This is 1 if a positioner other than the default index positioner exists, otherwise 0.

  • The index (first_det) of the first detector in the returned dictionary, which directly follows the last positioner.

mdaviz.utils.get_scan_2d(mda_file_data_dim1, mda_file_data_dim2)[source]#

Extracts scan positioners and detectors from 2D MDA file data objects and prepares datasets.

Processes two mda.scanDim objects (outer and inner dimensions) to extract scanPositioner and scanDetector instances, organizing them into a dictionary with additional metadata. For 2D data, the structure is typically:

  • dim1 (outer): X2 positioner + detectors

  • dim2 (inner): X1 positioner + detectors

Parameters:

  • mda_file_data_dim1: An instance of an mda.scanDim object for the outer dimension

  • mda_file_data_dim2: An instance of an mda.scanDim object for the inner dimension

Returns:

A tuple containing:

  • A dictionary keyed by index, each mapping to a sub-dictionary containing the scan object along with its data, unit, name and type. For 2D data, detectors have 2D arrays: data[X2_index][X1_index] For positioners, includes all_positioners list and np count for full positioner information.

  • The index (first_pos) of the first positioner in the returned dictionary

  • The index (first_det) of the first detector in the returned dictionary

mdaviz.utils.human_readable_size(size: float, decimal_places: int = 2) → str[source]#

Convert size in bytes to human readable format.

Parameters:

size (float): Size in bytes decimal_places (int): Number of decimal places to show

Returns:

str: Human readable size string

mdaviz.utils.iso2dt(iso_date_time: str) → datetime[source]#

Convert ISO8601 time string to datetime object.

Parameters:

iso_date_time (str): ISO8601 formatted time string

Returns:

datetime: Datetime object

mdaviz.utils.iso2ts(iso_date_time: str) → float[source]#

Convert ISO8601 time string to timestamp.

Parameters:

iso_date_time (str): ISO8601 formatted time string

Returns:

float: Unix timestamp

mdaviz.utils.mda2ftm(selection: dict | None) → dict[source]#

Converts a field selection from MDA_MVC (MVC) format to SelectFieldsTableModel (TM) format.

The MVC format {‘Y’: [2, 3], ‘X’: 1, ‘I0’: 4} is transformed into TM format {1: ‘X’, 2: ‘Y’, 4: ‘Y’, 4: ‘I0’}. This is used to sync selection states between SelectFieldsTableModel and MDA_MVC.

Parameters:

selection (dict | None): The selection in MVC format to be converted.

Returns:

dict: The selection converted to TM format.

mdaviz.utils.myLoadUi(ui_file, baseinstance=None, **kw)[source]#

Load a .ui file for use in building a GUI.

Wraps uic.loadUi() with code that finds our program’s resources directory.

See:

http://nullege.com/codes/search/PyQt4.uic.loadUi

See:

http://bitesofcode.blogspot.ca/2011/10/comparison-of-loading-techniques.html

inspired by: http://stackoverflow.com/questions/14892713/how-do-you-load-ui-files-onto-python-classes-with-pyside?lq=1

mdaviz.utils.num2fstr(x: float) → str[source]#

Return a string with the adequate precision and format.

Parameters:

x (float): Number to format

Returns:

str: Formatted string

mdaviz.utils.reconnect(signal, new_slot)[source]#

Disconnects any slots connected to the given signal and then connects the signal to the new_slot.

Parameters:

  • signal: The signal to disconnect and then reconnect.

  • new_slot: The new slot to connect to the signal.

Note:

  • this function catches TypeError which occurs if the signal was not connected to any slots.

mdaviz.utils.removeAllLayoutWidgets(layout) → None[source]#

Remove all existing widgets from QLayout.

Parameters:

layout: QLayout object to clear

mdaviz.utils.run_in_thread(func)[source]#

(decorator) run func in thread

USAGE:

@run_in_thread
def progress_reporting():
    logger.debug("progress_reporting is starting")
    # ...

#...
progress_reporting()   # runs in separate thread
#...
mdaviz.utils.ts2dt(timestamp: float) → datetime[source]#

Convert timestamp to datetime object.

Parameters:

timestamp (float): Unix timestamp

Returns:

datetime: Datetime object

mdaviz.utils.ts2iso(timestamp: float) → str[source]#

Convert timestamp to ISO8601 time string.

Parameters:

timestamp (float): Unix timestamp

Returns:

str: ISO8601 formatted time string