Command Line Interface usage¶

You can invoke the primary workflow of phys2cvr from the command line.

The `phys2cvr` command¶

%(prog)s, a tool to compute Cerebrovascular Reactivity maps and their lags. %(prog)s is compatible with different designs and techniques to estimate CVR maps. It can also be used to generate regressors to run the estimation with other software. Version 0.28.4

usage: phys2cvr -i FNAME_FUNC [-o OUTDIR] [-m FNAME_MASK] [-r FNAME_ROI]
                [-tr TR] [-co2 FNAME_CO2] [-pk FNAME_PIDX] [-fr FREQ]
                [-tlen TRIAL_LEN] [-ntrial N_TRIALS] [-absxcorr] [-noxcorr]
                [-af] [-hf HIGHCUT] [-lf LOWCUT] [-bo BUTTER_ORDER]
                [-skip_reg] [-skip_lagreg] [-skip_endtidal]
                [-hrf | -rrf | -crf | -norf | -rfpath RESPONSE_FUNCTION]
                [--r2full | --r2partial | --r2intercept | --r2adjfull | --r2adjpartial | --r2adjintercept]
                [-ldeg L_DEGREE] [-dmat [DENOISE_MATRIX_FILE ...]]
                [-omat [ORTHOGONALISED_MATRIX_FILE ...]]
                [-emat [EXTRA_MATRIX_FILE ...]] [-scale SCALE_FACTOR]
                [-lm LAG_MAX] [-ls LAG_STEP] [--legacy] [-lmap LAG_MAP]
                [-rdir REGR_DIR]
                [--brightspin | --brightspin-clinical | --baltimore | --baltimore-lag]
                [-debug] [-quiet] [-h] [-v]

Required Argument¶

-i, --input-func: Complete path (absolute or relative) and name of the file containing fMRI signal. This file can be a nifti-like file, a gifti file, a .mat file, or a txt-like file. Any filetype supported by nibabel should be supported.

Optional Argument for output¶

-o, --output-directory: Complete path (absolute or relative) and name of the desired output directory. If it does not exist, it will be created. If it is not specified, a folder named “phys2cvr” will be created in the folder containing the functional file.

Optional Arguments for fMRI timeseries¶

-m, --input-mask: Complete path (absolute or relative) and name of the file containing a brain mask (nifti file). Only the voxels in this mask will be considered by phys2cvr. Use this option to specify a GM mask or overwrite a full brain mask. If the functional file is specified and this option is not used, or the mask cannot be loaded, the program will create a mask using any voxel of the functional file constantly different from zero.
-r, --input-roi: Complete path (absolute or relative) and name of the nifti file containing a subset of voxels to treat as a region of interest (ROI). The average functional signal of the ROI will be used to run the cross correlation with the physiological regressor. The median lag value in the ROI will be used to correct the final lag map. If the functional file is specified and this option is not used, or the ROI cannot be loaded, the program will either use a specified mask (see –input-mask) or create a mask using any voxel of the functional file constantly different from zero.
-tr, --repetition-time: TR of functional data. Required if the latter is not passed as a nifti file. Use this option to overwrite the frequency of a nifti file.

Optional Arguments for physiological timeseries (regressor of interest)¶

-co2, --input-co2

Complete path (absolute or relative) and name of the file containing CO2 signal (or equivalent physiological trace to compute the regressor). This file can be a 1D txt-like file, a .mat file, or a .phys file from peakdet.: If nothing is specified, the average timeseries of the mask will be used as regressor.

-pk, --input-peaks

Complete path (absolute or relative) and name of the file containing the peak of the physiological trace. Required if the physiological trace file is not a .phys file. Use this option to overwrite the peaks specified in the .phys file.

-fr, --frequency

Frequency of the physiological trace. Required if the latter is not passed as a .phys file. Use this option to overwrite the frequency of a .phys file.

Optional Arguments for the cross correlation (bulk shift estimation step)¶

-tlen, --trial-length

Total duration of a single trial of the task in seconds (useful for block designs). Specify this with the number of trials to run a double cross-correlation between functional signal and physiological regressor to improve the detection of the bulk shift.

-ntrial, --trial-number

Number of trials in the task (useful for block designs). Specify this with the duration of trials to run a double cross-correlation between functional signal and physiological regressor to improve the detection of the bulk shift.

-absxcorr, --absolute-cross-corr

Allow cross correlation to consider both positive and negative values as possible maximum, i.e. to consider the maximum of the absolute of the cross correlation.

Default: False

-noxcorr, --skip-cross-corr

Skip cross correlation step.

Default: False

Optional Arguments for temporal filter¶

-af, --apply-filter

Apply a filter to the functional data before estimating the bulk shift. The filter will not be applied on the data before the GLM computation. If you want that, consider applying it before running phys2cvr (or running it a second time).

Default: False

-hf, --highcut-frequency

Higher frequency to use in signal filtering. The filter will be applied only to the functional data to estimate the bulk shift. This option is suggested when only using a functional file.

-lf, --lowcut-frequency

Lower frequency to use in signal filtering. The filter will be applied only to the functional data to estimate the bulk shift. This option is suggested when only using a functional file.

-bo, --butter-order

Order of Butterworth filter. Default is 9.

Default: 9

Optional Arguments to modify the workflow¶

-skip_reg, --skip-regression

Skip running physiological regression(s) internally. This will make phys2cvr generate the desired physiological regressors and quit, assuming that the regression itself will be carried out with other software (e.g. AFNI, FSL, …).

Default: True

-skip_lagreg, --skip-lagged-regression

Skip estimating the lagged regressors, estimating only the bulk shifted one. Skip running the lagged regression if the regression step is run.

Default: True

-skip_endtidal, --skip-endtidal-interpolation

Skip the end-tidal interpolation of the physiological trace.By default, phys2cvr linearly interpolate the peaks of the physiological trace. Use this option if providing a physiological trace that does not need interpolation or a previously computed trace.

Default: True

Optional Arguments to select a response function to convolve the signal of interest (e.g. PetCO2 trace)¶

-hrf, --hrf

Use an HRF to convolve the PetCO2 trace. This is the default behaviour.

Default: 'hrf'

-rrf, --rrf

Use a RRF (Respiratory Response Function) to convolve the signal of interest. Requires phys2denoise to be installed.

Default: 'hrf'

-crf, --crf

Use a CRF (Cardiac Response Function) to convolve the signal of interest. Requires phys2denoise to be installed.

Default: 'hrf'

-norf, --no-response-function

Do NOT convolve the signal of interest with a response function.

Default: 'hrf'

-rfpath, --response-function-path

Use a pre-generated response function from a file (which full path has to be given after the flag.

Default: 'hrf'

Optional Arguments to select R^2 model for regression step¶

--r2full: Use full R^2 of the model, , i.e. compare versus baseline 0
--r2partial: Use partial R^2 of the regressor of interest, i.e. compare versus any other regressor
--r2intercept: Use full R^2 of the model but the intercept, i.e. compare versus baseline intercept (Legendre polynomial order 0, a.k.a. average signal)
--r2adjfull: Same as “full”, but adjusted
--r2adjpartial: Same as “partial”, but adjusted
--r2adjintercept: Same as “intercept”, but adjusted

Optional Arguments for the regression step¶

-ldeg, --legendre-degree

Maximum legendre degree to add to the regression matrix as nuisance. Default is 0, to account for the degree of freedom lost in computing the SPC.

Default: 0

-dmat, --denoise-matrix

Complete path (absolute or relative) and filename of denoising matrices to add to the regression model. This option can be specified multiple times to add multiple denoising matrices, but multiple denoising matrices can be specified one after the other, separated by a space.

-omat, --orthogonalised-matrix

Complete path (absolute or relative) and filename of denoising matrices to add to the regression model, but only after they have been orthogonalised w.r.t. denoising matrices and extra matrices (-dmat and -emat flags). This option can be specified multiple times to add multiple matrices, but multiple matrices can be specified one after the other, separated by a space.

-emat, --extra-orthogonal-matrix

Complete path (absolute or relative) and filename of matrices to use to orthogonalise other denoising matrices with. These matrices will not be added as regressors in the regression, but only used for orthogonalisation purposes. This option can be specified multiple times to add multiple matrices, but multiple matrices can be specified one after the other, separated by a space.

-scale, --scale-factor

Scale factor by which the beta maps will be divided to create the CVR map output. Since BIDS currently does not support mmHg as unit, if using CO2 traces check their unit of measure and their scaling factor to transform Volts into mmHg. Use this option for other standardisations too.

Optional Arguments for the lagged regression¶

-lm, --lag-max

Maximum lag to consider during lag regression in seconds. The same lag will be considered in both directions. Despite the code being python, the upper limit is included in the computation. E.g. -lm 9 -ls .3 means [-9, +9] (61 regressors).

-ls, --lag-step

Lag step to consider during lagged regression in seconds. Default is 0.3 seconds.

--legacy

Use pythonic ranges, i.e. the upper limit is excluded from the computation. E.g. -lm 9 -ls .3 means [-9, +8.7] or [-9, +9) (60 regressors).

Default: False

Optional Arguments to re-run a lagged regression (also useful to use a lag estimation on a different functional timeseries)¶

-lmap, --lag-map: Complete path (absolute or relative) and name of a previously computed lag map to use in lagged regression.
-rdir, --regr-dir: Complete path (absolute or relative) and name of previously computed lagged regressors to use in a new lagged regression.

Optional Arguments to set up specific workflows¶

--brightspin: Estimate CVR using a specific set of L-GLM parameters, as used in: S. Moia, et al., “ICA-based denoising strategies in breath-hold induced cerebrovascular reactivity mapping with multi echo BOLD fMRI” (2021), NeuroImage. Same as setting –lag-max 9 –lag-step 0.3 –legacy –r2full
--brightspin-clinical: Like “brightspin”, but use a larger lag range. Same as setting –lag-max 20 –lag-step 0.3 –r2full
--baltimore: Estimate CVR using the average timeseries in the 0.02-0.04 frequency spectrum, as used in: P. Liu, et al., “Cerebrovascular reactivity mapping without gas challenges” (2017), NeuroImage. Same as setting –apply-filter -hf 0.04 -lf 0.02 -skip_conv -skip_lagreg -co2 ‘’
--baltimore-lag: Like “baltimore”, but use a L-GLM instead. Same as setting –apply-filter -hf 0.04 -lf 0.02 -skip_conv -co2 ‘’

Other Optional Arguments¶

-debug, --debug

Print debugging info to log file and export extra files for debugging. Default is not to do so.

Default: False

-quiet, --quiet

Only print “warnings” level messages to log file. Default is to print “info” level and above.

Default: False

-v, --version

show program’s version number and exit

Command Line Interface usage¶

The phys2cvr command¶

Required Argument¶

Optional Argument for output¶

Optional Arguments for fMRI timeseries¶

Optional Arguments for physiological timeseries (regressor of interest)¶

Optional Arguments for the cross correlation (bulk shift estimation step)¶

Optional Arguments for temporal filter¶

Optional Arguments to modify the workflow¶

Optional Arguments to select a response function to convolve the signal of interest (e.g. PetCO2 trace)¶

Optional Arguments to select R^2 model for regression step¶

Optional Arguments for the regression step¶

Optional Arguments for the lagged regression¶

Optional Arguments to re-run a lagged regression (also useful to use a lag estimation on a different functional timeseries)¶

Optional Arguments to set up specific workflows¶

Other Optional Arguments¶

The `phys2cvr` command¶