Differences between revisions 180 and 181
Revision 180 as of 17:33:49 27-02-2021
Size: 37277
Comment:
Revision 181 as of 02:14:34 14-06-2021
Size: 37277
Comment:
Deletions are marked like this. Additions are marked like this.
Line 6: Line 6:
To download latest packaged version, please '''[[https://s3-us-west-2.amazonaws.com/andersonwinkler/palm/palm-alpha118.tar.gz|click here]]'''. To download latest packaged version, please '''[[https://s3-us-west-2.amazonaws.com/andersonwinkler/palm/palm-alpha119.tar.gz|click here]]'''.


Downloading and installing PALM

To download latest packaged version, please click here.

Alternatively, visit the repository on GitHub.

PALM can run as a standalone command (i.e., executed directly from the command line/terminal), or inside Octave or Matlab. In Linux and in Mac systems, it can be executed in any of these ways. In Windows, it can be executed inside Matlab or Octave.

Running as a standalone command

It may be much simpler to run PALM as a command directly from the shell in Linux or in Mac, and it can easily be called from scripts. To do so:

  1. Uncompress the downloaded file.
  2. Open the file palm (not to be confused with palm.m). This is a script, inside which you can set whether the script should use Octave or Matlab. If the one that is chosen isn't in the $PATH variable, make sure to specify also the path to the directory that contains the executable for either of these (whichever you choose).

  3. To invoke PALM, simply type ./palm in the directory where it was installed. The path can also be added to the system's $PATH variable, so that it can be easily called from any directory just by typing palm.

If you are using Mac, and choose Octave, note that reading of NIFTI files need the option '-noniiclass' to work properly (more details below).

Running inside Matlab

Uncompress the downloaded file, open Matlab, and add the newly created directory to the Matlab path (menu File --> Set Path). Typing palm at the prompt without arguments shows usage information. This works for Linux, Mac and Windows.

Running inside Octave

Uncompress the downloaded file, start Octave, and add the newly created directory to the Octave path. This can be done with the command addpath:

addpath('/full/path/to/palm')

This line can be added to the ~/.octaverc file, so that the change becomes permanent (if the ~/.octaverc doesn't exist, an empty file can be created, then the line added). Typing palm at the prompt without arguments shows usage information. This works for Linux and Mac. It can work also with Windows if the paths are entered using the Windows filesystem convention (e.g., C:\example).

For Octave for Mac, note that reading of NIFTI files need the option '-noniiclass' to work properly (more details below).

For spatial statistics (cluster extent, cluster mass, and TFCE), the package 'image' is required.


Using PALM

A description of the main options is below. The same information can be seen if the command palm is executed without arguments.

Option

Description

-i <file>

Input(s). More than one can be specified, each one preceded by its own -i. All input files must contain the same number of observations (e.g., the same number of subjects). Except for NPC and MV, mixing is allowed (e.g., voxelwise, vertexwise and non-imaging data can be all loaded at once, and later will be all corrected across).

-m <file>

Mask(s). Either one for all inputs, or one per input supplied in the same order as the respective -i appear.

-s <filesurf> [filearea]

Surface file(s). When more than one is supplied, each -s should be entered in the same order as the respective -i. This option is needed when the input data is a scalar field over a surface and cluster extent or TFCE have been enabled. The first argument is the surface file itself. The second is an optional area-per-vertex or area-per-face file, or simply a number. If only the surface file is provided, its area is calculated and used for the computation of spatial statistics (cluster extent and TFCE). If the second argument is given, it should contain the areas, which are then used (e.g., average areas from native geometry after areal interpolation). Alternatively, if the areas are not meaningful for cluster extent or TFCE, this argument can be simply a number, such as "1", which is then used as the area of all vertices or faces.

-d <file>

Design matrix. It can be in csv format, or in fsl's vest format. For information on how to construct the design matrix, see the FSL GLM manual.

-t <file>

t-contrasts file, in csv or vest format (the format used by FSL). The option -t can be used more than once, so that more than one t-contrasts file can be loaded.

-f <file>

F-contrasts file, in csv or vest format. The option -f can be used more than once, so that more than one F-contrasts file can be loaded. Each file supplied with a -f corresponds to the file supplied with the option -t immediately before. The option -f cannot be used more than the number of times the option -t is used.

-fonly

Run only the F-contrasts, not the t-contrasts.

-n <integer>

Number of permutations. Use -n 0 to run all permutations and/or sign-flips exhaustively. Default is 10000.

-eb <file>

Exchangeability blocks file, in csv or vest format. If omitted, all observations are treated as exchangeable and belonging to a single large exchangeability block.

-within

If the file supplied with -eb has a single column, this option runs within-block permutation (default). Can be used with '-whole'.

-whole

If the file supplied with -eb has a single column, this option runs whole-block permutation. Can be used with '-within'.

-ee

Assume exchangeable errors (EE), to allow permutations (more details below).

-ise

Assume independent and symmetric errors (ISE), to allow sign-flipping (more details below).

-vg <file>

Variance groups file, in csv or vest format. If omitted, all observations are assumed to belong to the same variance group (i.e. the data is treated as homoscedastic. Use '-vg auto' to define the automatically using a structure that is compatible with the exchangeability blocks (option -eb).

-npcmethod <method>

Do a modified non-parametric combination (NPC), using the the specified method (combining function), which can be one of: Tippett, Fisher, Stouffer, Wilkinson <alpha>, Winer, Edgington, Mudholkar-George, Friston <u>, Darlington-Hayes <r>, Zaykin <alpha>, Dudbridge-Koeleman <r>, Dudbridge-Koeleman2 <r> <alpha>, Taylor-Tibshirani or Jiang <alpha>. Default is Fisher. Note that some methods require 1 or 2 additional parameters to be provided. All methods except Darlington-Hayes and Jiang can also be used to produce parametric p-values (under certain assumptions) and spatial statistics.

-npcmod

Enable NPC over modalities.

-npccon

Enable NPC over contrasts.

-npc

Shortcut to "-npcmethod <default method> -npcmod". The default method is Fisher (this can be changed in the file palm_defaults.m).

-mv <statistic> <k>

Do classical multivariate analysis (MV), such as MANOVA and MANCOVA, using the the specified statistic, which can be one of: Wilks, HotellingTsq, Lawley, Pillai, Roy_ii, Roy_iii. All but Roy_iii can be used with spatial statistics.

-pearson

Instead of t, F, v or G, compute the Pearson's correlation coefficient, r (if the constrast has rank=1), or the coefficient of determination, R2 (if the constrast has rank>1). For the contrasts in which some EVs are zeroed out, this option computes the multiple correlation coefficient (or R2) corresponding to the EVs of interest.

-T

Enable TFCE inference for univariate (partial) tests, as well as for NPC and/or MV if these options have been enabled.

-C <real>

Enable cluster inference for univariate (partial) tests, with the supplied cluster-forming threshold (supplied as the equivalent z-score), as well as for NPC and/or MV if these options have been enabled.

-Cstat <name>

Choose which cluster statistic should be used. Accepted statistics are "extent" and "mass".

-tfce1D

Set TFCE parameters for 1D data (timeseries), i.e., H = 2, E = 2, C = 6. Use this option together with -T.

-tfce2D

Set TFCE parameters for 2D data (surface, TBSS), i.e., H = 2, E = 1, C = 26. Use this option together with -T.

-corrmod

Apply FWER-correction of p-values over multiple modalities.

-corrcon

Apply FWER-correction of p-values over multiple contrasts.

-fdr

Produce FDR-adjusted p-values.

-o <string>

Output prefix. It may itself be prefixed by a path. Default is palm.

-save1-p

Save (1-p) instead of the actual p-values. Instead of -save1-p, consider using -logp.

-logp

Save the output p-values as -log10(p) (or -log10(1-p) if the option -save1-p is also used; using both together is not recommended). The -logp is not default but it is strongly recommended.

-demean

Mean center the data, as well as all columns of the design matrix. If the original design had an intercept, the intercept is removed.

-twotail

Run two-tailed tests for all the t-contrasts instead of one-tailed. If NPC is used, it also becomes two-tailed for the methods which statistic are symmetric around zero under the null.

-concordant

For the NPC, favour alternative hypotheses with concordant signs. Cannot be used with "-twotail".

-accel <method>

Run one of various acceleration methods (negbin, tail, noperm, gamma, lowrank). Click here for details.

-reversemasks

Reverse 0/1 in the masks, so that the zero values are then used to select the voxels/vertices/faces.

-quiet

Don't show progress as the shufflings are performed.

-advanced

Show advanced options (see below).

Advanced options are:

Option

Description

-con <file1> <file2>

Contrast file(s) in .mset format. For hypotheses of the form H0: C'*Beta*D, file1 contains a set of C contrasts, and file2 (optional) contains a set of D contrasts, that are performed in pairs (C,D).

-tonly

Run only the t-contrasts, not the F-contrasts.

-cmcp

Ignore the possibility of repeated permutations. This option will be ignored if the number of shufflings chosen is larger than the maximum number of possible shufflings, in which case all possible shufflings will be performed.

-cmcx

Ignore the possibility of repeated rows in X when constructing the set of permutations, such that each row is treated as unique, regardless of potential repetitions (ties).

-conskipcount <integer>

Normally the contrasts are numbered from 1, but this option allows staring the counter from the specified number. This option doesn't affect which contrasts are performed.

-Cuni <real>

Enable cluster inference for univariate (partial) tests, with the supplied cluster-forming threshold (as a z-score).

-Cnpc <real>

Enable cluster inference for NPC, with the supplied cluster-forming threshold (as a z-score).

-Cmv <real>

Enable cluster inference for MV, with the supplied cluster-forming threshold (as a z-score).

-designperinput

Use one design file for each input modality.

-ev4vg

Add to the design one EV modelling the mean of each VG.

-evperdat <string> [integer] [integer]

Treat the design matrix supplied with -d as having one column for each column in the observed data (entered with -i). This enables voxelwise/facewise/vertexwise regressors. For details, click here.

-inormal

Apply an inverse-normal transformation to the data. This procedure can go faster if the data is known to be quantitative (in which case, use '-inormal quanti'). There are four different methods available, which can be specified as '-inormal <method>' or '-inormal quanti <method>'. The methods are Waerden (default), Blom, Tukey and Bliss.

-probit

Apply a probit transformation to the data.

-inputmv

Treat the (sole) input as multivariate, that is, each column is a variable in a multivariate model, as opposed to independent univariate tests. Useful with non-imaging data.

-noranktest

For MV, don't check the rank of the data before trying to compute the multivariate statistics.

-noniiclass

Do not use the NIFTI class (use this option only if you have problems and even so, only for small datasets).

-precision <string>

Precision ("single" or "double") for input files.

-nounivariate

Don't save univariate results.

-nouncorrected

Don't save uncorrected results.

-pmethodp

Partition method used when defining the set of permutations. Can be Guttman, Beckmann, Ridgway or None. Default is Beckmann.

-pmethodr

Partition method used during the regression. Valid values are Guttman, Beckmann, Ridgway or None. Default is Beckmann.

-removevgbysize <integer>

Remove from the data and design those observations that are in VGs of size smaller or equal than specified. This is specially useful with the option '-vg auto'.

-rmethod <string>

Method for regression/permutation. It can be one of Freedman-Lane, Dekker, terBraak, Manly, Draper-Stoneman, Still-White and Huh-Jhun. Default, and recommended, is Freedman-Lane.

-savedof

Save file with the degrees of freedom.

-savemask

Save the effective masks used for each modality, as well as an intersection mask used for NPC and/or MV of these have been selected.

-savemetrics

Save a csv file with various permutation metrics.

-saveparametric

Save also uncorrected parametric p-values. These are only valid if all assumptions are met, including iid and normality.

-saveglm

Save COPEs and VARCOPEs in the first permutation.

-saveperms

Save one statistic image per permutation, as well as a csv file with the permutation indices (one permutation per row, one index per column; sign-flips are represented by the negative indices). Use cautiously, as this may consume large amounts of disk space.

-savemax

Save the distribution of the maximum statistic across (taken within each input file).

-nounivariate

For classical multivariate and NPC, don't save the univariate results.

-seed <positive>

Seed used for the random number generator. Use a positive integer up to 232. Default is 0. To start with a random number, use the word 'twist' instead of the integer. Note that a given seed used in Matlab isn't equivalent to the same seed used in Octave.

-syncperms

If possible, use synchronized permutations even they wouldn't be used by default.

-subjidx <file>

Indices of input data to keep in the design.

-tfce_H <real>

Set the TFCE H parameter (height power).

-tfce_E <real>

Set the TFCE E parameter (extent power).

-tfce_C <integer>

Set the TFCE C parameter (connectivity).

-tfce_dh <real>

Set the "delta h" for the calculation of TFCE. Default is "auto" (or 0), i.e., defined on a per-case basis, with max(:)/100 for each map.

-Tuni

Enable TFCE inference for univariate (partial) tests.

-Tnpc

Enable TFCE inference for NPC.

-Tmv

Enable TFCE inference for MV.

-transposedata

For input data (-i) that are csv tables, transpose rows and columns. If -evperdat is used, these are also transposed.

-verbosefilenames

Use lengthy filenames, even if the numbering goes up to 1 only.

-vgdemean

Mean center the data, as well as all columns of the design matrix, within each VG. Intercepts are removed.

-zstat

Convert the original statistic (t, F, v, G, r, R2, or any of the NPC or MV statistics) to a normally distributed, z-statistic.


Input files

Input files are recognised by the file extension:

Extension

Read as

.nii, .hdr, .img

NIFTI file. Can be used to input data (option -i) and mask (-m). Note that the old ANALYZE format is not supported.

.nii.gz

Compressed NIFTI file. Should be uncompressed manually (with gunzip) and loaded as nii (it uses more disk space, but far less memory). Or can be read directly with the option -noniiclass, but beware that for large datasets, the data may easily occupy 'all' the computer memory.

.mgh, .mgz

FreeSurfer data, either volumetric or surface-based. Can be used to input data (option -i) or mask for the same kind of data (option -m).

.dpv, .dpf, .dpx

Data-per-vertex (vertexwise), data-per-face (facewise), or unspecified surface-based data. Can be used to specify a mask (option -m) for surface-based data. Multiple such files can be merged into a csv table, and then input with the option -i; see details below.

.csv

Table in csv format. Can be used to specify input data (option -i), mask for the same kind of data (option -m), design matrix (option -d), contrasts (options -t and -f), exchangeability blocks (-eb) and variance groups (-vg).

.mat, .con, .fts, .grp

Table in the FSL vest format. Can be used essentially in the same way as csv files, i.e., to specify input data (option -i), mask for the same kind of data (-m) design matrix (-d), contrasts (options -t and -f), exchangeability blocks (-eb) and variance groups (-vg).

.mset

Multiple tables (arrays) in a single ASCII file. This format can be used with the option -con.

.srf

Surface in ASCII format (option -s).

.inflated, .nofix, .orig, .pial, .smoothwm, .sphere, .reg, .white

Files with these extensions are read as FreeSurfer surface (option -s).

.gii

GIFTI file.

.dtseries.nii, .ptseries.nii, .dscalar.nii, .pscalar.nii

CIFTI file. Support is currently available for .dscalar.nii, .dtseries.nii, .pscalar.nii and .ptseries.nii. It is expected that in the future there will be complete support for CIFTI files.

Files with extensions not listed above won't be read.

Support for NIFTI files

Support for NIFTI files is provided, internally, by the publicly available NIFTI class. This allows reading and writing even huge files without using too much computer memory. However, the NIFTI class does not operate on compressed files, i.e., with extension .nii.gz. To read these files, it is recommended that they are uncompressed (with gunzip).

Alternatively, if the datasets are small, and if either FSL or FreeSurfer are installed, the NIFTI class can be disabled with the option -noniiclass. This allows to read/write these .nii.gz files directly. However, if the files are too large, this can easily use all the computer memory and the system may become unstable/unusable. The option -noniiclass should be used with great caution for large datasets.

The NIFTI class, that is used by default, already comes with precompiled binaries for Matlab in various platforms, and for Octave for most 64-bit Linux distributions. Nonetheless, if compilation is needed, try using:

cd /full/path/to/palm/fileio/@file_array/private
./compile.sh

Support for FreeSurfer files

To be able to read/write FreeSurfer binary files (surfaces and curvatures), FreeSurfer needs to be installed and configured correctly. Surface files in ASCII format are read directly by PALM as long as their file extension is srf, so FreeSurfer isn't necessary for these files.

Freesurfer "curvature" files converted to ASCII (asc/dpv/dpf/dpx) need to be merged and converted to csv tables. To generate a valid csv file, use the command dpx2csv (available here) to make the csv file, initially with one column per subject and one row per vertex or face, then transpose the rows and columns of this file with the command transpose (available here).

Support for MZ3 files

MZ3 is a highly efficient, fast and compressed format to store triangular surfaces developed by Chris Rorden and colleagues. A full description of the format is available here. Support is provided natively.

Support for CSV files

Although PALM was created with imaging in mind, it can be used for non-imaging data. Any kind of data that can be arranged in a table and saved as comma-separated values file (csv) (i.e., any data) can be used as input. Each row constitutes a subject or observation, and each column represents a measurement. The csv files must contain numeric fields only, i.e., title labels are not accepted and will cause errors.

If the data is arranged as space- or tab-separated values instead of comma-separated values, it can be converted quickly using awk (or gawk):

awk 'BEGIN { OFS="," } { $1=$1; print $0 }' oldfile.txt > newfile.csv

If your data has any other separator, e.g., a semicolon, the same applies with using a small modification:

awk 'BEGIN { FS="x"; OFS="," } { $1=$1; print $0 }' oldfile.txt > newfile.csv

where the "x" should be replaced by the separator in the original table (e.g., a semicolon).

Support for MSET files

To allow multivariate contrasts, PALM uses a simple ASCII format that can contain multiple matrices. An example of such file is:

Matrix 1 3
1 -1 0

Matrix 2 3
1 -1 0
1 0 -1

In the example, the first matrix is defined as having 1 row and 3 columns (the numbers after the keyword "Matrix"). The second matrix is defined as having 2 rows and 3 columns. Files as these are meant to be used to test multivariate hypotheses as H: C'*Beta*D using the option -con <file1> <file2>, where <file1> is a file with multiple contrasts C and <file2> with multiple contrasts D. Each contrast in C pairs with a contrast in D.

Support for CIFTI files

Both the surface and volume components in CIFTI files that are of the type "dtseries", "ptseries", "dscalar" and "pscalar" can be read directly. If no spatial statistics are requested (i.e., no TFCE or cluster-level inference), all “grayordinates” (whether surface or volume) are processed without any complications. However, when spatial statistics are requested, it is currently necessary to first manually split the CIFTI files into separate surface (GIFTI) and volume (NIFTI) components, which then can be loaded and processed (see examples in this page). The Connectome Workbench must be installed. CIFTI can be used with PALM in Octave (both Mac and Linux) and in Matlab (Linux only).

Support for GIFTI files

GIFTI files are supported. However, note that the access to the actual data depends on parsing a potentially large XML tree, which can be slow in both Matlab and Octave. Other equivalent formats are usually faster to load.

Support for other file formats

If there is a file format that cannot be easily converted to csv, and which you'd like to be able to read directly in PALM, feel free to contact us. New formats may be added for future releases.


Permutations or sign-flips?

Exchangeable errors (EE) are assumed by default, such that permutations are performed. If the option -ise is supplied, the errors are instead assumed to be independent and symmetric (ISE) and only sign-flips are performed. If both -ee and -ise options are given, the errors are treated as being exchangeable, independent and symmetric, and both permutations and sign-flips are performed.


Defining exchangeability blocks

A basic definition of exchangeability blocks (EBs) can be made using a text file containing a single column of positive integers representing the blocks, i.e., one value per line. This file is supplied with the option -eb, and indicates that the observations corresponding to each line can only be shuffled within block of the same index. If a file with this simple structure is given with -eb and the option -whole is used, then the blocks are permuted as a whole, with the order of observations inside each block being kept unchanged. If the option -ise is used, sign-flips ignore block definitions unless the option -whole is given, in which case the signs of the blocks as a whole are flipped. If the option -whole is used together with the option -within, permutations happen for the blocks as a whole, and further within each block.

While the simple block specification as above, with just one column of indices, can cover various designs with structured dependence between observations, cases of more complex dependence can be accommodated using multiple, nested block definitions. In this case, the file containing the block definitions needs not just one, but multiple columns, each with a sequentially deeper level of dependence. Indices on one level indicate how the indices of the next level should be permuted. Positive indices at one level indicate that the corresponding indices of the next level should be permuted as a whole, akin to whole-block permutation with the "-whole" option described above. Negative indices at one level indicate that the corresponding indices in the next level should not be permutted, and their own subindices should be permuted within block, akin to within-block permutation described above. With this more complex structure, the option "-whole", even if supplied, is ignored, as this information is embedded, at multiple levels, in the file with the block definitions.

For more details and examples, click here.


Output files

All output file names are prefixed by the string supplied with the option -o. If this option is not supplied, the outputs will be saved to the directory from which palm is executed, all named as palm_*. The file names follow a consistent convention described below.

The file format of the outputs is the same as the input data (supplied with the option -i, collapsed along the dimension of the observations, i.e., the 4th dimension for 4D datasets (NIFTI or FreeSurfer surface formats), or the 1st dimension (rows) of csv files or 2D NIFTI files.

There are 2 outputs of general interest: the statistic image and its associated p-value. If the option -saveperms is used, the statistic computed for each permutation is also saved, as well as a table with the permutation indices for these images. These files are named according to the following convention:

File name

File contents

{prefix}_{unit}_{stat}_m{#}_d{#}_c{#}.{ext}

Statistic for the modality m{#}, for the design d{#} and for contrast c{#}.

{prefix}_{unit}_{stat}_{pval}_m{#}_d{#}_c{#}.{ext}

P-value for the modality m{#}, for the design d{#} and for contrast c{#}.

{prefix}_{unit}_{stat}_m{#}_d{#}_c{#}.dof

A text file containing the degrees of freedom for the statistic computed for the modality m{#}, for the design d{#} and for contrast c{#}. This is only useful to refer to the parametric distribution to find the p-values (which can, nonetheless, be produced directly with the option -saveparametric. For the v and G statistics, the dof of the errors are saved in the same format as the inputs.

{prefix}_{unit}_{stat}_m{#}_d{#}_c{#}_perm{#}.{ext}

Statistic for the permutation perm{#} for the modality m{#}, for the design d{#} and for contrast c{#}, if the option -saveperms is used.

{prefix}_{unit}_{stat}_m{#}_d{#}_c{#}_permidx.csv

Permutation indices, with negatives for the sign flips, if the option -saveperms is used. This csv file has one row per permutation and one column per permutation index.

Each of these fields are:

Field

Description

{prefix}

The prefix supplied with the option -o, which can contain full path information. If -o isn't supplied, the default prefix is palm.

{unit}

The unit in space in which the statistic is calculated. This can be vox for voxelwise, vtx for vertexwise, fac for facewise, dpx for surface-data without specification (it can be vertexwise or facewise if the actual surface geometry wasn't supplied with the -s option), dat for any data that doesn't necessarily have a spatial meaning (e.g., data entered in csv format), clustere for cluster extent, clusterm for cluster mass, or tfce for TFCE.

{stat}

The name of the statistic, which can be tstat for the t-statistic, fstat for the F-statistic, vstat for the Aspin–Welch's v-statistic, gstat for the generalised G-statistic, rstat for the Person's r correlation coefficient, rsqstat for the R2 coefficient of determination. For NPC, it is npc, appended by the name of the combining function. For MV, it is mv appended by the name of the statistic, or by tsqstat for Hotelling's T2. If the option -zstat was enabled, all these names are prefixed by the letter z.

{pval}

The type of p-value stored in the image. It can be uncp for uncorrected permutation p-values, fwep for the p-values FWER-corrected within modality and contrast, cfwep for the p-values FWER-corrected across contrasts if the option -corrcon was used (so, within modality), mfwep for the p-values FWER-corrected across modalities if the option -corrmod was used (so, within contrast), mcfwep for the p-values FWER-corrected across modalities and contrasts, fdrp for p-values FDR-adjusted within modality and contrast, uncparap uncorrected parametric p-value and fdrparap parametric FDR-corrected p-values.

m{#}

Modality index, in the same order as supplied as input with the option -i. This is omitted for the NPC over modalities and for MV statistics, or if there is just one modality.

d{#}

Design index, in the same order as supplied with the option -d. This is omitted if there is just one design.

c{#}

Contrast index, in the same order as in the files supplied with the -t and/or -f options. This is omitted if there is just one contrast.

perm{#}

Statistic map for the permutation perm{#} if the option -saveperms is used.

{ext}

File extension. This will typically be the same extension as the corresponding input files.

In addition, other files are created: a small text file is saved containing the degrees of freedom associated with the statistic. For the v and G statistics, the degrees of freedom associated with the errors vary for each image point and are saved as a map. A configuration file with all the input options is also saved. This file can be used as the sole argument to palm to run the same analysis again.


PALM or randomise?

Compared to randomise, PALM performs overall the same type of test, i.e., permutation, but offering various additional or novel features:

Feature

randomise

PALM

Input formats

NIFTI.

NIFTI, CSV, GIFTI, FreeSurfer (surface formats, MGH files, curvature, including ASCII vertexwise and facewise). Partial support for CIFTI.

Univariate statistics

t and F.

t, F, Aspin–Welch's v, G, Pearson's r and R2.

Multivariate statistics

None

Hotelling's T2, Wilks' lambda, Pillai's trace, Lawley–Hotelling's trace, Roy's largest root (both variants), assessed parametrically and non-parametrically. Details here.

Spatial statistics

Cluster extent, cluster mass, TFCE. All of these can be volume-based (voxelwise).

Cluster extent, cluster mass, TFCE. All of these can be volume-based (voxelwise) or surface-based (vertexwise or facewise).

Regression and permutation strategies

Freedman–Lane.

Draper–Stoneman, Still–White, Freedman–Lane, ter Braak, Manly, Huh–Jhun, Dekker and parametric (no permutation).

Shuffling possibilities

Permutations or sign-flippings.

Permutations, sign-flippings, and permutations with sign-flippings.

Block permutation

Either whole-block or within-block.

Whole-block and/or within-block, either in isolation or in arbitrary combinations, with multiple and complex levels of tree-like dependence between observations. Details here.

Variance groups

One. Cannot be changed.

Multiple. Can be set automatically or defined by the user. Details here.

Input datasets (modalities)

One.

Multiple.

Input designs matrices

One.

Multiple.

Joint permutation inference across modalities and/or contrasts (NPC)

No.

Yes. Various combining functions available: Tippett, Fisher, Pearson–David, Stouffer, Wilkinson, Winer, Edgington, Mudholkar–George, Friston, Darlington–Hayes, Zaykin, Dudbridge–Koeleman (2 variants), Taylor–Tibshirani and Jiang. Most of these can also be assessed parametrically. Details here.

FWER correction

Within each contrast only.

Within contrast, across contrasts, within modality, across modalities, and across modalities and contrasts. For correction across modalities, these don't need to have the same resolution or geometry; in fact, they don't need to be imaging data (and images can be mixed with non-images).

FDR correction

Yes, separate command. Correction within each contrast only.

Yes, built-in. Correction can be within contrast, across contrasts, within modality, across modalities, and across modalities and contrasts. For correction across modalities, these don't need to have the same resolution or geometry; in fact, they don't need to be imaging data (and images can be mixed with non-images).

Non-stationarity correction

Yes.

No.

Voxelwise regressors

Yes.

Yes. Details here.

Fast approximations

No.

Yes, various methods described here.

Parametric p-values

No.

Yes, for univariate, multivariate, and most of the NPC combining functions (uncorrected and FDR-corrected).

Permutation metrics

None.

Average Hamming distance, Hubermann–Hogg complexity and entropy measurements.

Overall performance

Generally a bit slower, except for spatial statistics.

Generally a bit faster, except for spatial statistics, that can be extremely slow. Includes acceleration methods (details here)

Parallel processing

Yes, with a separate command (randomise_parallel).

No.

Language

Written in C++.

Written in Matlab/Octave.

License

Free for academic use.

Free (GPL).


References

The main reference for PALM is the same as for randomise:

* Winkler AM, Ridgway GR, Webster MA, Smith SM, Nichols TE. Permutation inference for the general linear model. NeuroImage, 2014;92:381-397 (Open Access)

For correction across contrasts (option -corrcon), the most detailed reference is:

* Alberton BAV, Nichols TE, Gamba HR, Winkler AM. Multiple testing correction over contrasts for brain imaging. Neuroimage. 2020 Mar 19:116760. (Open Access)

For Non-Parametric Combination (NPC; options -npc, -npcmod and -npccon), classical multivariate tests (MANOVA, MANCOVA; option -mv) assessed with permutations, and for correction over contrasts and/or modalities (options -corrcon and -corrmod), the reference is:

* Winkler AM, Webster MA, Brooks JC, Tracey I, Smith SM, Nichols TE. Non-Parametric Combination and related permutation tests for neuroimaging. Hum Brain Mapp. 2016 Apr;37(4):1486-511. (Open Access)

For the multi-level exchangeability blocks (options -eb, -vg, and for HCP data), the reference is:

* Winkler AM, Webster MA, Vidaurre D, Nichols TE, Smith SM. Multi-level block permutation. Neuroimage. 2015;123:253-68. (Open Access)

For the accelerated permutation inference (options -accel or -approx), the reference is:

* Winkler AM, Ridgway GR, Douaud G, Nichols TE, Smith SM. Faster permutation inference in brain imaging. Neuroimage. 2016 Jun 7;141:502-516. (Open Access)

For additional theory of permutation tests in neuroimaging, please see and cite:

* Nichols TE, Holmes AP. Nonparametric permutation tests for functional neuroimaging: a primer with examples. Hum Brain Mapp. 2002 Jan;15(1):1-25.

* Holmes AP, Blair RC, Watson JD, Ford I. Nonparametric analysis of statistic images from functional mapping experiments. J Cereb Blood Flow Metab. 1996 Jan;16(1):7-22.

 

PALM/UserGuide (last edited 02:14:34 14-06-2021 by AndersonWinkler)