Sparse canonical correlations for symptom mapping

Multivariate SCCAN adapted for lesion to symptom mapping purposes. By default an optimization routine is used to find the best sparseness value. If you specify sparseness manually, it will be validated to find the cross-validated correlation that can be obtained with that sparseness. You can skip the entire optimization/validation by choosing optimizeSparseness=FALSE. To understand SCCAN arguments, see sparseDecom2.

lsm_sccan(lesmat, behavior, mask, showInfo = TRUE,
  optimizeSparseness = TRUE, validateSparseness = FALSE,
  pThreshold = 0.05, mycoption = 1, robust = 1, sparseness = 0.045,
  sparseness.behav = -0.99, nvecs = 1, cthresh = 150, its = 20,
  npermsSCCAN = 0, smooth = 0.4, maxBased = FALSE,
  directionalSCCAN = TRUE, ...)

Arguments

lesmat

matrix of voxels (columns) and subjects (rows).
behavior

vector of behavioral scores.
mask

antsImage binary mask to put back voxels in image.
showInfo

logical (default=TRUE) display messages
optimizeSparseness

logical (default=TRUE) whether to run the sparseness optimization routine. If FALSE, the default sparseness value will be used. If sparseness is manually defined this flag decides if cross validated correlations will be computed for the defined sparseness.
validateSparseness

logical (conditional default=TRUE) If sparseness is manually defined, this flag decides if cross validated correlations will be computed for the defined sparseness.
pThreshold

(default=0.05) If cross validated correlations show significance below this value the results are considered null and an empty map is returned.
mycoption

(default=1) SCCAN parameter, see sparseDecom2
robust

(ddefault=1) SCCAN parameter, see sparseDecom2
sparseness

(default=1) SCCAN parameter. Decides the proportion of voxels that will receive a non-zero weight. A positive sparseness will force the solution of each component to be one sided, i.e., voxels cannot have both positive and negative weights. A negative sparseness allows dual sided solution, where some voxels can have positive weights and other voxels can have negative weights. Setting sparseness manually without running the optimization routing is not recommended. For more, see sparseDecom2.
sparseness.behav

SCCAN parameter, what sparsness to use for behavioral scores. Useful only if multiple behavioral scores are passed. This argument is not optimized, you should not change it if you are not familiar with SCCAN.
nvecs

(default=1) SCCAN parameter. Normally only one eigenvector of weights is obtained in LESYMAP. Multiple maps/eigenvectors can be retrieved for mapping full deficit profiles in the future. For more, see sparseDecom2
cthresh

(default=150) SCCAN parameter, see sparseDecom2
its

(default=20) SCCAN parameter, see sparseDecom2
npermsSCCAN

(default=0) SCCAN permutations. In theory can be used to determine if the cross-correlation between the two sides (behavior and lesions) is not random. However, LESYMAP uses k-fold validations, which are faster; this option has not been tested. For more, see sparseDecom2.
smooth

(default=0.4) SCCAN parameter. Determines the amount of smoothing of weights in image space performed by sparseDecom2. The current default value is somewhat arbitrary, it was not determined through systematic simulations.
maxBased

(default=FALSE) SCCAN parameter. Removes voxels with weights smaller than 10% of the peak weight during internal SCCAN iterations. Although similar to what is done in LESYMAP with standard SCCAN results, this strategy follows a different route, and produces different weights. The overall final result is, however, quite similar. This method is faster then the standard SCCAN call in LESYMAP, but has not been tested thoroughly. Note that the optimal sparseness obtained with maxBased=TRUE is not optimal when switching to maxBased=FALSE.
directionalSCCAN

(default=TRUE) If TRUE, the upper and lower bounds of sparseness search will be negative. A negative sparseness permits positive and negative voxel weights, thus finding the direction of the relationship with behavior.
...

other arguments received from lesymap.

Value

List of objects returned:

  • statistic - vector of statistical values

  • pvalue - vector of pvalues

  • rawWeights.img - image with raw SCCAN voxel weights

  • sccan.eig2 - SCCAN weight(s) for behavior column(s).

  • sccan.ccasummary - SCCAN summary of projection correlations and permutation-derived pvalues

  • optimalSparseness - (if optimizeSparseness=TRUE) optimal value found for sparseness

  • CVcorrelation.stat - (if optimizeSparseness=TRUE) Correlation between true and predicted score with k-fold validation using the optimal sparseness value

  • CVcorrelation.pval - (if optimizeSparseness=TRUE) p-value of the above correlation

  • sccan.behavior.scaleval - scaling value for behavior

  • sccan.behavior.centerval - center value for behavior

  • sccan.lesmat.scaleval - scaling value for lesion matrix

  • sccan.lesmat.centerval - center value for lesion matrix

Examples

{
 if (FALSE) {
  lesydata = file.path(find.package('LESYMAP'),'extdata')
  filenames = Sys.glob(file.path(lesydata, 'lesions', '*.nii.gz'))
  behavior = Sys.glob(file.path(lesydata, 'behavior', 'behavior.txt'))
  behavior = read.table(behavior,header=FALSE)[,1]
  avg = antsAverageImages(filenames)
  mask = thresholdImage(avg, 0.1, Inf)
  lesmat = imagesToMatrix(filenames,mask)
  result = lsm_sccan(lesmat, behavior,
       optimizeSparseness=F, sparseness=0.8, mask = mask)
 }
}