Add assessment of spatial coverage within both fMRIVolume and fMRISurface

[mharms]

This PR is intended to address #132. This functionality is a necessary addition before we start HCP-D/A processing.

Some minor readability improvements and comment additions are included for the affected scripts as well.

[coalsont]

I'm not particularly fond of having an internal aspect of the data determine whether an output file gets generated. If we added some automated fix for the zeros (more dilation), having the mask of zeros exist regardless of whether it is empty might make the code simpler.

[mharms]

I did that here because due to the dilation, zeros in the CIFTI should be rare and the *_nonzero.stats.txt is written out regardless, so that provides the "evidence" that the check was performed on a particular set of processed data. That said, if you and @glasserm prefer that we write out the *_nonzero.dscalar.nii file regardless, I can do that.

I don't see how adding more dilation impacts whether or not we should write out the map of nonzero grayordinates. At some point, we can't just keep dilating, and frankly it seems like we already have a lot of dilation built in -- if I'm reading RibbonVolumeToSurfaceMapping correctly, we already dilate the "native" mesh data by 10 mm, and then dilate by 30 mm after we resample to the 32k_fsLR mesh.

Ideally, it would be great to have a dscalar that captures the grayordinates that contain "dilated" values themselves, but I don't know how easy that would be to implement...

[glasserm]

I prefer Mike's solution

[coalsont]

I don't know if this is correct.

[mharms]

Here are the inputs to OneStepResampling, from the call in GenericfMRIVolumeProcessingPipeline:

${RUN} ${PipelineScripts}/OneStepResampling.sh \
       --workingdir=${fMRIFolder}/OneStepResampling \
       --infmri=${fMRIFolder}/${OrigTCSName}.nii.gz \
       --t1=${AtlasSpaceFolder}/${T1wAtlasName} \
       --fmriresout=${FinalfMRIResolution} \
       --fmrifolder=${fMRIFolder} \
       --fmri2structin=${T1wFolder}/xfms/${fMRI2strOutputTransform} \
       --struct2std=${AtlasSpaceFolder}/xfms/${AtlasTransform} \
       --owarp=${AtlasSpaceFolder}/xfms/${OutputfMRI2StandardTransform} \
       --oiwarp=${AtlasSpaceFolder}/xfms/${Standard2OutputfMRITransform} \
       --motionmatdir=${fMRIFolder}/${MotionMatrixFolder} \
       --motionmatprefix=${MotionMatrixPrefix} \
       --ofmri=${fMRIFolder}/${NameOffMRI}_nonlin \
       --freesurferbrainmask=${AtlasSpaceFolder}/${FreeSurferBrainMask} \
       --biasfield=${AtlasSpaceFolder}/${BiasFieldMNI} \
       --gdfield=${fMRIFolder}/${NameOffMRI}_gdc_warp \
       --scoutin=${fMRIFolder}/${OrigScoutName} \
       --scoutgdcin=${fMRIFolder}/${ScoutName}_gdc \
       --oscout=${fMRIFolder}/${NameOffMRI}_SBRef_nonlin \
       --ojacobian=${fMRIFolder}/${JacobianOut}_MNI.${FinalfMRIResolution}

--freesurferbrainmask, --biasfield (and --t1) are all from ${AtlasSpaceFolder} ("MNINonLinear"). If it is somehow incorrect to refer to those inputs as "atlas (MNI152) space" rather than "T1w space" in the usage statement, I'll change it back, but if that's that case, would like to hear from @glasserm why my change is incorrect.

[coalsont]

I was not claiming it was wrong, just that I didn't know, and highlighting it so someone who did know would double-check.

[glasserm]

Mike seems correct

[glasserm]

I approve these changes provided they can be merged with Grega's pull requests. Mike please investigate this prior to merge.

[mharms]

@coalsont: In light of @glasserm's comments on this PR, do you give it your approval for merging?

[glasserm]

Mike, can this be merged with the other PRs?

[mharms]

It will have a merge conflict with #141, but that PR is a work-in-progress, and sounds like it might change considerably. My changes are relatively minor overall, so it shouldn't be hard for @sivcek to pull-in the new master, and work from there. In fact, I think it would be good if we get this merged in before he does anything else with that PR.

[sivcek]

Agreed.