run_palm#

qx_utilities.general.palm.run_palm(image, design=None, palm_args=None, root=None, surface='no', mask=None, parelements=None, overwrite='no', cleanup='yes')#

run_palm image=<image file(s)> [design=<design string>] [palm_args=<arguments string>] [root=<root name for the output>] [surface=no] [mask=<mask file>] [parelements=<number of elements to run in parallel>] [overwite=no] [cleanup=yes]

Runs second level analysis using PALM permutation resampling.

Warning

For the PALM processing to run successfully, the input image and the design files need to be prepared and match. Specifically, the input image file should hold first level results (e.g. GLM beta estimates or functional connectivity seed-maps) for all the subjects and conditions. For activation analyses a simple way to generate such a file is to use general_extract_glm_volumes Matlab function.

Design files:

When only a t-test against zero is run across all the volumes in the image, no design files are needed, in all other cases some or all of the design files need to be prepared:

  • design matrix file (d)

  • exchangibility blocks file (eb)

  • t-contrasts file (t)

  • f-contrast file (f).

The files should be named using the following convention. All the files should start with the same root, the design name, followed by an underscore then a tail that specifies the content of the file and the '.csv' extension. The files are expected to be matrices in the comma separated values format.

Parameters

--image (str):

One or multiple files can be specified as input. If multiple files are specified, they will be all passed to PALM. If they are cifti files, they will be split into separate structures and run in parallel. To specify multiple files, separate them with pipe ("|") character and take care to put the whole string with files in quotes. Also, if specifying multiple files, do take care, that they are of the same format (nifti, cifti) and do specify the relevant additional parameters (see below) that are relevant for multimodal testing.

Example string for multiple files:

image='rs_connectivity.dtseries.nii|task_activation.dtseries.nii'
--design (str, default 'name:palm|d:d|t:t|f:f|eb:eb'):

The design name and the specific tails (if the defaults are not used) are specified by a design string. Design string is a pipe separated list of key:value pairs that specify the following (with the defaults in the brackets):

  • 'name' ... the root name of the design files, defaults to 'palm'

  • 'd' ... the design matrix file tail, defaults to ''d'

  • 't' ... the t-contrasts file tail, defaults to 't'

  • 'f' ... the f-contrasts file tail, defaults to 'f'

  • 'eb' ... the exchange blocks file tail, defaults to 'eb'.

If 'none' is given as value, that file is not to be specified and used.

Do take into account that the design files are looked for from the location in which you are running the command from. If they are in a different location, then "name" has to specify the full path!

Two examples of design strings and files:

design='name:sustained|t:taov'

In this case the following files would be expected:

  • sustained_d.csv ... design matrix file

  • sustained_eb.csv ... exchangebility blocks file

  • sustained_taov.csv ... t-contrasts file

  • sustained_f.csv ... f-contrasts file.

design='name:designs/transient|t:faov|f:fmain'

In this case the following files would be expected:

  • designs/transient_d.csv ... design matrix file

  • designs/transient_eb.csv ... exchangebility blocks file

  • designs/transient_taov.csv ... t-contrasts file

  • designs/transient_fmain.csv ... f-contrasts file.

NOTE

The colon symbols used above to denote:

default 'name:palm|d:d|t:t|f:f|eb:eb'

are of the Unicode modifier colon variety (U+A789) and are not equivalent to the usual colon (U+003A) that should be used when running the command. Copying the above line containing modifier colons will result in an error - use normal colons with the command instead.

--palm_args (str, default 'n:100|zstat'):

Additional arguments to palm can be specified using the arguments string. The arguments string is a pipe separated list of arguments and optional values. The format of the string is:

'<arg 1>|<arg 2>|<arg 3>:<value 1>:<value 2>|<arg 4>:<value>'.

The default arguments and values are: 'n:100|zstat', which specify that 100 permutations should be run and the statistics of interest expressed in z values. To exclude a default argument, specify '<arg>:remove', e.g.: 'zstat:remove' if the statistics are not to be converted to z values.

For full list of possible arguments and values, please consult PALM user guide.

Some relevant arguments to consider:

--accel

Methods to accelerate analysis. Possible values are:

  • 'noperm' ... do not do any permutations (works with fdr correction only)

  • 'tail' ... estimates tail of the permuted distribution, needs at least 100 resamples

  • 'negbin' ... runs as many permutations an needed (works with fdr correction only)

  • 'gamma' ... computes the moment of permutation distribution and fits a gamma function

  • 'lowrank' ... runs as many permutations as needed to complete matrix (fdr, fwer only).

--twotail

Run two-tailed test for all the contrasts.

--fonly

Run only f-contrasts and not the individual t-contrasts.

--fdr

Compute a fdr correction for multiple comparisons.

--T

Enable TFCE inference.

--C <z>

Enable cluster inference for univariate tests with z cutoff.

NOTE

The colon symbols used above to denote:

default 'n:100|zstat'

are of the Unicode modifier colon variety (U+A789) and are not equivalent to the usual colon (U+003A) that should be used when running the command. Copying the above line containing modifier colons will result in an error - use normal colons with the command instead.

--T2DHEC (str, default '2:1:26'):

Sets H, E and C parameters for 2D part of analysis.

Sometimes it is desired to specify TFCE parameters that differ from the default values. As the function allows combined surface/volume processing of cifti files, it is useful to be able to set them separately for 2D and 3D analysis. All three values need to be provided when the parameter is specified, for example:

palm_args='T2HEC:2:0.5:26'

Defaults to H=2, E=1, C=26.

--T3DHEC (str, default detailed below):

Sets H, E and C parameters for 3D part of analysis. Defaults to H=2, E=0.5 (C value is not listed in PALM documentation). All three values need to be provided when the parameter is specified, for example:

palm_args='T3DHEC:4:1:6'
--surface (str, default 'no'):

Should the command only analyze left and right surfaces from dtseries or dscalar files.

--mask (str, default None):

Path to the mask file that will be used instead of the default mask files.

--root (str, default detailed below):

Optional root name for the result images, design name is used if the optional parameter is not specified.

--parelements (int | str, default 'all'):

Number of elements to run in parallel for grayordinate decomposition. If specified as None or 'all', all available elements (3 max for left surface, right surface and volume files) will be used. One element per CPU core is processed at a time.

--overwrite (str, default 'no'):

Whether to remove preexisting image files, if they exists, the command will exit with a warning if there are preexisting files and overwrite is set to 'no' (the default).

--cleanup (str, default 'yes'):

Should the command clean all the temporary generated files or not before the command exits.

Notes

TFCE specific additional arguments:

Sometimes it is desired to specify TFCE parameters that differ from the default values. As the function allows combined surface/volume processing of cifti files, it is useful to be able to set them separately for 2D and 3D analysis. run_palm therefore provides two additional optional parameters that are separately expanded to TFCE 2D and 3D settings: --T2DHEC and --T3DHEC.

All three values need to be provided when the parameter is specified, for example:

palm_args="T2HEC:2:0.5:26|T3DHEC:4:1:6"

If these two parameters are not specified, the default values specified by PALM are used, specifically, H=2, E=1, C=26 for 2D analysis and H=2, E=0.5 for 3D analysis (C value is not listed in PALM documentation).

Example TFCE specific additional arguments:

palm_args="n:500|accel:tail|T|fonly"

In this case PALM would run 500 permutations and the p-values would be estimated by a help of the tail estimation acceleration method, TFCE inference would be used, and only f-contrasts would be computed.

Use:

Runs second level analysis using PALM permutation resampling. It provides a simplifed interface, especially when running the analyses on grayordinate, CIFTI images. In this case the .dtseries.nii file will be split up into left and right surface and volume files, PALM will be run on each of them independently and in parallel, and all the resulting images will be then stitched back together in a single .dscalar.nii image file.

For volume images a standard MNI brain mask will be used. For CIFTI dtseries images, a standard atlas 32k midthickness will be used for surface data and the appropriate mask for volume data. In case of ptseries no mask or surface will be used. In the latter case no surface or volume based statistics (e.g. TFCE or clustering extent/mass) should be specified.

For ptseries it might be necessary to specify transposedata in argument string for the data to be interpreted correctly.

Examples

qunex run_palm \
    --design="name:sustained|t:taov" \
    --palm_args="n:500|accel:tail|T|fonly" \
    --root=sustained_aov