Performs (semi)Parametric Bootstrap Joint ((s)PBJ) Inference

pbjInference(
  statMap,
  statistic = mmeStat,
  null = TRUE,
  nboot = 5000,
  rboot = function(n) {
(2 * stats::rbinom(n, size = 1, prob = 0.5) - 1)
 },
  method = c("wild", "permutation", "nonparametric"),
  runMode = c("cdf", "bootstrap"),
  progress = FALSE,
  rdata_rds = NULL,
  cft_s = NULL,
  cft_p = NULL,
  cft_chisq = NULL,
  mc.cores = 1,
  mc.preschedule = FALSE,
  ...
)

Arguments

statMap

statMap object as obtained from lmPBJ function.

statistic

A user specified function that takes an RNifti image object and computes a particular statistic of interest. There are several provided in the pbj package. See referenced functions below.

null

Perform bootstrap under the null or alternative hypotheses?

nboot

Number of bootstrap samples to use.

rboot

Function for generating random variables. Should return an n vector. Defaults to Rademacher random variable.

method

Character, method to use for resampling procedure. Wild bootstrap, permutation, or nonparametric

runMode

character, that controls output. cdf returns the empirical CDFs, bootstrap returns the bootstrapped statistics as a list.

progress

Logical indicating whether to track progress with a progress bar.

rdata_rds

A character string specifying a .rdata or .rds file to write the output. If specified, resampling is run as background process.

cft_s

A vector of robust effect size index (RESI) cluster forming thresholds

cft_p

A vector of p-value cluster forming thresholds

cft_chisq

A vector of p-value cluster forming thresholds

mc.cores

Number of cores to parallelize bootstrap.

mc.preschedule

Logical, where to preschedule jobs see [parallel()]. FALSE is substantially faster.

...

arguments passed to statistic function.

Value

Returns the statMap object, with a pbj object added. If runMode=='cdf', the first element is the observed statistic value, and the subsequent elements are the CDFs and ROIs, used for computing adjusted p-values and plotting. If runMode=='bootstrap', the first element is the observed statistic value and the second is a list of the boostrap values.

Details

This function runs resampling-based methods to perform inference on topological features of neuroimaging statistics. The topological feature is determined by the `statistic` function. Several exist in the pbj package (see below). The statistic function should take an image as input and compute some topological feature from the image. returned as a list. Multiple topological features can be returned, as in [mmeStat()] and [cluster()]. #' To use default methods the statistic must have a logical `rois` argument that outputs an integer valued image identifying where each topological features is located.

See also

[mmeStat()], [maxima()], and [cluster()] for statistic functions. See [lmPBJ()] to create statMap objects. See [image.statMap()], and [table.statMap()] for producing summaries of the results.

Examples

# loading example data
library(pain21)
pain = pain21()
pdata = pain$data

# fitting regression of images onto study sample size,
# weights proportional to study sample size
pbjModel2 = lmPBJ(images=pdata$images, form=~n, formred=~1,
                  W = pdata$n, mask=pain$mask, data=pdata)
table.statMap(pbjModel2, 'maxima')
#>    Cluster ID Chi-square Coord (vox)  Max RESI
#> 45         45  24.221344  60, 44, 66 1.0515599
#> 43         43  23.343209  28, 44, 62 1.0314855
#> 7           7  17.476600  40, 32, 22 0.8857765
#> 46         46  16.176836  40, 34, 69 0.8501214
#> 25         25  16.168037  76, 35, 43 0.8498750
#> 28         28  15.911884  19, 58, 46 0.8426682
#> 42         42  15.226061  53, 27, 61 0.8230623
#> 26         26  15.163414  45, 76, 44 0.8212480
#> 47         47  14.610038  37, 45, 69 0.8050447
#> 21         21  13.652207  63, 87, 37 0.7761997
#> 17         17  13.291865  72, 39, 32 0.7650666
#> 3           3  13.001224  51, 57, 19 0.7559675
#> 10         10  12.791749  20, 34, 25 0.7493409
#> 40         40  12.350620  75, 54, 59 0.7351909
#> 19         19  12.339623  52, 51, 35 0.7348347
#> 33         33  11.717239  72, 56, 48 0.7143841
#> 23         23  11.356693  62, 58, 41 0.7022648
#> 2           2  10.841460  27, 23, 15 0.6845736
#> 24         24  10.810523  26, 44, 42 0.6834967
#> 44         44  10.778501  29, 64, 62 0.6823803
#> 35         35  10.658313  48, 27, 51 0.6781738
#> 13         13  10.242128  24, 65, 27 0.6634013
#> 5           5  10.206622  21, 46, 20 0.6621258
#> 32         32  10.046191  66, 48, 48 0.6563315
#> 18         18  10.034010  19, 73, 34 0.6558894
#> 4           4   9.972489  25, 62, 19 0.6536523
#> 27         27   9.956338  59, 85, 45 0.6530638
#> 48         48   9.868776  66, 61, 70 0.6498636
#> 37         37   9.674047  25, 36, 53 0.6426895
#> 11         11   9.637251  59, 82, 26 0.6413249
#> 20         20   9.338544  13, 44, 36 0.6301377
#> 38         38   8.959892  63, 31, 55 0.6156643
#> 36         36   8.928408  33, 83, 51 0.6144455
#> 29         29   8.382379  32, 93, 47 0.5929096
#> 34         34   8.363429  30, 73, 48 0.5921482
#> 39         39   7.311467  74, 73, 55 0.5482208
#> 16         16   5.778897  60, 16, 29 0.4770394
#> 14         14   5.521011  28, 91, 27 0.4639895
#> 22         22   4.982283  56, 14, 40 0.4354682
#> 1           1   4.914163  70, 73, 14 0.4317276
#> 31         31   4.644791  70, 21, 48 0.4166071
#> 41         41   4.473856  44, 88, 60 0.4067207
#> 8           8   4.459178  79, 58, 22 0.4058605
#> 15         15   4.236288  30, 15, 28 0.3925671
#> 30         30   4.193633  42, 13, 48 0.3899715
#> 6           6   4.134629  47, 76, 21 0.3863523
#> 9           9   3.958388  44, 93, 24 0.3753340
#> 12         12   3.316599  71, 83, 26 0.3321359


# p-value thresholding for cluster extent/mass
# not run, parallel processing
# pbjModelAll <- pbjInference(pbjModel2, nboot=50, cft_p=0.01,
#                             CEI=TRUE, CMI=TRUE, max=TRUE,
#                             mc.cores=ceiling(parallel::detectCores()/2))
pbjModelAll <- pbjInference(pbjModel2, nboot=5, cft_p=0.01,
                            CEI=TRUE, CMI=TRUE, max=TRUE)
head(table.statMap(pbjModelAll, method = 'maxima'))
#>    Cluster ID Chi-square Coord (vox) FWER p-value  Max RESI
#> 45         45   24.22134  60, 44, 66          0.2 1.0515599
#> 43         43   23.34321  28, 44, 62          0.2 1.0314855
#> 7           7   17.47660  40, 32, 22          0.2 0.8857765
#> 46         46   16.17684  40, 34, 69          0.4 0.8501214
#> 25         25   16.16804  76, 35, 43          0.4 0.8498750
#> 28         28   15.91188  19, 58, 46          0.4 0.8426682
head(table.statMap(pbjModelAll, method = 'CEI', cft_p=0.01))
#>    Cluster ID Cluster Extent Centroid (vox) Unadjusted p-value FWER p-value
#> 2           2           3382     49, 44, 63        0.002994012          0.2
#> 22         22           1624     67, 55, 40        0.002994012          0.2
#> 59         59           1569     40, 33, 21        0.002994012          0.2
#> 17         17            635     74, 37, 38        0.002994012          0.2
#> 27         27            371     20, 58, 43        0.002094241          0.2
#> 21         21            274     47, 76, 45        0.002094241          0.2
#>     Max RESI
#> 2  1.0515599
#> 22 0.7143841
#> 59 0.8857765
#> 17 0.8498750
#> 27 0.8426682
#> 21 0.8212480
# returns the first threshold used
head(table.statMap(pbjModelAll, method = 'CMI', cft_p = 0.01))
#>    Cluster ID Cluster Mass Centroid (vox) Unadjusted p-value FWER p-value
#> 2           2    28053.356     49, 44, 63        0.002994012          0.2
#> 59         59    12903.292     40, 33, 21        0.002994012          0.2
#> 22         22    12511.473     67, 55, 40        0.002994012          0.2
#> 17         17     5285.350     74, 37, 38        0.002994012          0.2
#> 27         27     3105.267     20, 58, 43        0.002094241          0.2
#> 21         21     2226.842     47, 76, 45        0.002094241          0.2
#>     Max RESI
#> 2  1.0515599
#> 59 0.8857765
#> 22 0.7143841
#> 17 0.8498750
#> 27 0.8426682
#> 21 0.8212480
# RESI effect size thresholding for cluster extent/mass
pbjModel2 = pbjInference(pbjModel2, nboot=2, cft_s=c(0.1, 0.25), CMI=TRUE)
head(table.statMap(pbjModel2, method = 'CEI', cft_s=0.1))
#>    Cluster ID Cluster Extent Centroid (vox) Unadjusted p-value FWER p-value
#> 1           1         158936     46, 52, 41        0.002392344          0.5
#> 74         74            196     63, 59, 15        0.030563136          1.0
#> 52         52             23     64, 90, 26        0.138260410          1.0
#> 26         26             22     66, 22, 48        0.144775068          1.0
#> 49         49             17     24, 93, 29        0.155794231          1.0
#> 77         77             16     59, 66, 13        0.155794231          1.0
#>     Max RESI
#> 1  1.0515599
#> 74 0.4581658
#> 52 0.2183630
#> 26 0.3629843
#> 49 0.2628849
#> 77 0.1789521
head(table.statMap(pbjModel2, method = 'CEI', cft_s=0.25))
#>     Cluster ID Cluster Extent Centroid (vox) Unadjusted p-value FWER p-value
#> 2            2          91472     46, 50, 41        0.002747253          0.5
#> 62          62           1442     57, 18, 34        0.002500000          0.5
#> 92          92           1068     47, 85, 26        0.002500000          0.5
#> 18          18           1023     42, 89, 57        0.002500000          0.5
#> 81          81            787     33, 26, 33        0.002500000          0.5
#> 117        117            624     73, 69, 18        0.002500000          0.5
#>      Max RESI
#> 2   1.0515599
#> 62  0.4770394
#> 92  0.4384951
#> 18  0.4067207
#> 81  0.4301236
#> 117 0.4317276
# Inference on local maxima
pbjModel2 = pbjInference(pbjModel2, nboot=2, statistic = maxima)
# Cluster extent inference
pbjModelCEI = pbjInference(pbjModel2, nboot=2, statistic = cluster, cft_s=0.1)

# not run
# outfile = paste0(tempfile(), '.rds')
# run in parallel in the background
# bgInfo <- pbjInference(pbjModel2, rdata_rds = outfile, nboot=50, cft_p=0.01,
# CEI=TRUE, CMI=TRUE, max=TRUE, mc.cores=ceiling(parallel::detectCores()/2))
# statMap = readRDS(outfile)