lsm_sccan: Sparse canonical correlations for symptom mapping
In neuroconductor/LESYMAP: Lesion to Symptom Mapping in R

Description Usage Arguments Value Author(s) Examples

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, ...)

`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`.

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

Dorian Pustina

{
 ## Not run: 
  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)
 
## End(Not run)
}