genVSM - generate a visual sign map and cortical-area ROIs
Creates a visual sign map from azimuth and elevation maps and writes detected cortical patches to a DataViewer-compatible .roi file.
Syntax
[outData, roiFile] = genVSM(retinotopyUMT, SaveFolder)
[outData, roiFile] = genVSM(retinotopyUMT, SaveFolder, 'Name', Value)Description
This function uses the azimuth and elevation phase maps created by genRetinotopyMaps to create a visual sign map (VSM). It always attempts to segment the VSM into connected cortical patches. When patches are detected, each patch is stored as a canonical ROI named CtxArea_<index>, for example CtxArea_1, in a .roi file that can be opened in DataViewer.
Input
- retinotopyUMT - Name or path of the .umt file written by genRetinotopyMaps (default retinotopyMaps.umt); a bare name is also looked up in SaveFolder. Only that output is accepted: an image UMT with exactly two entries, AzimuthMap and ElevationMap, each with dimensions {'Y','X','F'} and two slices: amplitude in slice 1 and phase in slice 2. UMT structs in memory, numeric arrays and other files are not supported, and maps created with Direction set to Azimuth_only or Elevation_only cannot be used.
- SaveFolder - Folder used to resolve input masks and save the generated ROI file.
The algorithm
In brief, the visual sign map is calculated as the sine of the difference between the gradients of the azimuth and elevation phase maps. The function then segments the map into connected patches and converts each patch into an ROI. This function uses the algorithm described by Sereno et al. [1,2] and Garrett et al. [3].
Output
- outData - An image UMT containing a single entry named VSM with dimensions {'Y','X'}. The default pipeline output filename is visualSignMap.umt. The output is derived exclusively from the retinotopy UMT input.
- roiFile - The folder-relative name of the created .roi file. The default is VisualCtxAreas.roi. If no patches are detected, the function issues a warning, returns an empty character vector, and does not create or overwrite an ROI file.
The generated file contains one ROI per connected patch, named CtxArea_1, CtxArea_2, and so on. These names identify segmented regions; they do not assign anatomical area identities. Open the file from the DataViewer ROIs tab. See ROI files organization for the file format and ROI management in DataViewer for the user workflow.
When genVSM runs through PipelineManager, the ROI output is optional: it is recorded in the output manifest only when a file was created during that run.
Parameters
The parameters of this function are the following:
Standard deviation of the Gaussian spatial filter, in pixels, applied to the azimuth and elevation phase maps before calculating the VSM. Set to 0 to skip filtering.
Standard deviation of the Gaussian spatial filter, in pixels, applied to the visual sign map before segmentation. Set to 0 to skip filtering.
Name of the DataViewer-compatible .roi file saved in SaveFolder. Supply a filename only, without folder components. The .roi extension is appended when omitted; other extensions are rejected.
Set to true to use a logical mask stored in a variable named logical_mask in a .mat file. The mask excludes non-pertinent areas of the visual sign map before segmentation.
Name or path of the .mat file containing logical_mask. A filename without folder components is resolved relative to SaveFolder.
API change: b_CreatePatches and PatchFileName have been removed. ROI creation is now always attempted, and ROIFileName controls the canonical .roi output filename.
References
- Sereno, M. I., A. M. Dale, J. B. Reppas, K. K. Kwong, J. W. Belliveau, T. J. Brady, B. R. Rosen, and R. B. Tootell. 1995. ‘Borders of Multiple Visual Areas in Humans Revealed by Functional Magnetic Resonance Imaging’. Science (New York, N.Y.) 268 (5212): 889–93.https://doi.org/10.1126/science.7754376.
- Sereno, Martin I., Colin T. McDonald, and John M. Allman. 1994. ‘Analysis of Retinotopic Maps in Extrastriate Cortex’. Cerebral Cortex 4 (6): 601–20. https://doi.org/10.1093/cercor/4.6.601.
- Garrett, Marina E., Ian Nauhaus, James H. Marshel, and Edward M. Callaway. 2014. ‘Topography and Areal Organization of Mouse Visual Cortex’. The Journal of Neuroscience 34 (37): 12587–600. https://doi.org/10.1523/JNEUROSCI.1124-14.2014.