API

Input data

CMRR format

niphlem.input_data.load_cmrr_info(filename)

Load information log files from CMRR sequences.

Parameters

filename (str, pathlike) – Path to Information Log file.

Returns

• traces (ndarray) – Time ticks of the scanner.

• meta_info (dict) – Dictionary with meta information about the info log file.

niphlem.input_data.load_cmrr_data(filename, sig_type, info_dict, sync_scan=True)

Load data log files from CMRR sequences.

Parameters

• filename (str, pathlike) – Path to recording log file..

• sig_type (str) – Type of signal for use in dictionary

• info_dict (dict) – Dictionary with the meta information of the Info log file. It needs to be compute before by using the function load_cmrr_info.

• sync_scan (bool, optional) – Whether we want to resample the signal to be synchronized with the scanner times. The default is True.

Returns

• signal (ndarray) – The recording signal, where the number of columns corresponds to the number of channels (ECG: 4, PULS: 1, RESP: 1) and the rows to observations.

• info_dict (dict) – Updated meta info of the physiological recording.

BIDS format

niphlem.input_data.load_bids_physio(data_file, json_file, resample_freq=None, sync_scan=True)

Load physiological data in BIDS format.

Parameters

• data_file (str, pathlike) – Path to recording bids physio file.

• json_file (str, pathlike) – Path to the sidecar json file of the input bids physio.

• resample_freq (float, optional) – Frequency to resample the data. The default is None.

• sync_scan (bool, optional) – Whether we want the signal to be synchronized with the scanner times. The default is True.

Returns

• signal (ndarray) – The signal, where each columns corresponds to a particular recording, whose names can wh be identfied in the meta_info dictionary returned, and the rows to observations.

• meta_info (dict) – Meta information that at least contains the sampling frequency, the start time of the signals, and the name of each signal column.

Models

Retroicor

class niphlem.models.RetroicorPhysio(*, physio_rate, t_r, delta, peak_rise=0.5, order=1, transform='demean', filtering=None, high_pass=None, low_pass=None, columns=None, peak_correct=True, n_jobs=1)

Physiological regressors using Retroicor.

Parameters

• physio_rate (float) – Sampling rate for the recording in Hz. This is needed for filtering to define the nyquist frequency.

• t_r (float) – Repetition time for the scanner (the usual T_R) in secs.

• delta (float) – minimum separation (in physio recording units) between events in signal to be considered peaks

• peak_rise (float) – relative height with respect to the 20th tallest events in signal to consider events as peak.

• order (int or array-like of shape (n_orders,)) – Fourier expansion for phases. If int, the fourier expansion is performed to that order, starting from 1. If an array is provided, each element will multiply the phases.

• transform ({"demean", "zscore", "abs"}, optional) – Transform data before filtering. The default is “demean”.

• high_pass (float, optional) – High-pass filtering frequency (in Hz). The default is None.

• low_pass (float, optional) – Low-pass filtering frequency (in Hz). The default is None.

• columns (List or array of n_channels elements, "mean" or None, optional) – It describes how to handle input signal channels. If a list, it will weight each channel and take the dot product. If “mean”, the average across the channels. If None, it will consider each channel separately. The default is None.

• peak_correct (bool, optional) – Whether to apply an automatic Grubbs’ test for peak outlier correction. The default is True.

• n_jobs (int, optional) – Number of jobs to consider in parallel. The default is 1.

compute_regressors(signal, time_scan, time_physio=None)

Compute regressors.

It basically takes care of all the preprocessing before concentrating on the specific type of physiological regressors

Parameters

• signal (array -like of shape (n_physio_samples, n_channels)) – Signal, where each column corresponds to a recording.

• time_scan (array -like of shape (n_scan_samples, )) – Time ticks (in secs) at the scanner resolution.

• time_physio (array -like of shape (n_physio_samples, )) – Time ticks (in secs) at the physio recording resolution. The default is None. In this default case, the time of the physiological recording is computed multiplying the number of points with the sampling period.

Return type

array-like with the physiological regressors

get_params(deep=True)

Get parameters for this estimator.

Parameters

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns

params – Parameter names mapped to their values.

Return type

dict

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters

**params (dict) – Estimator parameters.

Returns

self – Estimator instance.

Return type

estimator instance

Variation

class niphlem.models.RVPhysio(*, physio_rate, t_r, time_window=6.0, transform='demean', high_pass=None, low_pass=None, columns=None, n_jobs=1)

Physiological regressors for variations in breathing rate/volume.

Parameters

• physio_rate (float) – Sampling rate for the recording in Hz. This is needed for filtering to define the nyquist frequency.

• t_r (float) – Repetition time for the scanner (the usual T_R) in secs.

• time_window (float) – Time window (in secs) around the T_R from which computing variations (standard deviation of signal). The default is 6 secs.

• transform ({"demean", "zscore", "abs"}, optional) – Transform data before filtering. The default is “demean”.

• high_pass (float, optional) – High-pass filtering frequency (in Hz). The default is None.

• low_pass (float, optional) – Low-pass filtering frequency (in Hz). The default is None.

• columns (List or array of n_channels elements, "mean" or None, optional) – It describes how to handle input signal channels. If a list, it will weight each channel and take the dot product. If “mean”, the average across the channels. If None, it will consider each channel separately. The default is None.

• n_jobs (int, optional) – Number of jobs to consider in parallel. The default is 1.

compute_regressors(signal, time_scan, time_physio=None)

Compute regressors.

It basically takes care of all the preprocessing before concentrating on the specific type of physiological regressors

Parameters

• signal (array -like of shape (n_physio_samples, n_channels)) – Signal, where each column corresponds to a recording.

• time_scan (array -like of shape (n_scan_samples, )) – Time ticks (in secs) at the scanner resolution.

• time_physio (array -like of shape (n_physio_samples, )) – Time ticks (in secs) at the physio recording resolution. The default is None. In this default case, the time of the physiological recording is computed multiplying the number of points with the sampling period.

Return type

array-like with the physiological regressors

get_params(deep=True)

Get parameters for this estimator.

Parameters

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns

params – Parameter names mapped to their values.

Return type

dict

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters

**params (dict) – Estimator parameters.

Returns

self – Estimator instance.

Return type

estimator instance

class niphlem.models.HVPhysio(*, physio_rate, t_r, delta, peak_rise=0.5, time_window=6.0, transform='demean', high_pass=None, low_pass=None, columns=None, peak_correct=True, n_jobs=1)

Physiological regressors for variations in heart rate.

Parameters

• physio_rate (float) – Sampling rate for the recording in Hz. This is needed for filtering to define the nyquist frequency.

• t_r (float) – Repetition time for the scanner (the usual T_R) in secs.

• delta (float) – minimum separation (in physio recording units) between events in signal to be considered peaks

• peak_rise (float) – relative height with respect to the 20th tallest events in signal to consider events as peak.

• time_window (float) – Time window (in secs) around the T_R from which computing variations (time differences between signal events ). The default is 6 secs.

• transform ({"demean", "zscore", "abs"}, optional) – Transform data before filtering. The default is “demean”.

• high_pass (float, optional) – High-pass filtering frequency (in Hz). The default is None.

• low_pass (float, optional) – Low-pass filtering frequency (in Hz). The default is None.

• columns (List or array of n_channels elements, "mean" or None, optional) – It describes how to handle input signal channels. If a list, it will weight each channel and take the dot product. If “mean”, the average across the channels. If None, it will consider each channel separately. The default is None.

• peak_correct (bool, optional) – Whether to apply an automatic Grubbs’ test for peak outlier correction. The default is True.

• n_jobs (int, optional) – Number of jobs to consider in parallel. The default is 1.

compute_regressors(signal, time_scan, time_physio=None)

Compute regressors.

It basically takes care of all the preprocessing before concentrating on the specific type of physiological regressors

Parameters

• signal (array -like of shape (n_physio_samples, n_channels)) – Signal, where each column corresponds to a recording.

• time_scan (array -like of shape (n_scan_samples, )) – Time ticks (in secs) at the scanner resolution.

• time_physio (array -like of shape (n_physio_samples, )) – Time ticks (in secs) at the physio recording resolution. The default is None. In this default case, the time of the physiological recording is computed multiplying the number of points with the sampling period.

Return type

array-like with the physiological regressors

get_params(deep=True)

Get parameters for this estimator.

Parameters

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns

params – Parameter names mapped to their values.

Return type

dict

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters

**params (dict) – Estimator parameters.

Returns

self – Estimator instance.

Return type

estimator instance

Report

niphlem.report.make_ecg_report(ecg_signal, *, fs, delta, peak_rise=0.75, ground=None, high_pass=0.6, low_pass=5.0, outpath=None)

Generate QC report for ECG data. :param ecg_signal: or (n_physio_samples, n_channels).

ECG Signal, where each column corresponds to a recording.

Parameters

• fs (float) – Sampling frequency of ECG recording.

• delta (float) – minimum separation (in physio recording units) between events in signal to be considered peaks

• peak_rise (float) – relative height with respect to the 20th tallest events in signal to consider events as peak. The default is 0.75.

• ground (integer, optional) – Column in the input signal to be considered as a ground channel. This signal will be then substracted from the other channels. The default is None.

• high_pass (float, optional) – High-pass filtering frequency (in Hz). Only if filtering option is not None. The default is 0.6.

• low_pass (float, optional) – Low-pass filtering frequency (in Hz). Only if filtering option is not None. The default is 5.0.

• outpath (string, optional) – If provided, Path where report the HTML report, averaged filtered signal and corrected peaks will be saved. The default is None.

Returns

• report (html file) – HTML report.

• output_dict (dict) – Dictionary with the filtered signal and (corrected) peak locations.

niphlem.report.make_pulseox_report(pulse_signal, *, fs, delta_low, delta_high, peak_rise_low=0.5, peak_rise_high=0.75, resp_high_pass=0.1, resp_low_pass=0.5, hr_high_pass=0.6, hr_low_pass=5, outpath=None)

Generate QC report for pulse-ox data. :param pulse_signal: or (n_physio_samples, n_channels).

Pulse-oximetry belt signal.

Parameters

• fs (float) – Sampling frequency of pulse-oximetry recording.

• delta_low (float) – minimum separation (in physio recording units) between events in signal to be considered peaks

• delta_high (float) – minimum separation (in physio recording units) between events in signal to be considered peaks

• peak_rise_low (float) – relative height with respect to the 20th tallest events in signal to consider events as peak. The default is 0.5 and 0.75 respectively.

• peak_rise_high (float) – relative height with respect to the 20th tallest events in signal to consider events as peak. The default is 0.5 and 0.75 respectively.

• resp_high_pass (float, optional) – High-pass filtering frequency (in Hz). Only if filtering option is not None. The default is 0.1 and 0.6 respectively.

• hr_high_pass (float, optional) – High-pass filtering frequency (in Hz). Only if filtering option is not None. The default is 0.1 and 0.6 respectively.

• resp_low_pass (float, optional) – Low-pass filtering frequency (in Hz). Only if filtering option is not None. The default is 0.5 and 5 respectively.

• hr_low_pass (float, optional) – Low-pass filtering frequency (in Hz). Only if filtering option is not None. The default is 0.5 and 5 respectively.

• outpath (string, optional) – If provided, Path where report the HTML report, averaged filtered signal and corrected peaks will be saved. The default is None.

Returns

• report (html file) – HTML report.

• output_dict (dict) – Dictionary with the (high and low) filtered signals and (corrected) peak locations.

niphlem.report.make_resp_report(resp_signal, *, fs, delta, peak_rise=0.5, high_pass=0.1, low_pass=0.5, outpath=None)

Generate QC report for respiration data. :param resp_signal: or (n_physio_samples, n_channels).

Pneumatic belt signal.

Parameters

• fs (float) – Sampling frequency of pneumatic belt recording.

• delta (float) – minimum separation (in physio recording units) between events in signal to be considered peaks

• peak_rise (float) – relative height with respect to the 20th tallest events in signal to consider events as peak. The default is 0.5.

• high_pass (float, optional) – High-pass filtering frequency (in Hz). Only if filtering option is not None. The default is 0.1.

• low_pass (float, optional) – Low-pass filtering frequency (in Hz). Only if filtering option is not None. The default is 0.5.

• outpath (string, optional) – If provided, Path where report the HTML report, averaged filtered signal and corrected peaks will be saved. The default is None.

Returns

• report (html file) – HTML report.

• output_dict (dict) – Dictionary with the filtered signal and (corrected) peak locations.