roi_select

The Regions of Interest Selection Tool (roi_select) 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

After we run DTI data through a pipeline (whether our in-house one or a third-party one, such as 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 roi_select tool can help achieve these goals.

Installation

Dependencies

roi_select has two dependencies, both of which are located under $G:

1. libcurvecollection — for format interoperability, file I/O, and in-memory data handling
2. gg/args — for command-line argument processing

You will first need to set up your sandbox. (You may be able to do it automatically.)

To install libcurvecollection:

cd $G/common/libcurvecollection
make all
make install

To install gg_args:

cd $G/common/utility
make all
make install

cd $G/common/gg
make all
make install

(see more information)

Compiling roi_select

To compile roi_select:

cd $G/project/brain/pipeline/streamline_processing/roi_select
make all

This will create a subdirectory obj 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 ./obj/roi_select-gcc4.

Installing roi_select as a library

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

Using roi_select

After installing the dependencies and compiling the code, you can run roi_select by executing $G/project/brain/roi/select/roi_select-gcc4 with the following command-line arguments:

Required arguments

Flag	Arguments	Explanation
-i	filename [string]	The source file that contains the tracks that are to be selected. Supported formats are .trk, .data, and .ccf. This can be the absolute path to the file.
-o	filename [string]	The output file, where the selected streamlines are to be written. Supported formats are .trk, .data, and .ccf.
-e	expression [string]	The ROI expression — see explanation below

At least one of these arguments is required

Flag	Arguments	Explanation
-roi_aa	name [string] x1 [double] y1 [double] z1 [double] x2 [double] y2 [double] z2 [double]	The first argument is the name by which you refer to this ROI in the expression. The remainder of the arguments are the (x,y,z) coordinates that define this Axis-Aligned ROI.
-roi_nifti	name [string] filename [string] region [int]	The first argument is the name by which you refer to this ROI in the expression. The rest are the filename and the region (bitmap number) that define this NIfTI Bitmap ROI.
-roi_sphere	name [string] x [double] y [double] z [double] radius [double]	The first argument is the name by which you refer to this ROI in the expression. It is followed by the (x,y,z) coordinates of the sphere center and the radius of this Spherical ROI.

ROI types

Axis-Aligned ROI

You can think of an Axis-Aligned ROI as a box placed within the image volume — that is axis-aligned, of course. A streamline is said to pass through an Axis-Aligned ROI when any of the line's vertices is located within the bounds of this box or when a line segment connecting any two adjacent vertices passes through this box.

The box that is an Axis-Aligned ROI is defined by two corners: the front bottom left and the back top right. These are labeled as corners 1 and 2 in the following diagram:

Practically speaking, we check that x₁<x₂, y₁<y₂, and z₁<z₂.

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

Spherical ROI

A Spherical ROI is simply a sphere in the image volume, defined by the (x,y,z) coordinates of its center and a radius; all of these values are in millimeters.

A streamline is said to pass through the ROI if any of its vertices is within the sphere, or if the straight line segment connecting any two vertices passes through the sphere.

The ROI expression

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.

Note: any expression more complex than a single ROI will necessarily require spaces. For the program to catch the string as a whole, you will need to enclose it in quotes.
For example: ... -e "a AND b" is good, ... -e a AND b is bad

The supported operators are:

Operator	Alternate syntax	Selects
not	NOT, !	Lines that do not pass through the specified regions
and	AND, &, &&	Lines that pass through both specified regions
or	OR, |, ||	Lines that pass through at least one of the specified regions
xor	XOR, ^	Lines that pass through only one of the specified regions (not both)

Avoid errors: operators, even the symbolic ones, need to be separated from ROI names by spaces.
For example: ... -e "a&b" is invalid syntax; use ... -e "a & b" instead

Usage examples

./roi_select-gcc4 -i input_file.trk -o output_file.trk -roi_aa myAAroi 0 0 0 123.456 12.345 1.234 -e myAAroi

Selects all the lines that pass through the region between (0,0,0) and (123.456, 12.345, 1.234).

./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"

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.

./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)"

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.

./roi_select-gcc4 -i input_file.trk -o output_file.trk -roi_nifti roi1 roi.nii.gz 1 -roi_nifti roi2 roi.nii.gz 2 -roi_nifti roi3 roi.nii.gz 3 -e "roi1 | roi2 | roi3"

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.

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

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

... -e "( a & !(b) ) XOR ( (c OR NOT (d AND NOT e) OR (((b)) && c)) )"

You can get pretty wild with your ROI expression, as long as you're using the proper syntax and all parentheses match.