ionique.io

Input/output utilities for data files.

This module provides an interface for loading, parsing, and preprocessing signal data from various file formats (e.g., .edh, .opt, .abf, .dat, .xml). It defines a base reader class and concrete implementations that handle format-specific logic, metadata extraction, data alignment, and optional preprocessing steps.

This module is central to converting raw experimental data into analyzable form.

class ionique.io.AbstractFileReader

Bases: object

An abstract class for reading various data files (.abf, .edh, .mat, .opt, .xml) This class defines the structure for file readers

__init__()
accepted_keywords = []
current_multiplier: float = 1.0
ext = '___'
read(filename: str, **kwargs)

Read a datafile or series of files. Files are identified according to their extension. Data formats that come with a header file must be referred to by the header file. If inheriting from the AbstractFileReader class, do not override this function; instead, create a custom _read method.

Parameters:

filename – file name or list of file names, typically

given as a string or PathLike object. :type filename: str or os.PathLike or list[str] or list[os.PathLike] :param **kwargs: keyword arguments passed directly to the file reader class that matches the data format. :return: [metadata, current, etc.. ]. If the input “filename” is a list, this function returns a generator object that yields the output of _read() for every file in the input list. :rtype: tuple[dict,np.ndarray [,np.ndarray or tuple[slice,np.float32]]]

voltage_multiplier: float = 1.0
class ionique.io.EDHReader(edh_filename, voltage_compress=False, n_remove=0, downsample=1, prefilter=None)

Bases: AbstractFileReader

Reader class for loading .edh data files and their associated current data.

This class parses the .edh header file and automatically loads the corresponding signal data (either from .abf or .dat files in the same directory). It extracts metadata, converts raw current and voltage data to SI units, and supports optional preprocessing steps such as voltage step segmentation, downsampling, and signal filtering.

__init__(edh_filename, voltage_compress=False, n_remove=0, downsample=1, prefilter=None)

Initialize the EDHReader and load signal data from associated files.

Parameters:

  • edh_filename (str) – Path to the .edh header file.

  • voltage_compress (bool) – If True, splits signal into segments based on voltage steps.

  • n_remove (int) – Number of samples to remove from the beginning of each voltage step.

  • downsample (int) – Downsampling factor to reduce data size.

  • prefilter (callable or None) – Callable to apply preprocessing to the current signal.

accepted_keywords = ['voltage_compress', 'n_remove', 'downsample', 'prefilter']
current_multiplier: float = 1e-09
ext = '.edh'
voltage_multiplier: float = 0.001
class ionique.io.OPTReader(opt_filename: str, voltage_compress=False, n_remove=0, downsample=1, prefilter=None)

Bases: AbstractFileReader

Reader for .opt data files with corresponding XML or _volt.opt metadata.

This class reads current data from .opt files and attempts to extract or reconstruct corresponding voltage data using associated .xml or _volt.opt files found in the same directory. It handles metadata extraction, signal preprocessing, voltage alignment, and segment compression based on voltage steps.

Supported XML structures include both standard HWtiming_cap_step formats and timestamp-based custom formats.

__init__(opt_filename: str, voltage_compress=False, n_remove=0, downsample=1, prefilter=None)

Initialize the OPTReader instance and load corresponding files.

Parameters:

  • opt_filename (str) – Path to the .opt header file.

  • voltage_compress (bool) – If True, splits signal into segments based on voltage steps.

  • n_remove (int) – Number of samples to remove from the beginning of each voltage step.

  • downsample (int) – Downsampling factor to reduce data size.

  • prefilter (callable or None) – Callable to apply preprocessing to the current signal.

accepted_keywords = ['voltage_compress', 'n_remove', 'downsample', 'prefilter']
current_multiplier: float = 1000000000.0
ext = '.opt'
find_peaks_in_segment(current_data, start_index, end_index)

Apply “find_peaks” on a segment of the current data and return the indices of the found peak

find_peaks_slide_window(current, start_index, window_shift_duration=0.002, sampling_frequency=250000, sign='negative')

Find peaks in the current every time the voltage changes. The search for the peaks happens in the window of the timestamp 0.02 seconds.

process_custom_xml()

Processes the custom XML file to extract voltage data, align the voltage waveform with the current, and detect peaks in the current signal every time the voltage changes.

ionique.io.load_files_GUI()
Create a form with:

  • ‘Compress voltage (only uncheck if voltage is not stepwise, e.g., triangle wave)’ : checkbox

  • ‘Apply Filter?’ : checkbox

  • If ‘Apply Filter?’ checked: dynamic form from the Filter dataclass (types, options, limits).

Returns (frame, get_values) where get_values() -> dict with:

{‘compress_voltage’: bool, ‘apply_filter’: bool, ‘filter’: Filter|None}

ionique.io.select_files_GUI()

Open a file dialog allowing multiple selection, but only for ONE file type at a time. Users can switch the dialog’s file-type dropdown, but the final selection must be homogeneous (all the same extension) and in the allowed list.

Returns

tuple[str, …]

Absolute paths of the selected files (empty tuple if the user cancels).