The recommended (and easiest) way to run PNM is via the Pnm GUI.
This GUI allows you to specify the following inputs:
- text file containing the sampled physiological recordings (each line containing numbers corresponding to one point in time)
- FMRI timeseries data (a 4D image in NIFTI format)
- information about the text file (which columns are cardiac/respiratory/triggers)
- information about the physiological recordings (e.g., sampling rate)
- information about the FMRI scans (e.g., slice ordering)
It also allows the user to specify the desired outputs:
- order of cardiac EVs (this is the number of pairs of sinusoidal frequencies to use - e.g. a value of 2 would indicate that the base frequency and the first harmonic, twice the base frequency, should be used - which would generate 4 regressors)
- order of respiratory EVs
- order of interaction EVs (see below)
optional RVT, HeartRate and CSF regressors
Scanner triggers must be supplied, as experience has shown that relative timings between the MR scans and physiological recordings is not sufficiently accurate/reliable without this. The scanner triggers need to be once per volume (or once per slice). The format for the trigger input is just the same as the other traces, and no special values need to be used: it just requires a strong rising edge per trigger point, returning to a consistent baseline level (e.g. baseline of zero going up to a value of one at each trigger and then down again after a small number of samples, anywhere from one sample to 50% of the interval can be spent at the high value).
Cardiac input information can either be provided as a full trace or as "Pulse Ox Triggers" (as detected from any external software). Scanner triggers and cardiac triggers are not interchangeable as they contain different information.
The interaction EVs combine cardiac and respiratory frequencies. For instance, if the cardiac frequency is fc and the respiratory frequency is fr then the interaction terms have frequencies nc*fc +/- nr*fr where the permitted values of nc and nr are determined by the order of interactions entered in the GUI. For example, cardiac order 3 and respiratory order 2 would generate frequencies: 1*fc +/- 1*fr ; 2*fc +/- 1*fr ; 3*fc +/- 1*fr ; 1*fc +/- 2*fr ;2*fc +/- 2*fr ; 3*fc +/- 2*fr. For each frequency a pair of regressors (sin and cos) are generated. So the number of interaction EVs (regressors) can grow quite large.
Note that in practice the frequencies here are changing throughout the scan (as heart rate and breathing rate vary) so they should be thought of more like instantaneous frequencies.
Slice Timing Information
It is necessary to supply information about which direction is the through-slice direction (according to the voxel axes: x,y,z) and then either the slice ordering (sequential or interleaved; up or down) or a manually specified slicetiming file. If the interleaved option is used then the timing uses the Siemens conventions for the order, which depends on whether an even or odd number of slices are acquired. For users on a non-Siemens system we recommend using a manually specified slice timing file when working with interleaved data.
The manually specified slicetiming file needs to be a text file that specifies the timing (in seconds) of every slice relative to the start of the volume acquisition (t=0). The file must have one number per slice and be arranged in one line, separated by spaces, and each number is the timing value for that slice (e.g. third number gives the timing of the third slice, where numbering of slices is consistent with the NIFTI voxel coordinate; i.e. the way that FSLView/FSLeyes shows them).
As an advanced option, it is also possible to specify separate times for each volume by having multiple lines (as many lines as number of volumes), where the values in each line represent the timings for one volume, across all slices, which allows for a variable slice timing per volume.
PNM stage 1
Set up the GUI and click Go when ready.
Unfortunately, physiological recordings, and the detection of the peaks in them, tends not to be perfect. Therefore we have a simple and quick method for manually checking the recordings and peak detections, and noting down errors to be corrected by the following stage. This is all done within a browser that shows the waveforms and the appropriate peaks.
The output directory will be created and when stage 1 has finished running there will be a file ending with _pnm1.html.
- Open this file in the firefox web browser
If you do not have the firefox browser (or cannot install it) then you can either skip this step (hoping for the best) or use some other software to view the outputs (e.g. matlab/octave) and note down the times (in seconds) of erroneous/extra peaks or missing peaks. You can then rerun popp (see the log file to get the previous options) and add the options --respadd,--respdel,--cardadd,--carddel for respiratory/cardiac additions/deletions.
Note that respiratory peaks are only shown (and only detected) in the case where the RVT output has been requested. If that is not the case, the respiratory trace is converted to a phase using the RETROICOR methodology, without requiring peak detection. Therefore, there is no need to manually check and correct the respiratory peaks unless RVT is requested. Currently the respiratory checkbox is still available on the webpage even when RVT is not selected - this will be changed in future.
PNM stage 2
If you have done the manual check/edit in the browser then follow the instructions given in the browser window (which are tailored to your particular directory and data).
If you have not done a manual check/edit then go to the output directory and run the script pnm_stage2.
Outputs of PNM
The main output of PNM is a file containing the desired regressor information. Since the timing of the MR acquisition varies with slice in the FMRI data, you do not get a simple text file output. Instead you get a set of outputs in the NIFTI format that are voxelwise regressors. There is also a text file with a name ending in _evlist.txt can contains the appropriately ordered list of all of these voxelwise regressors.
For those that are interested, the order of the individual EVs in the output list is the following:
- Cardiac only (sin, then cos, low to high freq: e.g. sin(p), cos(p), sin(2p), cos(2p), etc.)
- Respiratory only (as above for individual terms)
- Interaction terms (cos(c+r), sin(c+r), cos(c-r), sin(c-r), for c,r = multiples of cardiac/resp phase; e.g. starting with c=1*cardiac phase and r=1*resp phase, then c=1*cardiac phase and r=2*resp phase for next set of four, if --multr is 2 or more, ..., c=1*cardiac and r=n*resp, then c=2*cardiac and r=1*resp, if --multc is 2 or more, ...)
If you are just entering the entire set of EVs as confounds into FEAT (the recommended method) then you don't need to worry about the order above.
Using PNM in FEAT
To use the output of PNM with FEAT all you need to do is to find the file with the name ending in _evlist.txt and enter this (via the file browser) in the Voxelwise Confound List in the FEAT GUI (on the Stats tab). This will use these regressors as confounds, giving them automatic zero entries in all contrasts. With the GLM this ensures that wherever there is any shared variance between these and the EVs of interest (specified in the main design matrix) that the shared variance will be assigned to the physiological noise model. This is the conservative, and more correct, option and avoids inflating false positive rates, maintaining interpretability of any significant output results as being due to the changes of interest and not due to physiological noise.
Note on randomise
Since randomise currently cannot account for time-series autocorrelations (it invalids the exchangeability) it is not possible to use PNM with randomise.
Other tools (advanced)
The basic command-line tools used by PNM are: popp and pnm_evs.
The usage for these are:
Part of FSL (build 500) popp Copyright(c) 2011, University of Oxford (Mark Jenkinson) Usage: popp [options] -i <input data file> -o <output data file> Compulsory arguments (You MUST set one or more of): -i,--in input physiological data filename (text format) -o,--out output basename for physiological data and timing/triggers (no extensions) Optional arguments (You may optionally specify one or more of): -s,--samplingrate sampling rate in Hz (default is 100Hz) --tr TR value in seconds --resp specify column number of respiratory input --cardiac specify column number of cardiac input --trigger specify column number of trigger input --rvt generate RVT data --heartrate generate heartrate data --pulseox_trigger specify that cardiac data is a trigger --smoothcard specify smoothing amount for cardiac (in seconds) --smoothresp specify smoothing amount for respiratory (in seconds) --highfreqcutoff high frequency cut off for respiratory filter in Hz (default is 5Hz) --lowfreqcutoff low frequency cut off for respiratory filter in Hz (default is 0.1Hz) --initthreshc initial threshold percentile for cardiac (default 90) --nthreshc neighbourhood exclusion threshold percentile for cardiac (default 60) --initthreshr initial threshold percentile for respiratory (default 80) --nthreshr neighbourhood exclusion threshold percentile for respiratory (default 80) --invertresp invert respiratory trace --invertcardiac invert cardiac trace --noclean1 turn off cleanup phase 1 --noclean2 turn off cleanup phase 2 --loadcardphase input cardiac phase for reprocessing (text format) --loadrespphase input respiratory phase for reprocessing (text format) --vol input volumetric image (EPI) filename --startingsample set sample number of the starting time (t=0) --respadd comma separated list of times (in sec) to add to respiratory peak list (uses nearest local max) --respdel comma separated list of times (in sec) to delete from respiratory peak list (uses nearest existing peak) --cardadd comma separated list of times (in sec) to add to cardiac peak list (uses nearest local max) --carddel comma separated list of times (in sec) to delete from cardiac peak list (uses nearest existing peak) -v,--verbose switch on diagnostic messages --debug output debugging information -h,--help display this message
Part of FSL (build 500) pnm_evs Copyright(c) 2011, University of Oxford (Mark Jenkinson) Usage: pnm_evs [options] --tr=3.0 -i fmri_data.nii.gz -o pnmevs -r resp.txt -c card.txt Compulsory arguments (You MUST set one or more of): -i,--in input image filename (of 4D functional/EPI data) -o,--out output filename (for confound/EV matrix) --tr TR of fMRI volumes (in seconds) Optional arguments (You may optionally specify one or more of): -c,--cardiac input filename for cardiac values (1 or 2 columns: time [phase]) -r,--respiratory input filename for respiratory phase values (1 or 2 columns: time [phase]) --oc order of basic cardiac regressors (number of Fourier pairs) - default=2 --or order of basic respiratory regressors (number of Fourier pairs) - default=1 --multc order of multiplicative cardiac terms (also need to set --multr) - default=0 --multr order of multiplicative respiratory terms (also need to set --multc) - default=0 --csfmask filename of csf mask image (and generate csf regressor) --rvt input filename of RVT data (2 columns: time value) --heartrate input filename for heartrate data (2 columns: time value) --rvtsmooth Optional smoothing of RVT regressor (in seconds - default 0) --heartratesmooth Optional smoothing of heart rate regressor (in seconds - e.g. 10) --slicedir specify slice direction (x/y/z) - default is z --sliceorder specify slice ordering (up/down/interleaved_up/interleaved_down) --slicetiming specify slice timing via an external file --debug turn on debugging output -v,--verbose switch on diagnostic messages -h,--help display this message