Working with ROIs (Freesurfer) - Revision history

Chris: /* AnchorBar */

2022-08-17T20:13:04Z

AnchorBar

← Older revision		Revision as of 16:13, 17 August 2022
Line 9:		Line 9:

	=AnchorBar=		=AnchorBar=
	All the procedures and code lower down on the page have been replaced with a handy Python tool called AnchorBar (aka "Analyzer"), which maintains a sqlite3 database of annotations in template space. The program allows the user to add new annotations to the database and compute set operations on the stored annotations to create new annotation schemes; for example dividing functional clusters along anatomical boundaries.		All the procedures and code lower down on the page have been replaced with a handy Python tool called [[AnchorBar]] (aka "Analyzer"), which maintains a sqlite3 database of annotations in template space. The program allows the user to add new annotations to the database and compute set operations on the stored annotations to create new annotation schemes; for example dividing functional clusters along anatomical boundaries.

	==Adding Annotations to the AnchorBar database==		==Adding Annotations to the AnchorBar database==
Line 15:		Line 15:

	See also: [[Working with Subcortical ROIs (Freesurfer)]]		See also: [[Working with Subcortical ROIs (Freesurfer)]]

	= Old Information =		= Old Information =
	The information below this point is accurate, but is largely obsolete. I couldn't bring myself to just delete it all because you never know when it'll be handy to know some of this stuff.		The information below this point is accurate, but is largely obsolete. I couldn't bring myself to just delete it all because you never know when it'll be handy to know some of this stuff.

Chris at 20:08, 17 August 2022

2022-08-17T20:08:21Z

← Older revision		Revision as of 16:08, 17 August 2022
Line 4:		Line 4:
	Group-level contrast maps, generated by [[Mri_glmfit]] are well-suited for generating a set of ROIs that are appropriate for use across the set of participants entered into the group-level analysis. They have the useful property of being spatially consistent across all participants. There are a couple things to note, however. The first is that there must first be a sufficient number of participants to produce statistically significant contrast clusters. The second is that the group-level analysis must be done in fsaverage space. If the data you wish to explore is in native '''self''' space, you would need to map the ROIs back to a subject's native surface space. Note that this is not a strong consideration, given that you would have had to have preprocessed and analyzed individuals in fsaverage space in order to produce group-level contrast maps, so I cannot imagine a situation that would absolutely ''require'' you to map ROIs to native space.		Group-level contrast maps, generated by [[Mri_glmfit]] are well-suited for generating a set of ROIs that are appropriate for use across the set of participants entered into the group-level analysis. They have the useful property of being spatially consistent across all participants. There are a couple things to note, however. The first is that there must first be a sufficient number of participants to produce statistically significant contrast clusters. The second is that the group-level analysis must be done in fsaverage space. If the data you wish to explore is in native '''self''' space, you would need to map the ROIs back to a subject's native surface space. Note that this is not a strong consideration, given that you would have had to have preprocessed and analyzed individuals in fsaverage space in order to produce group-level contrast maps, so I cannot imagine a situation that would absolutely ''require'' you to map ROIs to native space.

			=Working From Existing Labels=
			The other primary source of ROIs come from anatomical labels provided in the <code>fsaverage/label/</code> folder. Because the folder in the FreeSurfer install directory is owned by root, you won't be able to add new labels to this folder. Instead, you should make a copy of the fsaverage folder in your project directory:
			cp -r $FREESURFER_HOME/subjects/fsaverage $SUBJECTS_DIR

			=AnchorBar=
			All the procedures and code lower down on the page have been replaced with a handy Python tool called AnchorBar (aka "Analyzer"), which maintains a sqlite3 database of annotations in template space. The program allows the user to add new annotations to the database and compute set operations on the stored annotations to create new annotation schemes; for example dividing functional clusters along anatomical boundaries.

			==Adding Annotations to the AnchorBar database==
			The initial AnchorBar annotation database is called annot.db, and has been populated with standard FreeSurfer annotations.

	See also: [[Working with Subcortical ROIs (Freesurfer)]]		See also: [[Working with Subcortical ROIs (Freesurfer)]]

Chris at 16:29, 14 April 2022

2022-04-14T16:29:08Z

← Older revision		Revision as of 12:29, 14 April 2022
Line 1:		Line 1:
	This page seriously needs to be reorganized. It documents some procedures that were developed before we figured out better ways to do some things, and so it may be more confusing than helpful.		This page seriously needs to be reorganized. It documents some procedures that were developed before we figured out better ways to do some things, and so it may be more confusing than helpful.

			=Working From Group-Level Results=
			Group-level contrast maps, generated by [[Mri_glmfit]] are well-suited for generating a set of ROIs that are appropriate for use across the set of participants entered into the group-level analysis. They have the useful property of being spatially consistent across all participants. There are a couple things to note, however. The first is that there must first be a sufficient number of participants to produce statistically significant contrast clusters. The second is that the group-level analysis must be done in fsaverage space. If the data you wish to explore is in native '''self''' space, you would need to map the ROIs back to a subject's native surface space. Note that this is not a strong consideration, given that you would have had to have preprocessed and analyzed individuals in fsaverage space in order to produce group-level contrast maps, so I cannot imagine a situation that would absolutely ''require'' you to map ROIs to native space.


	See also: [[Working with Subcortical ROIs (Freesurfer)]]		See also: [[Working with Subcortical ROIs (Freesurfer)]]
			= Old Information =
			The information below this point is accurate, but is largely obsolete. I couldn't bring myself to just delete it all because you never know when it'll be handy to know some of this stuff.

	The .label files created during autorecon3, or by saving an overlay are plaintext lists of vertices. It should be straightforward to find the intersection or union of the vertices in two or more .label files using common Unix shell commands.		The .label files created during autorecon3, or by saving an overlay are plaintext lists of vertices. It should be straightforward to find the intersection or union of the vertices in two or more .label files using common Unix shell commands.

	= .label Syntax =		== .label Syntax ==
	Below is the first few lines of the lh.banksts.label file for a participant. This file was produced during the Lausanne parcellation procedure.		Below is the first few lines of the lh.banksts.label file for a participant. This file was produced during the Lausanne parcellation procedure.
	#!ascii label , from subject FS_0043 vox2ras=TkReg		#!ascii label , from subject FS_0043 vox2ras=TkReg
Line 19:		Line 25:
	The first line is a header line. The second line indicates the number of vertices in the label file. The remaining lines indicate the vertex number, x,y,z coordinates of the vertex, and I have no idea what that last column indicates but it's not terribly important for our purposes.		The first line is a header line. The second line indicates the number of vertices in the label file. The remaining lines indicate the vertex number, x,y,z coordinates of the vertex, and I have no idea what that last column indicates but it's not terribly important for our purposes.

	=Working From Individual-Level Results=		==Working From Individual-Level Results==
	Running selxavg3-sess will produce some number of statistical contrast maps that can be loaded as an overlay in tksurfer. Significant clusters can be turned into ROIs for that particular individual in a series of steps. This has the advantage of being applicable to a single dataset -- there is no need to wait until sufficient fMRI data has been collected to produce significant group-level contrasts. The downside is that this is process has many steps.		Running selxavg3-sess will produce some number of statistical contrast maps that can be loaded as an overlay in tksurfer. Significant clusters can be turned into ROIs for that particular individual in a series of steps. This has the advantage of being applicable to a single dataset -- there is no need to wait until sufficient fMRI data has been collected to produce significant group-level contrasts. The downside is that this is process has many steps.

	== Load Overlay ==		=== Load Overlay ===
	The first step is to load up the participant's surface data and the desired overlay. Care must be taken in selecting a contrast overlay that is appropriate for the type of analysis that you eventually plan to do. As a rule of thumb, the overlay contrast should be orthogonal (i.e., completely independent) of the contrast that you are ultimately interested in. For example, if your goal is to compare mean signal strength for low- vs. high-familiar trials, it would be ''inappropriate'' to use the contrast of high-familiar.vs.low-familiar to generate ROIs from which to calculate the mean signal strength. The reason for this is that this contrast will be selecting voxels that have already been found to demonstrate a significant difference. Naturally, any analysis of familiarity effects on these voxels will be ''biased''! A more appropriate contrast to use would be something like task.vs.rest, which isn't biased towards either high or low-familiarity items, but is instead just showing the voxels that were more highly active during the task trials (which presumably contain equal numbers of high and low familiarity items).		The first step is to load up the participant's surface data and the desired overlay. Care must be taken in selecting a contrast overlay that is appropriate for the type of analysis that you eventually plan to do. As a rule of thumb, the overlay contrast should be orthogonal (i.e., completely independent) of the contrast that you are ultimately interested in. For example, if your goal is to compare mean signal strength for low- vs. high-familiar trials, it would be ''inappropriate'' to use the contrast of high-familiar.vs.low-familiar to generate ROIs from which to calculate the mean signal strength. The reason for this is that this contrast will be selecting voxels that have already been found to demonstrate a significant difference. Naturally, any analysis of familiarity effects on these voxels will be ''biased''! A more appropriate contrast to use would be something like task.vs.rest, which isn't biased towards either high or low-familiarity items, but is instead just showing the voxels that were more highly active during the task trials (which presumably contain equal numbers of high and low familiarity items).

	After the overlay is loaded, you may want to play around with the [https://surfer.nmr.mgh.harvard.edu/fswiki/TkSurferGuide/TkSurferWorkingWithData/TkSurferOverlay overlay configuration parameters]: for example you might choose to ''truncate'' your results to only show positive t-values, or modify your significance threshold.		After the overlay is loaded, you may want to play around with the [https://surfer.nmr.mgh.harvard.edu/fswiki/TkSurferGuide/TkSurferWorkingWithData/TkSurferOverlay overlay configuration parameters]: for example you might choose to ''truncate'' your results to only show positive t-values, or modify your significance threshold.

	==Save Clusters as Labels==		===Save Clusters as Labels===
	Now comes the somewhat tedious part of individually converting each cluster into a .label file. This simple but repetitive process is described [https://surfer.nmr.mgh.harvard.edu/fswiki/CreatingROIs here] and you can get pretty quick at it:		Now comes the somewhat tedious part of individually converting each cluster into a .label file. This simple but repetitive process is described [https://surfer.nmr.mgh.harvard.edu/fswiki/CreatingROIs here] and you can get pretty quick at it:
	#If you wish to subdivide a large cluster, first create one or more paths that completely cross (e.g., bisect) the cluster.		#If you wish to subdivide a large cluster, first create one or more paths that completely cross (e.g., bisect) the cluster.
Line 40:		Line 46:
	#*Click OK		#*Click OK

	== Merge .label Files ==		=== Merge .label Files ===
	If you wish to work with the resulting .label files individually, your work is done. However, if you wish to merge multiple clusters into a single .annot file, you have to first create a color table which is called by <code>mris_label2annot</code>.		If you wish to work with the resulting .label files individually, your work is done. However, if you wish to merge multiple clusters into a single .annot file, you have to first create a color table which is called by <code>mris_label2annot</code>.
	=== Create a CTAB File ===		=== Create a CTAB File ===
Line 84:		Line 90:
	Note that the above command is the syntax used when you have an ''unknown'' label and corresponding entry in your CTAB file. If you do not wish to include the unknown label, rather than assign index 0 to the unknown label, start your CTAB index numbering at 0 for the first real label, and use the <code>--no-unknown</code> command-line argument when calling <code>mris_label2annot</code>. I didn't remember this being a problem the first time I tried this, but when I just went through this process again, it seemed that the CTAB index needed to start at 0, but I couldn't have index 0 associated with unknown if there was not an ''?h.unknown.label'' file, even when using the --no-unknown switch. When I edited the ctab files to have index 0, 1, ... , n-1 corresponding with label_001, label_002, ... , label_n, then everything seemed to work fine.		Note that the above command is the syntax used when you have an ''unknown'' label and corresponding entry in your CTAB file. If you do not wish to include the unknown label, rather than assign index 0 to the unknown label, start your CTAB index numbering at 0 for the first real label, and use the <code>--no-unknown</code> command-line argument when calling <code>mris_label2annot</code>. I didn't remember this being a problem the first time I tried this, but when I just went through this process again, it seemed that the CTAB index needed to start at 0, but I couldn't have index 0 associated with unknown if there was not an ''?h.unknown.label'' file, even when using the --no-unknown switch. When I edited the ctab files to have index 0, 1, ... , n-1 corresponding with label_001, label_002, ... , label_n, then everything seemed to work fine.

	~~=Working From Group-Level Results=~~
	Group-level contrast maps, generated by [[Mri_glmfit]] are well-suited for generating a set of ROIs that are appropriate for use across the set of participants entered into the group-level analysis. They have the useful property of being spatially consistent across all participants. There are a couple things to note, however. The first is that there must first be a sufficient number of participants to produce statistically significant contrast clusters. The second is that the group-level analysis must be done in fsaverage space. If the data you wish to explore is in native '''self''' space, you would need to map the ROIs back to a subject's native surface space. Note that this is not a strong consideration, given that you would have had to have preprocessed and analyzed individuals in fsaverage space in order to produce group-level contrast maps, so I cannot imagine a situation that would absolutely ''require'' you to map ROIs to native space.

	==Preparation of .label Files==		==Preparation of .label Files==

Chris: /* You're Going to Want to Turn These into an .annot File */

2020-05-24T03:06:46Z

You're Going to Want to Turn These into an .annot File

← Older revision		Revision as of 23:06, 23 May 2020
Line 136:		Line 136:
	The above two commands will generate my lh and rh label files in the current working directory (assumed to be ${SUBJECTS_DIR}/${SUBJECT}/label; ${SUBJECT} is likely to be fsaverage if you are making a functional mask from group-level analyses in fsaverage space).		The above two commands will generate my lh and rh label files in the current working directory (assumed to be ${SUBJECTS_DIR}/${SUBJECT}/label; ${SUBJECT} is likely to be fsaverage if you are making a functional mask from group-level analyses in fsaverage space).
	===You're Going to Want to Turn These into an .annot File===		===You're Going to Want to Turn These into an .annot File===
	After you've merged multiple .label files into a single .label file, all the vertices will be assigned to the same label. You will probably want to go through and relabel each of the distinct regions (e.g., by cluster) in FreeSurfer. After you've done that, save (export) each of the relabeled regions as separate .label files (e.g., CLUST_01, CLUST_02, ... etc.) in a working directory. ~~We'll be creating~~ a CLUT ~~table so that we can then~~ merge ~~them all~~ into a single .annot file.		After you've merged multiple .label files into a single .label file, all the vertices will be assigned to the same label. You will probably want to go through and relabel each of the distinct regions (e.g., by cluster) in FreeSurfer. After you've done that, save (export) each of the relabeled regions as separate .label files (e.g., CLUST_01, CLUST_02, ... etc.) in a working directory.

			After you do, you need to create or snag a CLUT file.

			Finally, you use mris_label2annot to merge your united labels, along with the CLUT into a single .annot file.

	=ROI 'VennDiagram' Matlab Function=		=ROI 'VennDiagram' Matlab Function=

Chris: /* Merging .label Files (Union) */

2020-05-24T01:48:36Z

Merging .label Files (Union)

← Older revision		Revision as of 21:48, 23 May 2020
Line 135:		Line 135:
	mri_mergelabels -d rh -o rh.AB_UNION.label		mri_mergelabels -d rh -o rh.AB_UNION.label
	The above two commands will generate my lh and rh label files in the current working directory (assumed to be ${SUBJECTS_DIR}/${SUBJECT}/label; ${SUBJECT} is likely to be fsaverage if you are making a functional mask from group-level analyses in fsaverage space).		The above two commands will generate my lh and rh label files in the current working directory (assumed to be ${SUBJECTS_DIR}/${SUBJECT}/label; ${SUBJECT} is likely to be fsaverage if you are making a functional mask from group-level analyses in fsaverage space).
			===You're Going to Want to Turn These into an .annot File===
			After you've merged multiple .label files into a single .label file, all the vertices will be assigned to the same label. You will probably want to go through and relabel each of the distinct regions (e.g., by cluster) in FreeSurfer. After you've done that, save (export) each of the relabeled regions as separate .label files (e.g., CLUST_01, CLUST_02, ... etc.) in a working directory. We'll be creating a CLUT table so that we can then merge them all into a single .annot file.

	=ROI 'VennDiagram' Matlab Function=		=ROI 'VennDiagram' Matlab Function=

Chris: /* Breaking Up .annot into multiple .label Files */

2020-05-24T01:08:54Z

Breaking Up .annot into multiple .label Files

← Older revision		Revision as of 21:08, 23 May 2020
Line 113:		Line 113:
	mri_annotation2label --subject fsaverage --hemi lh --outdir LDT.lh --annotation lh.ldt_hi.annot		mri_annotation2label --subject fsaverage --hemi lh --outdir LDT.lh --annotation lh.ldt_hi.annot
	This command created a new subdirectory (LDT.lh), and broke up the ld.ldt_hi.annot into its constituent label files, placing them in the subdirectory.		This command created a new subdirectory (LDT.lh), and broke up the ld.ldt_hi.annot into its constituent label files, placing them in the subdirectory.

	'''Note: when working with functional contrast map annotation files, the output files will be called ?h.cluster-nnn.label. If you convert multiple .annot files for the same hemisphere (e.g., from two separate contrasts) with the intention of later merging them, you will run the risk of overwriting earlier .label files unless you take care to rename them as you go.'''		'''Note: when working with functional contrast map annotation files, the output files will be called ?h.cluster-nnn.label. If you convert multiple .annot files for the same hemisphere (e.g., from two separate contrasts) with the intention of later merging them, you will run the risk of overwriting earlier .label files unless you take care to rename them as you go.'''

Chris: /* Breaking Up .annot into multiple .label Files */

2020-05-24T01:08:38Z

Breaking Up .annot into multiple .label Files

← Older revision		Revision as of 21:08, 23 May 2020
Line 110:		Line 110:
	SURF=orig		SURF=orig
	mri_annotation2label --annotation ${ANNOT} --hemi ${HEMI} --subject fsaverage --surf ${SURF} --labelbase ${HEMI}.${BASE_LABEL_NAME}		mri_annotation2label --annotation ${ANNOT} --hemi ${HEMI} --subject fsaverage --surf ${SURF} --labelbase ${HEMI}.${BASE_LABEL_NAME}
			Alternatively, you might want to dump all your .label files into a single output directory. Instead of supplying a labelbase, you specify an output dir (''outdir''):
			mri_annotation2label --subject fsaverage --hemi lh --outdir LDT.lh --annotation lh.ldt_hi.annot
			This command created a new subdirectory (LDT.lh), and broke up the ld.ldt_hi.annot into its constituent label files, placing them in the subdirectory.
			'''Note: when working with functional contrast map annotation files, the output files will be called ?h.cluster-nnn.label. If you convert multiple .annot files for the same hemisphere (e.g., from two separate contrasts) with the intention of later merging them, you will run the risk of overwriting earlier .label files unless you take care to rename them as you go.'''

	=Set Operations on .label Files=		=Set Operations on .label Files=

Chris: /* CTAB and Annot */

2020-04-23T15:11:57Z

CTAB and Annot

← Older revision		Revision as of 11:11, 23 April 2020
Line 277:		Line 277:
	If you don't have a ton of labels, this can easily be done by hand by copying and editing the 'FreeSurferColorLUT.txt' file found in /usr/local/freesurfer, and simply renaming the regions(label names) to match your labelling convention. Then save it as a .annot.ctab file, e.g. 'RH.annot.ctab'.		If you don't have a ton of labels, this can easily be done by hand by copying and editing the 'FreeSurferColorLUT.txt' file found in /usr/local/freesurfer, and simply renaming the regions(label names) to match your labelling convention. Then save it as a .annot.ctab file, e.g. 'RH.annot.ctab'.

	Then you'll want to use the mris_label2annot command found [https://surfer.nmr.mgh.harvard.edu/fswiki/mris_label2annot here]. Example:		Then you'll want to use the mris_label2annot command found [https://surfer.nmr.mgh.harvard.edu/fswiki/mris_label2annot here]. There are 2 ways to do this. The first is to pass it each of the label files using the--l switch, and a ctab fie. Example:

	mris_label2annot --l rh.label-001.txt --l rh.label-002.txt --l rh.label-003.txt --l rh.label-004.txt --l rh.label-005.txt --l rh.label-006.txt --l rh.label-007.txt --l rh.label-008.txt --l rh.label-009.txt --l rh.label-010.txt --l rh.label-011.txt --l rh.label-012.txt --l rh.label-013.txt --l rh.label-014.txt --l rh.label-015.txt --l rh.label-016.txt --l rh.label-017.txt --l rh.label-018.txt --l rh.label-019.txt --l rh.label-020.txt --l rh.label-021.txt --l rh.label-022.txt --l rh.label-023.txt --l rh.label-024.txt --l rh.label-025.txt --l rh.label-026.txt --ctab RH.annot.ctab --s fsaverage --h rh --annot T1T2intersected		mris_label2annot --l rh.label-001.txt --l rh.label-002.txt --l rh.label-003.txt --l rh.label-004.txt --l rh.label-005.txt --l rh.label-006.txt --l rh.label-007.txt --l rh.label-008.txt --l rh.label-009.txt --l rh.label-010.txt --l rh.label-011.txt --l rh.label-012.txt --l rh.label-013.txt --l rh.label-014.txt --l rh.label-015.txt --l rh.label-016.txt --l rh.label-017.txt --l rh.label-018.txt --l rh.label-019.txt --l rh.label-020.txt --l rh.label-021.txt --l rh.label-022.txt --l rh.label-023.txt --l rh.label-024.txt --l rh.label-025.txt --l rh.label-026.txt --ctab RH.annot.ctab --s fsaverage --h rh --annot T1T2intersected

			That's unwieldy (and yet, that's how I first did this). The easier way is to throw all the label files into a single directory, and pass the directory and a ctab file.

	Now that you have .annot files for your intersecting vertices, you can [http://ccnlab.psy.buffalo.edu/wiki/index.php/Freesurfer_Subparcellation#Transfer_Subparcellation_to_Other_Subjects, subparcellate] and/or continue with network analyses.		Now that you have .annot files for your intersecting vertices, you can [http://ccnlab.psy.buffalo.edu/wiki/index.php/Freesurfer_Subparcellation#Transfer_Subparcellation_to_Other_Subjects, subparcellate] and/or continue with network analyses.

Chris: /* Using R to Work With Colortables */

2020-03-31T15:26:53Z

Using R to Work With Colortables

← Older revision		Revision as of 11:26, 31 March 2020
Line 284:		Line 284:

	==Using R to Work With Colortables==		==Using R to Work With Colortables==
	This is kind of a stub topic, but ~~I just discovered~~ an R library when trying to extract a CLUT from an existing .annot file~~. One of the freesurfer guys wrote a tool to do this using Linux, but that doesn't help much on my MacOS laptop. It turns out some folks have written some R utilities for working with FreeSurfer~~. I introduce the [https://rdrr.io/cran/freesurferformats/ freesurferformats R package]. In particular, there is a function to extract the color lookup table from a .annot file:		This is kind of a stub topic, but there is an R library when trying to extract a CLUT from an existing .annot file. I introduce the [https://rdrr.io/cran/freesurferformats/ freesurferformats R package]. In particular, there is a function to extract the color lookup table from a .annot file:
	> library("freesurferformats")		> library("freesurferformats")
	> annotfile="/path/to/subject/label/lh.myannot.annot"		> annotfile="/path/to/subject/label/lh.myannot.annot"
Line 290:		Line 290:
	> colortable = colortable.from.annot(annot);		> colortable = colortable.from.annot(annot);
	> head(colortable);		> head(colortable);

			If you install this library, you can use [[Extracting CLUT from .annot Files Using R\|this handy R script]] that I wrote that can be run from the terminal to extract a CLUT from a .annot file.

	[[Category: FreeSurfer]]		[[Category: FreeSurfer]]
	[[Category: ROI]]		[[Category: ROI]]

Chris: /* Intersecting .label Files (Intersection) */

2020-03-29T23:30:43Z

Intersecting .label Files (Intersection)

← Older revision		Revision as of 19:30, 29 March 2020
Line 115:		Line 115:
	Given what we know about the contents of a label file, the unix <code>comm</code> command should suffice to find the common entries between two label files, which is the set intersection of vertices appearing in each.		Given what we know about the contents of a label file, the unix <code>comm</code> command should suffice to find the common entries between two label files, which is the set intersection of vertices appearing in each.

	https://mail.nmr.mgh.harvard.edu/~~pipermail//freesurfer/2009-August/011743~~.html		[https://www.mail-archive.com/freesurfer@nmr.mgh.harvard.edu/msg11344.html Relevant thread here]

	==Merging .label Files (Union)==		==Merging .label Files (Union)==