phys2cvr.workflows.phys2cvr

phys2cvr.workflows.phys2cvr(fname_func, fname_co2=None, fname_pidx=None, fname_roi=None, fname_mask=None, outdir=None, freq=None, tr=None, trial_len=None, n_trials=None, abs_xcorr=False, skip_xcorr=False, highcut=0.04, lowcut=0.02, butter_order=9, apply_filter=False, run_regression=False, lagged_regression=True, r2model='full', lag_max=None, lag_step=None, legacy=False, l_degree=0, denoise_matrix_file=None, orthogonalised_matrix_file=None, extra_matrix_file=None, scale_factor=None, lag_map=None, regr_dir=None, comp_endtidal=True, response_function='hrf', quiet=False, debug=False)

Run main workflow of phys2cvr.

Parameters:

fname_funcstr or path

Filename of the functional input (nifti or txt)

fname_co2str or path, optional

Filename of the CO2 (physiological regressor) timeseries. Can be either peakdet’s output or a txt file. If not declared, phys2cvr will consider the average temporal value from the input. Default: empty

fname_pidxstr or path, optional

Filename of the CO2 (physiological regressor) timeseries’ PEAKS. Required if CO2 file is a txt AND the convolution step is not skipped. If not declared AND the convolution step is not skipped, raises an exception. Default: empty

fname_roistr or path, optional

Filename of the roi in a nifti volume. If declared, phys2cvr will use these voxels . If not, phys2cvr will use a mask, either the declared one or estimated from the functional input. Ignored if input is a txt file. Default: empty

fname_maskstr or path, optional

Filename of the mask in a nifti volume. If declared, phys2cvr will run only on these voxels. If not, phys2cvr will estimate a mask from the functional input. Ignored if input is a txt file. Default: empty

outdirstr or path, optional

Output directory Default: the directory where fname_func is.

freqstr, int, or float, optional

Sample frequency of the CO2 regressor. Required if CO2 input is TXT file. If declared with peakdet file, it will overwrite the file frequency.

trstr, int, or float, optional

TR of the timeseries. Required if input is TXT file. If declared with nifti file, it will overwrite the file TR.

trial_lenstr or int, optional

Length of each single trial for tasks that have more than one (E.g. BreathHold, CO2 challenges, …) Used to improve cross correlation estimation. Default: None

n_trialsstr or int, optional

Number of trials in the task. Default: None

abs_xcorrbool, optional

If True, the cross correlation will consider max(abs(xcorr)). If False, the cross correlation will consider max(xcorr). Default: False

skip_xcorrbool, optional

If True, skip the cross correlation step. Default: False

highcutstr, int, or float, optional

High frequency limit for filter. Required if applying a filter. Default: 0.02

lowcutstr, int, or float, optional

Low frequency limit for filter. Required if applying a filter. Default: 0.04

butter_orderint, optional

Butterworth filter order. Default: 9

apply_filterbool, optional

Apply a Butterworth filter to the functional input. Default: False

run_regressionbool, optional

Also run the regression step within phys2cvr. By default, phys2cvr will only estimate the regressor(s) of interest. Default: False

lagged_regressionbool, optional

Estimates regressors to run a lagged regression approach. If run_regression is True, also run the lagged regression. Can be turned off. Default: True

r2model{full, partial, intercept, adj_full, adj_partial, adj_intercept), optional

R^2 model the regression should return (and hence used for lag selection). Potentially invariant if no orthogonalisation is introduced, will change results with orthogonalisations. See stats.ols help for more details. Default: full

lag_maxint or float, optional

Limits (both positive and negative) of the temporal area to explore, expressed in seconds (e.g. ±9 seconds). Caution: this is not a pythonic range, but a real range, i.e. the upper limit is included (e.g. [-9, +9]). Default: None

lag_stepint or float, optional

Step of the lag to take into account in seconds. Default: None

legacybool, optional

If True, use pythonic ranges when creating the regressors, i.e. exclude the upper range (e.g. [-9, +9) ). Default: False

l_degreeint, optional

Only used if performing the regression step. Highest order of the Legendre polynomial to add to the denoising matrix. phys2cvr will add all polynomials up to the specified order (e.g. if user specifies 3, orders 0, 1, 2, and 3 will be added). Default is 0, which will model only the mean of the timeseries.

denoise_matrix_fileNone, list of str(s) or path(s), optional

Add one or multiple denoising matrices to the regression model. Ignored if not performing the regression step. Default is None.

orthogonalised_matrix_fileNone, list of str(s) or path(s), optional

Add one or multiple denoising matrices to the regression model, AFTER orthogonalising them w.r.t. the task, the denoise matrix, and the extra matrix. Ignored if not performing the regression step. Default is None.

extra_matrix_fileNone, list of str(s) or path(s), optional

Add one or multiple extra matrices to use in the orthogonalisation step. These matrices will not be added to the final regression model. Ignored if not performing the regression step. Default is None.

scale_factorstr, int, or float, optional

A scale factor to apply to the CVR map before exporting it. Useful when using inputs recorded/stored in Volts that have a meaningful unit of measurement otherwise, e.g. (CO2 traces in mmHg). V->mmHg: CO2[mmHg] = (Patm-Pvap)[mmHg] * 10*CO2[V]/100[V] Default: None

lag_mapstr or path, optional

Filename of a lag map to get lags from. Ignored if not running a lagged-GLM regression. Default: None

regr_dirstr, optional

Directory containing pre-generated lagged regressors, useful to (re-)run a GLM analysis. Default: None

comp_endtidalbool, optional

Compute the end-tidal interpolation of the CO2 signal.

response_function{hrf, rrf, crf, None}, None, str, path, or 1D array_like, optional

Name of the response function to be used in the convolution of the regressor of interest. Default is hrf. If None, skips the convolution step. If file, loads it. For rrf and crf, phys2denoise must be installed (see extra installs). See signal.compute_petco2hrf for details.

quietbool, optional

Return to screen only warnings and errors. Default: False

debugbool, optional

Return to screen more output. Default: False

Raises:

ValueError

• If the order of Legendre Polynomials is < 0.

• If a wrong R^2 model was specified.

• If functional nifti file is not at least 4D.

• If mask was specified but it has different dimensions than the

  functional nifti file.

• If ROI was specified but it has different dimensions than the

  functional nifti file.

• If a lag map was specified but it has different dimensions than the

  functional nifti file.

• If a lag map was specified, lag_step was not, and the lag map seems

  to have different lag_steps inside.

NotImplementedError

• If a file type is not supported yet.

NameError

• If functional timeseries is lacking TR and the latter was not specified.

• If physiological file is a txt file and no peaks were provided.

• If physiological file is lacking frequency and the latter was not specified.