Roi select - Revision history

Nathan Malkin: /* Compiling roi_select */ updated with new location of roi_select

2010-09-26T17:10:43Z

Compiling roi_select: updated with new location of roi_select

← Older revision		Revision as of 17:10, 26 September 2010
Line 38:		Line 38:
	To compile <tt>roi_select</tt>:		To compile <tt>roi_select</tt>:
	<pre>		<pre>
	cd $G/project/brain/roi_select		cd $G/project/brain/pipeline/streamline_processing/roi_select
	make all		make all
	</pre>		</pre>
	This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is probably to stick with the latest version (right now, GCC4). Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.		This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is probably to stick with the latest version (right now, GCC4). Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.


	==Installing roi_select as a library==		==Installing roi_select as a library==

Nathan Malkin: /* The ROI expression */

2010-07-12T16:18:49Z

The ROI expression

← Older revision		Revision as of 16:18, 12 July 2010
Line 137:		Line 137:

	==The ROI expression==		==The ROI expression==
	After you have defined the ROIs using the ''-roi_aa'' or ''-~~roi_nifti~~'' arguments, you tell the tool exactly which ROIs to check — and how — using the expression string (''-e'').		After you have defined the ROIs using the ''-roi_aa'', ''-roi_nifti'', or ''-roi_sphere'' arguments, you tell the tool exactly which ROIs to check — and how — using the expression string (''-e'').

	The expression string can be the name of just one ROI, or an arbitrarily complex boolean algebra expression using different kinds of ROIs, parentheses, and assorted NOTs, ANDs, ORs, and XORs.		The expression string can be the name of just one ROI, or an arbitrarily complex boolean algebra expression using different kinds of ROIs, parentheses, and assorted NOTs, ANDs, ORs, and XORs.
Line 164:		Line 164:
	{{infobox\|'''Avoid errors:''' operators, even the symbolic ones, need to be separated from ROI names by spaces. <br />		{{infobox\|'''Avoid errors:''' operators, even the symbolic ones, need to be separated from ROI names by spaces. <br />
	For example: <code>... -e "a&b"</code> is invalid syntax; use <code>... -e "a & b"</code> instead}}		For example: <code>... -e "a&b"</code> is invalid syntax; use <code>... -e "a & b"</code> instead}}



	=Usage examples=		=Usage examples=

Nathan Malkin: added spherical ROIs

2010-07-12T15:59:44Z

added spherical ROIs

@@ Line 97: / Line 97: @@
 ||
 The first argument is the name by which you refer to this ROI in the expression. <br />
-The rest are the filename and the region (bitmap number) that define this '''[[#NIfTI Bitmap ROI|NIfTI Bitmap ROI]]
+The rest are the filename and the region (bitmap number) that define this '''[[#NIfTI Bitmap ROI|NIfTI Bitmap ROI]].
 |}
@@ Line 118: / Line 128: @@
 If you want to select multiple regions from a single file, you will have to define them as separate ROIs. However, if you want the program to use '''all''' the ROIs in a given file (an ''or'' of all regions), you can just specify the ROI number as <tt>-1</tt>.

Nathan Malkin: wording & formatting changes

2010-07-08T17:41:18Z

wording & formatting changes

← Older revision		Revision as of 17:41, 8 July 2010
Line 4:		Line 4:

	=Introduction=		=Introduction=
	After we run DTI data through a pipeline (whether [[Diffusion Processing Pipeline\|our in-house one]] or a third-party one, such as [http://www.trackvis.org/dtk/ DTK]), we ~~may be~~ left with data for hundreds of thousands of streamlines. Often times, however, we are interested in only a small subset of that data. We may be working with a specific structure in the brain and would like to see a visualization of only that structure. Or we may be interested in a particular region and would like to compute statistics about the streamlines that pass through that region. Perhaps we want to see how many streamlines connect two distinct regions and what paths they take. The <tt>roi_select</tt> tool can help achieve these goals.		After we run DTI data through a pipeline (whether [[Diffusion Processing Pipeline\|our in-house one]] or a third-party one, such as [http://www.trackvis.org/dtk/ DTK]), we are left with data for hundreds of thousands of streamlines. Often times, however, we are interested in only a small subset of that data. We may be working with a specific structure in the brain and would like to see a visualization of only that structure. Or we may be interested in a particular region and would like to compute statistics about the streamlines that pass through that region. Perhaps we want to see how many streamlines connect two distinct regions and what paths they take. The <tt>roi_select</tt> tool can help achieve these goals.


Line 10:		Line 10:
	==Dependencies==		==Dependencies==
	<tt>roi_select</tt> has two dependencies, both of which are located under [[$G]]:		<tt>roi_select</tt> has two dependencies, both of which are located under [[$G]]:
	# <tt>[[libcurvecollection]]</tt> — for file I/O and in-memory data handling		# <tt>[[libcurvecollection]]</tt> — for format interoperability, file I/O, and in-memory data handling
	# <tt>gg/args</tt> — for command-line argument processing		# <tt>gg/args</tt> — for command-line argument processing

Line 34:		Line 34:
	<blockquote>(see [[Check out projects\|more information]])</blockquote>		<blockquote>(see [[Check out projects\|more information]])</blockquote>

	==~~Installing~~ roi_select==
	To ~~install~~ <tt>roi_select</tt>:		==Compiling roi_select==
			To compile <tt>roi_select</tt>:
	<pre>		<pre>
	cd $G/project/brain/roi_select		cd $G/project/brain/roi_select
Line 42:		Line 43:
	This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is probably to stick with the latest version (right now, GCC4). Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.		This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is probably to stick with the latest version (right now, GCC4). Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.

	==~~Using~~ roi_select as a library==
	If you would like to expand on the functionality provided by <tt>roi_select</tt>, you can install it as a library. After compiling the source (see above), run the command <code>make install</code>. You will then be able to use it by including <code>#include <brain/roi_select.h></code> (and other header files) in your source ~~files~~.		==Installing roi_select as a library==
			If you would like to expand on the functionality provided by <tt>roi_select</tt>, you can install it as a library. After compiling the source (see above), run the command <code>make install</code>. You will then be able to use it by including <code>#include <brain/roi_select.h></code> (and other header files) in your source.



Line 59:		Line 62:
	The source file that contains the tracks that are to be selected.		The source file that contains the tracks that are to be selected.
	* Supported formats are .trk, .data, and .ccf.		* Supported formats are .trk, .data, and .ccf.
	* ~~It is recommended that you use~~ the absolute path to the file.		* This can be the absolute path to the file.
	\|-		\|-
	\| -o \|\| filename [string] \|\|		\| -o \|\| filename [string] \|\|
Line 67:		Line 70:
	\| -e \|\| expression [string] \|\| The ROI expression — [[#The_ROI_expression\|see explanation below]]		\| -e \|\| expression [string] \|\| The ROI expression — [[#The_ROI_expression\|see explanation below]]
	\|}		\|}


	==At least one of these arguments is required==		==At least one of these arguments is required==
Line 108:		Line 112:

	The coordinates of the vertices are in millimeters and must be in the same coordinate system (have the same origin) as the streamline vertices in the input file.		The coordinates of the vertices are in millimeters and must be in the same coordinate system (have the same origin) as the streamline vertices in the input file.


	===NIfTI Bitmap ROI===		===NIfTI Bitmap ROI===
Line 113:		Line 118:

	If you want to select multiple regions from a single file, you will have to define them as separate ROIs. However, if you want the program to use '''all''' the ROIs in a given file (an ''or'' of all regions), you can just specify the ROI number as <tt>-1</tt>.		If you want to select multiple regions from a single file, you will have to define them as separate ROIs. However, if you want the program to use '''all''' the ROIs in a given file (an ''or'' of all regions), you can just specify the ROI number as <tt>-1</tt>.


	==The ROI expression==		==The ROI expression==
Line 142:		Line 148:
	{{infobox\|'''Avoid errors:''' operators, even the symbolic ones, need to be separated from ROI names by spaces. <br />		{{infobox\|'''Avoid errors:''' operators, even the symbolic ones, need to be separated from ROI names by spaces. <br />
	For example: <code>... -e "a&b"</code> is invalid syntax; use <code>... -e "a & b"</code> instead}}		For example: <code>... -e "a&b"</code> is invalid syntax; use <code>... -e "a & b"</code> instead}}

Nathan Malkin: updated with functionality changes

2010-07-08T15:01:40Z

updated with functionality changes

← Older revision		Revision as of 15:01, 8 July 2010
Line 37:		Line 37:
	To install <tt>roi_select</tt>:		To install <tt>roi_select</tt>:
	<pre>		<pre>
	cd $G/project/brain/~~roi/select~~		cd $G/project/brain/roi_select
	make all		make all
	</pre>		</pre>
	This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is probably to stick with the latest version (right now, GCC4). Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.		This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is probably to stick with the latest version (right now, GCC4). Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.

			==Using roi_select as a library==
			If you would like to expand on the functionality provided by <tt>roi_select</tt>, you can install it as a library. After compiling the source (see above), run the command <code>make install</code>. You will then be able to use it by including <code>#include <brain/roi_select.h></code> (and other header files) in your source files.


Line 107:		Line 110:

	===NIfTI Bitmap ROI===		===NIfTI Bitmap ROI===
	'''NIfTI Bitmap ROIs''' are defined in [[NIfTI]] files. They use only three of the available dimensions and, for every voxel, store a 0 or a positive integer. A voxel with a zero value is not in any ROI. A voxel with value 1 is in ROI 1, value 2 means ROI 2, and so on. Therefore, a definition of a NIfTI Bitmap ROI consists of a filename and an integer — the particular ROI you are interested~~. If you want to select multiple regions from a single file, you will have to define them as separate ROIs~~.		'''NIfTI Bitmap ROIs''' are defined in [[NIfTI]] files. They use only three of the available dimensions and, for every voxel, store a 0 or a positive integer. A voxel with a zero value is not in any ROI. A voxel with value 1 is in ROI 1, value 2 means ROI 2, and so on. Therefore, a definition of a NIfTI Bitmap ROI consists of a filename and an integer — the particular ROI you are interested.

			If you want to select multiple regions from a single file, you will have to define them as separate ROIs. However, if you want the program to use '''all''' the ROIs in a given file (an ''or'' of all regions), you can just specify the ROI number as <tt>-1</tt>.

	==The ROI expression==		==The ROI expression==
Line 160:		Line 164:

	Selects the lines that pass through any of ROIs 1, 2, or 3, all of which are defined in the same file — roi.nii.gz.		Selects the lines that pass through any of ROIs 1, 2, or 3, all of which are defined in the same file — roi.nii.gz.


			<code>./roi_select-gcc4 -i input_file.trk -o output_file.trk -roi_nifti rois roi.nii.gz -1 -e rois</code>

			Selects all lines that pass through any of the ROIs defined in roi.nii.gz.

Nathan Malkin: User:Nathan Malkin/roi select moved to Roi select: roi_select is in $G and ready to be used!

2010-07-08T14:49:59Z

User:Nathan Malkin/roi select moved to Roi select: roi_select is in $G and ready to be used!

← Older revision	Revision as of 14:49, 8 July 2010
(No difference)

Nathan Malkin at 20:20, 2 July 2010

2010-07-02T20:20:01Z

← Older revision		Revision as of 20:20, 2 July 2010
Line 1:		Line 1:
	{{DISPLAYTITLE:roi_select}}		{{DISPLAYTITLE:roi_select}}
	~~<span style="color:red">{{infobox\|This page is incomplete and currently under development.}}</span>~~

	The '''Regions of Interest Selection Tool''' ('''<tt>roi_select</tt>''') is a command-line program that, when provided with a collection of curves, selects and outputs only the subset that passes through a particular region (or regions) of interest.		The '''Regions of Interest Selection Tool''' ('''<tt>roi_select</tt>''') is a command-line program that, when provided with a collection of curves, selects and outputs only the subset that passes through a particular region (or regions) of interest.

	=Introduction=		=Introduction=
	After we run DTI data through a pipeline (whether [[Diffusion Processing Pipeline\|our in-house one]] or a third-party one, such as [http://www.trackvis.org/dtk/ DTK]), we ~~are~~ left with data for hundreds of thousands of streamlines. Often times, however, we are interested in only a small subset of that data. We may be working with a specific structure in the brain and would like to see a visualization of only that structure. Or we may be interested in a particular region and would like to compute statistics about the streamlines that pass through that region. Perhaps we want to see how many streamlines connect two distinct regions and what paths they take. The <tt>roi_select</tt> tool can help achieve these goals.		After we run DTI data through a pipeline (whether [[Diffusion Processing Pipeline\|our in-house one]] or a third-party one, such as [http://www.trackvis.org/dtk/ DTK]), we may be left with data for hundreds of thousands of streamlines. Often times, however, we are interested in only a small subset of that data. We may be working with a specific structure in the brain and would like to see a visualization of only that structure. Or we may be interested in a particular region and would like to compute statistics about the streamlines that pass through that region. Perhaps we want to see how many streamlines connect two distinct regions and what paths they take. The <tt>roi_select</tt> tool can help achieve these goals.


	=Installation=		=Installation=
	==Dependencies==		==Dependencies==
	<tt>roi_select</tt> has two dependencies:		<tt>roi_select</tt> has two dependencies, both of which are located under [[$G]]:
	# <tt>[[libcurvecollection]]</tt> — for file I/O and in-memory data handling		# <tt>[[libcurvecollection]]</tt> — for file I/O and in-memory data handling
	# <tt>gg/args</tt> — for command-line argument processing		# <tt>gg/args</tt> — for command-line argument processing

	~~Both are located under [[$G]].~~ You will first need to [[Quick Start for CIT Users\|set up your sandbox]]. (You may be able to [[Automated Quick Start\|do it automatically]].)		You will first need to [[Quick Start for CIT Users\|set up your sandbox]]. (You may be able to [[Automated Quick Start\|do it automatically]].)

	To install <tt>libcurvecollection</tt>:		To install <tt>libcurvecollection</tt>:
Line 62:		Line 61:
	The output file, where the selected streamlines are to be written.		The output file, where the selected streamlines are to be written.
	* Supported formats are .trk, .data, and .ccf.		* Supported formats are .trk, .data, and .ccf.
	* It is recommended that you use the absolute path to the file.
	\|-		\|-
	\| -e \|\| expression [string] \|\| [[#The_ROI_expression\|~~See~~ explanation below]]		\| -e \|\| expression [string] \|\| The ROI expression — [[#The_ROI_expression\|see explanation below]]
	\|}		\|}

Line 149:		Line 147:


	<code>./roi_select-gcc4 -i input_file.trk -o output_file.trk -roi_aa myAAroi 0 0 0 123.456 12.345 1.234 -roi_nifti myNIfTIroi roi.nii.gz 1 -e "myAAroi or myNIfTIroi"</code>		<code>./roi_select-gcc4 -i input_file.trk -o output_file.trk -roi_aa myAAroi 0 0 0 123.456 12.345 1.234 -roi_nifti myNIfTIroi roi.nii.gz 1 -e "myAAroi OR myNIfTIroi"</code>

	Selects all the lines that pass through the region between (0,0,0) and (123.456, 12.345, 1.234) ''or'' through ROI 1 defined in roi.nii.gz.		Selects all the lines that pass through the region between (0,0,0) and (123.456, 12.345, 1.234) ''or'' through ROI 1 defined in roi.nii.gz.


	<code>./roi_select-gcc4 -i input_file.trk -o output_file.trk -roi_aa myAAroi 0 0 0 123.456 12.345 1.234 -roi_nifti myNIfTIroi roi.nii.gz 1 -roi_nifti anotherNIfTIroi roi2.nii.gz 3 -e "anotherNIfTIroi AND NOT (myAAroi or myNIfTIroi)"</code>		<code>./roi_select-gcc4 -i input_file.trk -o output_file.trk -roi_aa myAAroi 0 0 0 123.456 12.345 1.234 -roi_nifti myNIfTIroi roi.nii.gz 1 -roi_nifti anotherNIfTIroi roi2.nii.gz 3 -e "anotherNIfTIroi AND NOT (myAAroi OR myNIfTIroi)"</code>

	Selects all the lines that pass through ROI 3 defined in roi2.nii.gz ''but not'' through either of the regions in the previous example.		Selects all the lines that pass through ROI 3 defined in roi2.nii.gz ''but not'' through either of the regions in the previous example.

Nathan Malkin at 18:44, 2 July 2010

2010-07-02T18:44:57Z

@@ Line 41: / Line 41: @@
 make all
 </pre>
-This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is to stick with GCC4. Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.
+This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is probably to stick with the latest version (right now, GCC4). Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.
@@ Line 113: / Line 113: @@
 ==The ROI expression==

Nathan Malkin at 17:36, 2 July 2010

2010-07-02T17:36:26Z

← Older revision		Revision as of 17:36, 2 July 2010
Line 1:		Line 1:
			{{DISPLAYTITLE:roi_select}}
	<span style="color:red">{{infobox\|This page is incomplete and currently under development.}}</span>		<span style="color:red">{{infobox\|This page is incomplete and currently under development.}}</span>

Line 5:		Line 6:
	=Introduction=		=Introduction=
	After we run DTI data through a pipeline (whether [[Diffusion Processing Pipeline\|our in-house one]] or a third-party one, such as [http://www.trackvis.org/dtk/ DTK]), we are left with data for hundreds of thousands of streamlines. Often times, however, we are interested in only a small subset of that data. We may be working with a specific structure in the brain and would like to see a visualization of only that structure. Or we may be interested in a particular region and would like to compute statistics about the streamlines that pass through that region. Perhaps we want to see how many streamlines connect two distinct regions and what paths they take. The <tt>roi_select</tt> tool can help achieve these goals.		After we run DTI data through a pipeline (whether [[Diffusion Processing Pipeline\|our in-house one]] or a third-party one, such as [http://www.trackvis.org/dtk/ DTK]), we are left with data for hundreds of thousands of streamlines. Often times, however, we are interested in only a small subset of that data. We may be working with a specific structure in the brain and would like to see a visualization of only that structure. Or we may be interested in a particular region and would like to compute statistics about the streamlines that pass through that region. Perhaps we want to see how many streamlines connect two distinct regions and what paths they take. The <tt>roi_select</tt> tool can help achieve these goals.


	=Installation=		=Installation=
Line 40:		Line 42:
	</pre>		</pre>
	This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is to stick with GCC4. Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.		This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is to stick with GCC4. Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.


	=Using roi_select=		=Using roi_select=
Line 51:		Line 54:
	! {{Hl2}} \| Explanation		! {{Hl2}} \| Explanation
	\|-		\|-
	\| -i \|\| filename[string] \|\|		\| -i \|\| filename [string] \|\|
	The source file that contains the tracks that are to be selected.		The source file that contains the tracks that are to be selected.
	* Supported formats are .trk, .data, and .ccf.		* Supported formats are .trk, .data, and .ccf.
	* It is recommended that you use the absolute path to the file.		* It is recommended that you use the absolute path to the file.
	\|-		\|-
	\| -o \|\| filename[string] \|\|		\| -o \|\| filename [string] \|\|
	The output file, where the selected streamlines are to be written.		The output file, where the selected streamlines are to be written.
	* Supported formats are .trk, .data, and .ccf.		* Supported formats are .trk, .data, and .ccf.
	* It is recommended that you use the absolute path to the file.		* It is recommended that you use the absolute path to the file.
	\|-		\|-
	\| -e \|\| expression[string] \|\| [[#The_ROI_expression\|See explanation below]]		\| -e \|\| expression [string] \|\| [[#The_ROI_expression\|See explanation below]]
	\|}		\|}

Line 72:		Line 75:
	\|-		\|-
	\| -roi_aa \|\|		\| -roi_aa \|\|
	name[string] <br />		name [string] <br />
	x1[double] <br />		x1 [double] <br />
	y1[double] <br />		y1 [double] <br />
	z1[double] <br />		z1 [double] <br />
	x2[double] <br />		x2 [double] <br />
	y2[double] <br />		y2 [double] <br />
	z2[double]		z2 [double]
	\|\|		\|\|
	The first argument is the name by which you refer to this ROI in the expression. <br />		The first argument is the name by which you refer to this ROI in the expression. <br />
Line 84:		Line 87:
	\|-		\|-
	\| -roi_nifti \|\|		\| -roi_nifti \|\|
	name[string] <br />		name [string] <br />
	filename[string] <br />		filename [string] <br />
	region[int]		region [int]
	\|\|		\|\|
	The first argument is the name by which you refer to this ROI in the expression. <br />		The first argument is the name by which you refer to this ROI in the expression. <br />
Line 107:		Line 110:
	===NIfTI Bitmap ROI===		===NIfTI Bitmap ROI===
	'''NIfTI Bitmap ROIs''' are defined in [[NIfTI]] files. They use only three of the available dimensions and, for every voxel, store a 0 or a positive integer. A voxel with a zero value is not in any ROI. A voxel with value 1 is in ROI 1, value 2 means ROI 2, and so on. Therefore, a definition of a NIfTI Bitmap ROI consists of a filename and an integer — the particular ROI you are interested. If you want to select multiple regions from a single file, you will have to define them as separate ROIs.		'''NIfTI Bitmap ROIs''' are defined in [[NIfTI]] files. They use only three of the available dimensions and, for every voxel, store a 0 or a positive integer. A voxel with a zero value is not in any ROI. A voxel with value 1 is in ROI 1, value 2 means ROI 2, and so on. Therefore, a definition of a NIfTI Bitmap ROI consists of a filename and an integer — the particular ROI you are interested. If you want to select multiple regions from a single file, you will have to define them as separate ROIs.


	==The ROI expression==		==The ROI expression==

Nathan Malkin at 17:29, 2 July 2010

2010-07-02T17:29:46Z

@@ Line 39: / Line 39: @@
 make all
 </pre>
-This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best best is to stick with GCC4. Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.
+This will create a subdirectory <tt>obj</tt> with executables for each of the compilers supported under $G. Unless you have a compelling reason against doing so, your best bet is to stick with GCC4. Therefore, to execute, run <code>./obj/roi_select-gcc4</code>.