ionique.utils

Signal Processing and Data Extraction Utilities

This module provides a set of utility functions and classes designed for use in signal processing workflows.

These tools are intended for both internal processing and external use cases such as analysis pipelines and API integrations.

class ionique.utils.Filter(cutoff_frequency: float, filter_type: Literal['lowpass', 'highpass', 'bandpass', 'bandstop'], filter_method: Literal['butter', 'bessel'] = 'butter', order: int = 2, bidirectional: bool = True, sampling_frequency: float | None = None)

Bases: object

This class allows a user to apply low-pass, high-pass, band-pass, or band-stop filters using standard filter types (Butterworth or Bessel). Filters are implemented using second-order sections (SOS) for numerical stability and can be applied in either forward-only or bidirectional mode.

Parameters:

cutoff_frequency (float or list[float]) – The cutoff frequency or frequency band for the filter in Hz. For band filters, provide the band center or list of [low, high] values.
filter_type (Literal["lowpass", "highpass", "bandpass", "bandstop"]) – The type of filter to apply. Options are “lowpass”, “highpass”, “bandpass”, or “bandstop”.
filter_method (Literal["butter", "bessel"]) – The filter method. Supported options: “butter” (Butterworth), “bessel”. Defaults to “butter”.
order (int) – The order of the filter. Must be >= 1. Defaults to 2.
bidirectional (bool) – If True, applies filtering forward and backward using sosfiltfilt. If False, uses causal sosfilt. Defaults to True.
sampling_frequency (float, optional) – Sampling frequency of the signal in Hz.

__init__(cutoff_frequency: float, filter_type: Literal['lowpass', 'highpass', 'bandpass', 'bandstop'], filter_method: Literal['butter', 'bessel'] = 'butter', order: int = 2, bidirectional: bool = True, sampling_frequency: float | None = None) → None

bidirectional: bool = True

cutoff_frequency: float

filter_method: Literal['butter', 'bessel'] = 'butter'

filter_type: Literal['lowpass', 'highpass', 'bandpass', 'bandstop']

order: int = 2

sampling_frequency: float = None

class ionique.utils.Singleton(*args, **kwargs)

Bases: type

Generic singleton metaclass.

This metaclass ensures the same return every time the class is instanced.

__init__(*args, **kwargs)

Class initialization

Parameters:

args – Arguments for the class
kwargs – Keyword arguments for the class

class ionique.utils.Trimmer(samples_to_remove: int, rank: str = 'vstep', newrank: str = 'vstepgap')

Bases: object

Segment trimming utility for hierarchical signal data.

This class operates on a segment tree. It traverses segments of a given rank (e.g., “vstep”) and trims a fixed number of samples from the start of each segment. The resulting trimmed segments are added as new child segments with a specified new rank (e.g., “vstepgap”).

This is useful when initial samples of each segment include artifacts that should be excluded from analysis.

Parameters:

samples_to_remove (int) – Number of samples to trim from the beginning of each segment.
rank (str) – The hierarchical rank of segments to target for trimming. Defaults to “vstep”.
newrank (str) – The rank name to assign to newly created trimmed child segments. Defaults to “vstepgap”.

__init__(samples_to_remove: int, rank: str = 'vstep', newrank: str = 'vstepgap') → None

newrank: str = 'vstepgap'

rank: str = 'vstep'

samples_to_remove: int

ionique.utils.extract_features(seg, bottom_rank, extractions: list[str], add_ons: dict = {}, lambdas={})

Extract features from hierarchical segments into a DataFrame.

Traverses a hierarchical segment structure down to bottom_rank, then collects feature values from each segment. Static features are retrieved via get_feature(), constants can be added via add_ons, and custom computed features can be provided through lambdas.

This is useful for generating structured datasets from annotated traces for statistical analysis or machine learning.

Parameters:

seg (object) – The root segment or trace object containing a hierarchical structure. It must implement traverse_to_rank() and support get_feature().
bottom_rank (str) – The rank name of the lowest-level segments from which to extract features.
extractions (list[str]) – List of feature names to extract directly using get_feature() on each segment. Common examples include: ‘mean’, ‘frac’, ‘duration’, ‘baseline’, ‘current’, ‘wrap’, ‘start’.
add_ons (dict) – A dictionary of fixed key-value pairs to include as constant columns in the resulting DataFrame.
lambdas (dict) – A dictionary mapping column names to lambda functions that compute derived values from each segment.

Returns:

A pandas DataFrame where each row corresponds to a bottom-rank segment and columns represent extracted and computed features.

Return type:

pandas.DataFrame

ionique.utils.si_eval(value, unit=None, return_unit=False)

Evaluate and convert a value with an SI unit prefix to its numeric base value.

This function handles both string-based and numeric values with SI (International System of Units) prefixes such as “k” (kilo), “M” (mega), “μ” (micro), etc. It multiplies the input value by the appropriate factor based on the SI prefix.

This utility is useful when parsing human-readable measurement strings or standardizing units across data pipelines that mix strings and numeric formats.

Parameters:

value (str or float) – The value to be converted. Can be a string like “1.2 kHz” or a numeric value (int or float).
unit (str, optional) – The unit string (e.g., “kHz”, “mV”). Required only if value is a numeric type.
return_unit (bool, optional) – If True, returns a tuple containing the converted numeric value and the base unit (e.g., ‘Hz’). If False, only the numeric value is returned.

Raises:

ValueError – If the input format is invalid or the unit is missing for numeric input.
TypeError – If the value is neither a string nor a numeric type.

Returns:

The converted value, optionally paired with the base unit.

Return type:

float or tuple[float, str]

ionique.utils.split_voltage_steps(voltage: ndarray, n_remove=0, as_tuples=False)

Split a voltage signal into segments based on step changes.

This function detects changes in the voltage signal and splits it into individual segments (or steps) wherever a change in value occurs. It is useful in analyzing stepwise voltage protocols.

Optionally, a number of initial samples can be removed from each segment using the n_remove parameter. The output can either be two separate arrays of start and end indices, or a list of tuples representing each segment.

Parameters:

voltage (numpy.ndarray) – 1D voltage signal array to be segmented.
n_remove (int) – Number of samples to remove from the start of each split. Defaults to 0.
as_tuples (bool) – If True, returns a list of (start, end) index tuples. If False, returns two arrays: start_indices and end_indices. Defaults to False.

Raises:

ValueError – If n_remove is negative or larger than the start of the voltage changes.

Returns:

Either: - A tuple of (start_indices, end_indices), where each is a numpy array of indices. - A list of (start, end) tuples if as_tuples=True.

Return type:

tuple[numpy.ndarray, numpy.ndarray] or list[tuple[int, int]]