Roi select

This page is incomplete and currently under development.

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:

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

Both are located under $G. 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)

Installing roi_select

To install roi_select:

cd $G/project/brain/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 to stick with GCC4. Therefore, to execute, run ./obj/roi_select-gcc4.

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. It is recommended that you use 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. It is recommended that you use the absolute path to the file.
-e	expression [string]	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 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.