ionique.io
The io module provides file readers for nanopore data formats. All readers
subclass AbstractFileReader and return (metadata, current, voltage)
tuples.
EDHReader— Element Data Header files (.edh)OPTReader— Orbit Potential files (.opt)ABFReader— Axon Binary Format files (.abf)
See Data Input for usage examples.
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:
objectAn abstract class for reading various data files (.abf, .edh, .mat, .opt, .xml) This class defines the structure for file readers
- __init__()
- accepted_keywords = []
- ext = '___'
- read(filename: str, **kwargs)
Read a datafile or series of files, identified by their extension.
Data formats that come with a header file must be referred to by the header file. If inheriting from AbstractFileReader, do not override this method; instead, create a custom
_readmethod.- Parameters:
filename (str or os.PathLike or list[str] or list[os.PathLike]) – File name or list of file names.
**kwargs – Keyword arguments passed directly to the format-specific
_readmethod.
- Returns:
A tuple of
(metadata, current, voltage). Iffilenameis a list, returns a generator that yields the output of_read()for each file.- Return type:
tuple[dict, np.ndarray, np.ndarray or list[tuple[slice, np.float32]]]
- class ionique.io.EDHReader(edh_filename, voltage_compress=False, n_remove=0, downsample=1, prefilter=None)
Bases:
AbstractFileReaderReader 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, optional) – If True, splits signal into segments based on voltage steps. Defaults to False.
n_remove (int, optional) – Number of samples to remove from the beginning of each voltage step. Defaults to 0.
downsample (int, optional) – Downsampling factor to reduce data size. Defaults to 1.
prefilter (callable or None, optional) – Callable to apply preprocessing to the current signal. Defaults to None.
- accepted_keywords = ['voltage_compress', 'n_remove', 'downsample', 'prefilter']
- ext = '.edh'
- class ionique.io.OPTReader(opt_filename: str, voltage_compress=False, n_remove=0, downsample=1, prefilter=None)
Bases:
AbstractFileReaderReader 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 data file.
voltage_compress (bool, optional) – If True, splits signal into segments based on voltage steps. Defaults to False.
n_remove (int, optional) – Number of samples to remove from the beginning of each voltage step. Defaults to 0.
downsample (int, optional) – Downsampling factor to reduce data size. Defaults to 1.
prefilter (callable or None, optional) – Callable to apply preprocessing to the current signal. Defaults to None.
- accepted_keywords = ['voltage_compress', 'n_remove', 'downsample', 'prefilter']
- ext = '.opt'
- find_peaks_in_segment(current_data, start_index, end_index)
Apply
scipy.signal.find_peakson a slice of the current signal.- Parameters:
- Returns:
peaks (np.ndarray) – Indices of detected peaks relative to the start of the slice.
properties (dict) – Properties dict returned by
scipy.signal.find_peaks.
- find_peaks_slide_window(current, start_index, window_shift_duration=0.002, sampling_frequency=250000, sign='negative')
Find the first capacitive peak near a voltage transition in the current signal.
Searches a symmetric window of half-width
window_shift_durationseconds aroundstart_indexfor a positive or negative peak, and returns the left edge of the first detected peak.- Parameters:
current (np.ndarray) – Full ionic current signal array.
start_index (int) – Approximate sample index of the voltage transition.
window_shift_duration (float, optional) – Half-width of the search window in seconds. Defaults to 0.002.
sampling_frequency (int, optional) – Sampling rate in Hz. Defaults to 250000.
sign (str, optional) – Direction of the peak to search for:
"negative"or"positive". Defaults to"negative".
- Returns:
Sample index of the left edge of the first detected peak, or
Noneif no peak was found within the window.- Return type:
int or None
- process_custom_xml()
Process a custom timestamp-based XML file to reconstruct the voltage waveform.
Extracts voltage data and time points from
<timestamp>elements, then aligns the reconstructed voltage waveform with the current signal by detecting capacitive peaks at each voltage transition.