elecphys package

Submodules

elecphys.cfc module

elecphys.cfc.band_tfMVL(x, high_freq, low_freq, fs: int) → float

Function that Calculates the tf_MVL for a given signal x

Parameters:

  • x (np.array) – signal in time domain

  • high_freq (list) – high frequency band (Hz)

  • low_freq (list) – low frequency band (Hz)

  • fs (int) – sampling frequency (Hz)

Returns:

tf_canolty – tf_MVL

Return type:

float

elecphys.cfc.butterworth_filter(sig, filt_freq: float, fs: int) → ndarray

Function that Filters signal array

Parameters:

  • sig (np.array) – signal in time domain

  • filt_freq (float) – filter frequency (Hz)

  • fs (int) – sampling frequency (Hz)

Returns:

  • filtered_sig (np.ndarray) – filtered signal

  • b (np.ndarray) – filter numerator coefficients

  • a (np.ndarray) – filter denominator coefficients

elecphys.cfc.calc_MVL(phase, amp) → ndarray

Function that Calculates the MVL for a given signal phasae and amplitude

Parameters:

  • phase (np.array) – phase values

  • amp (np.array) – amplitude values

Returns:

MVL – MVL values

Return type:

np.array

elecphys.cfc.calc_tf_mvl(x, fs: int, freqs_phase: list, freqs_amp: list) → ndarray

Function that Calculates the tf_MVL matrix for a given signal x

Parameters:

  • x (np.array) – signal in time domain

  • fs (float) – sampling frequency (Hz)

  • freqs_phase (list) – phase frequencies (Hz)

  • freqs_amp (list) – amplitude frequencies (Hz)

Returns:

MI_mat – 2D tf_MVL matrix (phase x amplitude)

Return type:

np.ndarray

elecphys.cfc.cfc_mi(sig, freqs_phase: list, freqs_amp: list, fs: int, nbins: int = 20) → ndarray

Function that Calculates the MI matrix for a given signal x

Parameters:

  • sig (np.array) – signal in time domain

  • freqs_phase (list) – phase frequencies (Hz)

  • freqs_amp (list) – amplitude frequencies (Hz)

  • fs (int) – sampling frequency (Hz)

  • nbins (int) – number of bins

Returns:

MI_mat – 2D MI matrix (phase x amplitude)

Return type:

np.ndarray

elecphys.cfc.chwi_krn(D, L, A) → ndarray

Function that Calculates the chwi_krn for a given signal x

Parameters:

  • D (np.array) – D

  • L (np.array) – L

  • A (float) – A

Returns:

k – chwi_krn

Return type:

np.ndarray

elecphys.cfc.data_wrapper(x, sec_dim) → ndarray

Function that Wraps the data for a given signal x

Parameters:

  • x (np.array) – signal in time domain

  • sec_dim (int) – second dimension

Returns:

wrapped_x – wrapped signal

Return type:

np.ndarray

elecphys.cfc.extract_inst_amp(sig) → ndarray

Function that Extracts the instantaneous amplitude for a given signal x

Parameters:

sig (np.array) – signal in time domain

Returns:

inst_amplitude – instantaneous amplitude

Return type:

np.ndarray

elecphys.cfc.extract_inst_phase(sig) → ndarray

Function that Extracts the instantaneous phase for a given signal x

Parameters:

sig (np.array) – signal in time domain

Returns:

inst_phase – instantaneous phase

Return type:

np.ndarray

elecphys.cfc.rid_rihaczek4(x, fbins) → ndarray

Function that Calculates the rid_rihaczek4 for a given signal x

Parameters:

  • x (np.array) – signal in time domain

  • fbins (int) – number of frequency bins

Returns:

tfd – 2D rid_rihaczek4 matrix

Return type:

np.ndarray

elecphys.conversion module

elecphys.conversion.convert_OpenBCI_csv_to_npz(file_path: str, output_npz_folder: str, notch_filter_freq: int) → None

Function that Converts OpenBCI CSV files to NPZ files

Parameters:

  • file_path (str) – path to OpenBCI csv file

  • output_npz_folder (str) – path to output npz folder

  • notch_filter_freq (int) – frequency of notch filter

elecphys.conversion.convert_mat_to_npz(mat_file: str, output_npz_folder: str, notch_filter_freq: int) → None

Function that Converts MAT files to NPZ files

Parameters:

  • mat_file (str) – path to mat file

  • output_npz_folder (str) – path to output npz folder

elecphys.conversion.convert_rhd_to_mat(folder_path: str, output_mat_file: str, ds_factor: int) → None

Function that Converts RHD files to mat files using RHD to MAT converter written in MATLAB

Parameters:

  • folder_path (str) – path to folder containing RHD files

  • output_mat_file (str) – path to output mat file

  • ds_factor (int) – downsample factor

elecphys.data_loading module

elecphys.dimensionality_reduction module

elecphys.dimensionality_reduction.pca_from_npz(input_npz_folder, output_npz_folder, n_components, matrix_whitenning, channels_list) → None

Performs PCA on NPZ files

Parameters:

  • input_npz_folder (str) – path to input npz folder

  • output_npz_folder (str) – path to output npz folder

  • n_components (int) – number of components to keep

  • matrix_whitenning (bool) – whether to whiten the matrix

  • channels_list (list) – list of channels to plot

elecphys.fourier_analysis module

elecphys.fourier_analysis.butterworth_filtering_from_array(signal_array, fs: int, _args: dict) → ndarray

Filters signal array

Parameters:

  • signal_array (type: np.ndarray) – number of FFT points

  • fs (int) – sampling frequency (Hz)

  • _args (dict) – dictionary containing filter parameters

Returns:

  • signal_array (np.ndarray) – filtered signal array in time domain

  • filter_freq_response (dict) – dictionary containing filter frequency response

elecphys.fourier_analysis.butterworth_filtering_from_npz(input_npz_folder: str, output_npz_folder: str, _args: dict) → None

Filters signal array

Parameters:

  • input_npz_folder (str) – path to input npz folder

  • output_npz_folder (str) – path to output npz folder to save filtered results

  • _args (dict) – dictionary containing filter parameters

elecphys.fourier_analysis.calc_cfc_from_array(signal_array, fs: int, freqs_amp: list, freqs_phase: list, time_interval: list = None) → ndarray

Calculates CFC matrix

Parameters:

  • signal_array (np.ndarray) – 1D array of signal

  • fs (int) – sampling frequency (Hz)

  • freqs_amp (list) – amplitude frequencies (Hz)

  • freqs_phase (list) – phase frequencies (Hz)

  • time_interval (list) – time interval to calculate CFC over in seconds

Returns:

MI_mat – CFC matrix

Return type:

np.ndarray

elecphys.fourier_analysis.calc_cfc_from_npz(input_npz_folder: str, output_npz_folder: str, freqs_amp: list, freqs_phase: list, time_interval: list = None) → None

Calculates CFC matrix

Parameters:

  • input_npz_folder (str) – path to input npz folder

  • output_npz_folder (str) – path to output npz folder to save CFC results

  • freqs_amp (list) – amplitude frequencies (Hz)

  • freqs_phase (list) – phase frequencies (Hz)

  • time_interval (list) – time interval to calculate CFC over in seconds

elecphys.fourier_analysis.calc_freq_response(_args: dict) → ndarray | dict

Calculates filter frequency response

Parameters:

_args (dict) – dictionary containing filter parameters

Returns:

  • f (np.ndarray) – frequency vector

  • mag (np.ndarray) – magnitude vector

  • phase (np.ndarray) – phase vector

  • _args (dict) – dictionary containing filter parameters

elecphys.fourier_analysis.dft_from_array(signal_array, fs: int, nfft: int = None) → ndarray

Computes DFT from 1D array

Parameters:

  • signal_array (np.ndarray) – signal array in time domain

  • fs (int) – sampling frequency (Hz)

  • nfft (int) – number of FFT points

Returns:

  • f (np.ndarray) – frequency vector

  • Zxx (np.ndarray) – DFT vector (complex)

elecphys.fourier_analysis.dft_numeric_output_from_npz(input_npz_folder: str, output_npz_folder: str, nfft: int = None) → None

Computes DFT and saves results as NPZ files

Parameters:

  • input_npz_folder (str) – path to input npz folder

  • output_npz_folder (str) – path to output npz folder to save DFT results

elecphys.fourier_analysis.freq_bands_power_over_time(input_npz_folder: str, freq_bands: tuple | list = None, channels_list: str = None, ignore_channels: str = None, window_size: float = 1, overlap: float = 0.5, t_min: float = None, t_max: float = None, output_csv_file: str = None, output_plot_file: str = None, plot_type: str = 'average_of_channels') → None

Calculates power over time for given frequency bands

Parameters:

  • input_npz_folder (str) – path to input npz folder containing signal npz files (in time domain)

  • freq_bands (tuple, list) – tuple or list of frequency bands to calculate power over time for. It should be a tuple or list of lists, where each list contains two elements: the lower and upper frequency bounds of the band (in Hz). For example, freq_bands = [[1, 4], [4, 8], [8, 12]] would calculate power over time for the delta, theta, and alpha bands.

  • channels_list (str) – list of channels to include in analysis

  • ignore_channels (str) – list of channels to ignore in analysis

  • window_size (float) – window size in seconds to calculate power over time

  • overlap (float) – windows overlap in seconds to calculate power over time

  • t_min (float) – start of time interval to calculate power over time. Default is None which means start from beginning of signal.

  • t_max (float) – end of time interval to calculate power over time. Default is None which means end at end of signal.

  • output_csv_file (str) – path to output csv file to save power over time results

  • output_plot_file (str) – path to output plot file to save power over time results

  • plot_type (str) – type of plot to generate. Options are ‘avg’ or ‘all’. Default is ‘avg’ which plots average power over time for all channels with an erros cloud. ‘all’ plots power over time for all channels individually.

elecphys.fourier_analysis.stft_from_array(signal_array, fs: int, window_size: float, overlap: float, window_type: str = 'hann', nfft: int = None) → ndarray

Computes STFT from 1D array

Parameters:

  • signal_array (np.ndarray) – signal array in time domain

  • fs (int) – sampling frequency (Hz)

  • window_size (float) – window size in seconds

  • overlap (float) – windows overlap in seconds

  • window_type (str) – window type. Default is ‘hann’, but can be any window type supported by scipy.signal.get_window()

  • nfft (int) – number of FFT points

Returns:

  • f (np.ndarray) – frequency vector

  • t (np.ndarray) – time vector

  • Zxx (np.ndarray) – STFT matrix (complex)

elecphys.fourier_analysis.stft_numeric_output_from_npz(input_npz_folder: str, output_npz_folder: str, window_size: float, overlap: float, window_type: str = 'hann') → None

Computes STFT and saves results as NPZ files

Parameters:

  • input_npz_folder (str) – path to input npz folder

  • output_npz_folder (str) – path to output npz folder to save STFT results

  • window_size (float) – window size in seconds

  • overlap (float:) – overlap in seconds

  • window_type (str) – window type. Default is ‘hann’, but can be any window type supported by scipy.signal.get_window()

elecphys.handlers module

class elecphys.handlers.ErrorHandler

Bases: object

Error handler class

Methods

error(e)

Prints error message

error_handler(func)

Error handler decorator
error(e: str)

Prints error message

Parameters:
e: str

error message

Returns:
None
error_handler(func)

Error handler decorator

Parameters:
func: function

function to be decorated

Returns:
wrapper: function

decorated function

elecphys.main module

elecphys.main.main()

elecphys.preprocessing module

elecphys.preprocessing.apply_notch(_signal_chan: ndarray, _args: dict) → ndarray

Applies notch filter to given signal

Parameters:

  • _signal_chan (np.ndarray) – signal channel

  • _args (dict) – dictionary containing notch filter parameters

Returns:

_signal_chan – signal channel with notch filter applied

Return type:

np.ndarray

elecphys.preprocessing.normalize(data: ndarray) → ndarray

Normalizes data

Parameters:

data (umpy.ndarray) – data to be normalized

Returns:

data_normalized – normalized data

Return type:

numpy.ndarray

elecphys.preprocessing.normalize_npz(input_npz_folder: str, output_npz_folder: str) → None

Normalizes NPZ files

Parameters:

  • input_npz_folder (str) – path to input npz folder

  • output_npz_folder (str) – path to output npz folder

elecphys.preprocessing.re_reference(data: ndarray, ignore_channels: list | str = None, rr_channel: int = None) → ndarray

Average re-references data

Parameters:

  • data (numpy.ndarray) – data to be re-referenced. Shape: (n_channels, n_samples)

  • ignore_channels (str, list) – list of channels to be ignored. Either a list of channel indexes or a string of channel indexes separated by commas. If None, no channels will be ignored

  • rr_channel (int) – channel to be used as reference. If None, average re-referencing will be used

Returns:

data_rereferenced – re-referenced data. Shape: (n_channels, n_samples)

Return type:

numpy.ndarray

elecphys.preprocessing.re_reference_npz(input_npz_folder: str, output_npz_folder: str, ignore_channels: list | str = None, rr_channel: int = None) → None

re-references NPZ files

Parameters:

  • input_npz_folder (str) – path to input npz folder

  • output_npz_folder (str) – path to output npz folder

  • ignore_channels (list, str) – list of channels to be ignored. Either a list of channel indexes or a string of channel indexes separated by commas. If None, no channels will be ignored

  • rr_channel (int) – channel to be used as reference. If None, average re-referencing will be used

elecphys.preprocessing.zscore_normalize(data: ndarray) → ndarray

Z-score normalizes data

Parameters:

data (np.ndarray) – data to be normalized

Returns:

data_zscore – normalized data

Return type:

np.ndarray

elecphys.preprocessing.zscore_normalize_npz(input_npz_folder: str, output_npz_folder: str) → None

Z-score normalizes NPZ files

Parameters:

  • input_npz_folder (str) – path to input npz folder

  • output_npz_folder (str) – path to output npz folder

elecphys.utils module

elecphys.utils.check_freq_bands(freq_bands: list, fs: int) → list

checks frequency bands in the tuple to see if they are valid such as first element is smaller than second element and both of them are smaller than half of sampling frequency

Parameters:

freq_bands (tuple) – frequency bands to be checked

Returns:

freq_bands – checked frequency bands

Return type:

tuple

elecphys.utils.convert_string_to_list(string)

Converts string to list

Parameters:

string (str) – string to be converted

Returns:

output – converted list

Return type:

list

elecphys.utils.get_matlab_engine()

Installs MATLAB engine for Python

Returns:

eng – MATLAB engine for Python

Return type:

matlab.engine

elecphys.utils.keep_npz_files(file_names: list) → list

Keeps only NPZ files

Parameters:

file_names (list) – list of file names

Returns:

file_names – list of NPZ file names

Return type:

list

elecphys.utils.remove_non_numeric(input_list: list) → list

Removes None values from list

Parameters:

input_list (list) – list to be processed

Returns:

output_list – processed list

Return type:

list

elecphys.utils.sort_file_names(file_names: list) → list

Sorts file names in ascending order

Parameters:

file_names (list) – list of file names to be sorted

Returns:

file_names – sorted list of file names

Return type:

list

elecphys.visualization module

elecphys.visualization.plot_avg_stft_from_npz(npz_folder_path: str, output_plot_file: str, f_min: int, f_max: int, t_min: float, t_max: float, db_min: int, db_max: int, channels_list: str | list = None) → None

Plots average STFT from NPZ files (STFT must be saved as NPZ file)

Parameters:

  • npz_folder_path (str) – path to input npz folder

  • output_plot_file (str) – path to save figure. If None, will show figure instead of saving it

  • f_min (int) – minimum frequency to plot in Hz

  • f_max (int) – maximum frequency to plot in Hz

  • t_min (float) – minimum time to plot in seconds

  • t_max (float) – maximum time to plot in seconds

  • db_min (float) – minimum dB to plot

  • db_max (float) – maximum dB to plot

  • channels_list (str) – list of channels to plot (can be a strin of comma-separated values or a list of integers)

elecphys.visualization.plot_dft_from_npz(npz_folder_path: str, output_plot_file: str, f_min: int, f_max: int, plot_type: str, channels_list: str | list = None, conv_window_size: float = None) → None

Plots DFT from NPZ file (DFT must be saved as NPZ file)

Parameters:

  • npz_folder_path (str) – path to input npz folder

  • output_plot_file (str) – path to save figure. If None, will show figure instead of saving it

  • f_min (int) – minimum frequency to plot in Hz

  • f_max (int) – maximum frequency to plot in Hz

  • plot_type (str) – whether to plot all channels or average of channels

  • channels_list (str) – list of channels to plot (can be a strin of comma-separated values or a list of integers)

  • conv_window_size (float) – size of convolution window to smooth the DFT

elecphys.visualization.plot_filter_freq_response(filter_args: dict, figure_save_path: str = None) → None

Plots filter frequency response

Parameters:

  • filter_args (dict) – dictionary containing filter parameters

  • figure_save_path (str) – path to save figure. If None or not specified, will show figure instead of saving it

elecphys.visualization.plot_filter_freq_response_from_json(filter_freq_response_json_file_path: str, figure_save_path: str = None) → None

Plots filter frequency response from JSON file

Parameters:

  • filter_freq_response_json_file_path (str) – path to filter frequency response JSON file

  • figure_save_path (str) – path to save figure. If None or not specified, will show figure instead of saving it

elecphys.visualization.plot_mvl_form_array(MI_mat: ndarray, freqs_phase: ndarray, freqs_amp: ndarray, clim: list = None, figure_save_path: str = None) → None

Plots MVL from 2D array

Parameters:

  • MI_mat (np.ndarray) – MVL array

  • freqs_phase (np.ndarray) – phase frequencies (Hz)

  • freqs_amp (np.ndarray) – amplitude frequencies (Hz)

  • clim (list) – colorbar limits. if None or not specified, will use default limits

  • figure_save_path (str) – path to save figure. If None or not specified, will show figure instead of saving it

elecphys.visualization.plot_mvl_from_npz(npz_file_path: str, figure_save_path: str = None) → None

Plots MVL from NPZ file

Parameters:

  • npz_file_path (str) – path to npz file

  • figure_save_path (str) – path to save figure. If None or not specified, will show figure instead of saving it

elecphys.visualization.plot_power_over_time_from_array(power: ndarray, t: ndarray, channels_map: list, plot_type: str = 'avg', output_plot_file: str = None) → None

Plots power over time from 3D array

Parameters:

  • power (np.ndarray) – A 2D array containing power values. Shape: (num_channels, num_timepoints)

  • t (np.ndarray) – time array (seconds)

  • plot_type (str) – whether to plot all channels or average of channels. Must be either ‘all’ or ‘avg’

elecphys.visualization.plot_signals_from_npz(npz_folder_path: str, output_plot_file: str, t_min: float, t_max: float, channels_list: str | list = None, normalize: bool = False, scale_bar: bool = True, _rereference_args: dict = None) → None

Plots signals from NPZ file

Parameters:

  • npz_folder_path (str) – path to input npz folder

  • output_plot_file (str) – path to save figure. If None, will show figure instead of saving it

  • t_min (float) – minimum time to plot in seconds

  • t_max (float) – maximum time to plot in seconds

  • channels_list (str) – list of channels to plot (can be a strin of comma-separated values or a list of integers)

  • normalize (bool) – whether to normalize the signal

  • scale_bar (bool) – whether to plot a scale bar

  • _rereference_args (dict) – dictionary containing rereferencing parameters. If None, no rereferencing will be applied

elecphys.visualization.plot_stft_from_array(Zxx: ndarray, t: ndarray, f: ndarray, f_min: int, f_max: int, t_min: float, t_max: float, db_min: float, db_max: float, output_plot_file: str = None) → None

Plots STFT from 2D array

Parameters:

  • Zxx (np.ndarray) – STFT array

  • t (np.ndarray) – time array

  • f (np.ndarray) – frequency array

  • f_min (int) – minimum frequency to plot in Hz

  • f_max (int) – maximum frequency to plot in Hz

  • t_min (float) – minimum time to plot in seconds

  • t_max (float) – maximum time to plot in seconds

  • db_min (float) – minimum dB to plot

  • db_max (float) – maximum dB to plot

  • output_plot_file (str) – path to save figure. If None, will show figure instead of saving it

elecphys.visualization.plot_stft_from_npz(input_npz_file: str, output_plot_file: str, f_min: int, f_max: int, t_min: float, t_max: float, db_min: float, db_max: float) → None

Plots STFT from NPZ file (STFT must be saved as NPZ file)

Parameters:

  • input_npz_file (str) – path to input npz file

  • output_plot_file (str) – path to save figure. If None, will show figure instead of saving it

  • f_min (int) – minimum frequency to plot in Hz

  • f_max (int) – maximum frequency to plot in Hz

  • t_min (float) – minimum time to plot in seconds

  • t_max (float) – maximum time to plot in seconds

  • db_min (float) – minimum dB to plot

  • db_max (float) – maximum dB to plot

Module contents