Home
Uni-Logo
 

The iRoCS Toolbox - Interactive Arabidopsis Root Analysis


Contents

What is the iRoCS Toolbox Obtaining the iRoCS Toolbox Data Usage

What is the iRoCS Toolbox?

The iRoCS Toolbox is an interactive Qt4 analysis tool for attaching the intrinsic Root Coordinate System (iRoCS) to 3-D confocal recordings of the Arabidopsis root apical meristem (RAM). This allows quantitative comparative studies of root populations in a sound and intuitive context. It consists of the data browser labelling and a set of command line tools for batch processing.

Main features are

  • 3-D Visualization of the volume in an orthographic view.
  • Manual annotation of anatomical reference structures (QC, nuclei)
  • Automatic detection and annotation of cells and/or nuclei with several meaningful properties, like position, radius, tissue, cell file, cell cycle state, volume.
  • Full control. Any step can be manually corrected and re-fed into the modeling.
  • Retrieval and localization of key events like cell divisions

iRoCS Toolbox Screenshot
click to enlarge
Arabidopsis Root Model
animation     enlarge
Figure 1: The iRoCS Toolbox in action. Within the orthoview (back) a confocal recording of a PI stained Arabidopsis root tip is shown. The same root tip is simultaneously rendered in the 3D window (front). The color given to the cells indicates their layer. Figure 2: A 3D rendering of a DAPI stained root tip with nuclei shown as colored spheres. The root axis is shown as red line, and the tissue layers are indicated by the cut ellipsoids. The rendering has been generated from the annotated root data using vgStudio MAX .
During the animation, the original DAPI channel is stripped off, revealing the extracted underlying cellular model. Finally only the mitoses within the root tip remain, and the patterning becomes apparent.

Obtaining the iRoCS Toolbox

Remark for Microsoft® Windows© users: Prior to starting the iRoCS Toolbox labelling.exe on Windows operating systems you will have to download and install the Visual Studio Runtime libraries for your system type. The according download links are given in the table below. Download the vcredist_<arch>.exe and run it as Administrator. It will install a set of dll's in the appropriate places in your Windows system.

The iRoCS Toolbox is only available for 64Bit operating systems due to high memory consumption during feature computation and classification. The 3 GB RAM limit of 32Bit Windows would be easily exceeded, when working on real data sets.

System requirements

To process datasets of a raw size of 100MB (8-Bit integer data) with a raw resolution of 1μm per voxel, you will need the following minimum system specification for completing the processing pipeline:

Feature Minimum Recommended
CPU 64 Bit Intel/AMD 64 Bit Intel/AMD Multicore (> 8 Cores)
RAM 8 GB (chunked detection) 64 GB
Harddisk 100 GB >100 GB
GPU OpenGL Software rendering Full Hardware Acceleration with at least 64 MB

Running times on reference systems

To get a feeling for the approximate workload, the running times on a state-of-the-art workstation are given in the table below:

System specification (Linux):

CPU RAM HDD OS
Intel i7 4 Cores (hyperthreading) (1.2 GHz) 16 GB DDR4 500GB SATA-2 Ubuntu 12.04 LTS (Precise Pangolin)

Running times and peak memory consumption:

Data set Peak Memory consumption Nucleus Detection Epidermis Labeling Attach iRoCS Layer Assignment Total
Feature comp. Classification Other
rootTip_short.h5 3.3 GB 0:00:52 0:02:39 0:00:09 0:00:04 0:00:01 0:00:02 0:03:47
rootTip_long.h5 17.1 GB 0:08:27 0:31:38 0:04:12 0:02:54 0:00:11 0:00:08 0:47:33

System specification (Windows):

CPU RAM HDD OS
Intel i7 4 Cores (hyperthreading) (1.2 GHz) 16 GB DDR4 500GB SATA-2 Windows 7 Professional

Running times and peak memory consumption:

Data set Peak Memory consumption Nucleus Detection Epidermis Labeling Attach iRoCS Layer Assignment Total
Feature comp. Classification Other
rootTip_short.h5 3.4 GB 0:01:15 0:15:15 0:00:13 0:00:12 0:00:00 0:00:08 0:17:05
rootTip_long.h5 17.1 GB ~0:15:00 ~3:00:00 ~0:10:00 ~3:30:00

Download

The iRoCS Toolbox is free software. You may use, distribute and copy the iRoCS Toolbox under the terms of the GNU General Public License version 3, which is contained in each of the downloadable packages for reference. By downloading the iRoCS Toolbox you implicitly accept the license agreement.

iRoCS Toolbox Labelling GUI

Operating System Architecture Filesize Download Prerequisites
Linux (Ubuntu 14.04) 64 Bit 25 MB iRoCS_Toolbox_1.1.2_x86_64-linux-gnu_gcc4.8_en.tar.gz (2015-05-13) blitz++ 0.10, HDF5 1.8.4, FFTW 3, GSL 1.16, OpenCV 2.4, Qt 4.8.5, libc6 2.19
Linux (Ubuntu 10.04) 64 Bit 27 MB iRoCS_Toolbox_1.1.0_x86_64-linux-gnu_gcc4.4.3_en.tar.gz (2014-11-07) blitz++ 0.9, HDF5 1.8.4, FFTW 3, GSL 1.13, OpenCV 2.0, Qt 4.6.2, libc6 2.11
Linux (Ubuntu 12.04) 64 Bit 56 MB iRoCS_Toolbox_0.7.2_x86_64_linux-gnu_gcc4.6_en.tar.gz (2014-01-20) Qt 4.8 (if Qt 4.8 is not installed on your system you can use the libraries shipped with the iRoCS Toolbox. For this uncomment the LD_LIBRARY_PATH line in iRoCSToolbox.sh)
Linux (Ubuntu 10.04) 64 Bit 81 MB iRoCS_Toolbox_0.7.1_x86_64_linux-gnu_gcc4.4.3_en.tar.gz (2013-08-07) Qt 4.8 (if Qt 4.8 is not installed on your system you can use the libraries shipped with the iRoCS Toolbox. For this uncomment the LD_LIBRARY_PATH line in iRoCSToolbox.sh)
Windows XP / Vista / 7 64 Bit 37 MB iRoCS_Toolbox_0.7.2_win_x64_en.zip (2014-01-20) Microsoft Visual Studio 2008 SP1 Runtime Libraries

iRoCS Toolbox L_T_C segmentation editor

Operating System Architecture Filesize Download Prerequisites
Linux (Ubuntu 14.04) 64 Bit 1 MB L_T_C.tar.gz (2015-02-25) iRoCS-Toolbox 1.1, blitz++ 0.10, HDF5 1.8.4, FFTW 3, GSL 1.16, OpenCV 2.4, Qt 4.8.5, libc6 2.19

Command line tools for batch processing (Linux x86_64 only)

Description Filesize Download Dependencies
iRoCS command line tools v 1.1, static build 2015-02-27

Contains: detectNuclei, labelEpidermis, attachIRoCS, assignLayers, segmentCells, computeCellFeatures, attachIRoCSToCellSegmentation, assignLayersToCellSegmentation
25 MB iRoCS_Toolbox_1.1.0_cmdline.tar.gz libc6 2.15
iRoCS command line tools v 1.0, static build 2014-08-29

Contains: detectNuclei, labelEpidermis, attachIRoCS, assignLayers, segmentCells, attachIRoCSToCellSegmentation, assignLayersToCellSegmentation
21 MB iRoCS_Toolbox_1.0.0_cmdline.tar.gz libc6 2.15
Useful hdf5 dataset manipulation scripts
Description Filesize Download Dependencies
HDF5 tools

Contains: rotateDataset, cropDataset
21 MB h5tools.tar.gz libc6 2.15

Source code

Description Filesize Download Dependencies
iRoCS toolbox v 1.1.2, sources 2015-05-13 2.5 MB iRoCS_Toolbox_1.1.2_src_en.tar.gz blitz++ >=0.9,hdf5 >=1.8.4,
fftw3 >= 3.2.2, gsl >= 1.13,
OpenCV >= 2.0, Qt4 >=4.6.2, OpenMP

On request, you can also get more recent snap-shots. Just mail the package maintainer .


Installation

When all prerequisites are fulfilled, unpack the iRoCS Toolbox archive into a location of your choice and start the iRoCS Toolbox using iRoCSToolbox.bat (Windows) resp. iRoCSToolbox.sh (Linux) in the base folder.

Data

SVM/RF models

Detection and classification of nuclei within the volume datasets are performed using a discriminative classifier, the support vector machine (SVM). Within this project we trained a set of SVMs for the detection the epidermis labelling and the final layer assignment. The corresponding SVM model files can be downloaded here. Training was performed on manually labelled full organ recordings of DAPI stained root tips with a raw resolution of 0.15 x 0.15 x 1.0 μm up to a length of 500μm. The detector should be able to generalize to other stains, but a re-training will probably lead to more accurate results. You can train new SVM models on your own data using the corresponding training plugins, which are included in the iRoCS Toolbox.

Task Filesize Model download
Nucleus detection 1.7 MB nucleusDetector_svmModel.h5
Epidermis Labelling 15 MB epidermisLabelling_svmModel.h5
Layer assignment 12 MB layerAssignment_svmModel.h5

The assignment of layers to the segmented cells is performed using a Random Forest classifier. We also provide a trained model for the Arabidopsis wild type.

Task Filesize Model download
Layer assignment to segmented cells 13 MB wt-model.rf.h5

Sample Data

To try out the iRoCS Toolbox in action without having an Arabidopsis root tip recording at hand, we provide two sample datasets in HDF5 format.

Dataset description Data channel Datatype Filesize Download
DAPI stained Arabidopsis root tip up to a length of 150μm from QC /t0/channel0 8 Bit (unsigned char) 71 MB rootTip_short.h5
DAPI stained Arabidopsis root tip up to a length of 500μm from QC /rawdata/stitched_weighted_ch0 32 Bit (floating point) 698 MB rootTip_long.h5
Arabidopsis root tip after pseudo Schiff staining up to a length of 600μm from QC /stitched_weighted_ch0
/L (segmentation masks)
16 Bit (unsigned short) 607 MB PI_root.h5

Usage

The input-output file format of the iRoCS Toolbox is HDF5. HDF5 is a general file format for storing arbitrary-dimensional raw data and corresponding meta-data in an hierarchical structure. The iRoCS Toolbox does not support proprietary file formats from the different microscope manufacturers. To convert your data into HDF5, we recommend to use ImageJ and the HDF5 ImageJ-plugin.

Once you converted your dataset into HDF5, you can start the iRoCS Toolbox and import the raw data channel using Channel->Import Channels. Choose the dataset out of the HDF5 tree structure and click OK. The dataset is loaded, which may block the application for a short period of time. Depending on the dataset type, you may need to adjust the gray value range to see your data. For floating point data types this can be done by checking the normalize checkbox or by manually adjusting the gray value bounds using the spin boxes, for integral data types (usually 8-Bit, 12-Bit or 16Bit) the corresponding preset range can be selected or the normalize button pressed, in the channel properties snap-in on the right of the iRoCS Toolbox main window. You should eventually save your project using File -> Save, and can load already processed files using File -> Open. You can savely use the same name for the original file and for the annotated one, the annotations will be just added to the file. If you want to use the information stored in the markers from outside the iRoCS Toolbox you can directly access the metadata, which are stored in an hdf5-group corresponding to the channel name. The group contains one dataset for each attribute, the datasets contain as many entries as markers are present in the channel. MATLAB contains functions for directly interacting with HDF5 files (hdf5read, hdf5write, ...). You can also export your data to tables of comma separated values (CSV) for import into other applications like e.g. Microsoft® Excel©.

Nucleus Detection

To automatically detect the nuclei of the loaded dataset choose Plugins -> 01 - Detect nuclei. Select the channel for detection (the one you just loaded). Choose a name for the annotation channel that will be generated (this can be changed later on in the channel properties). If you want to reuse the features later on in the pipeline choose a name for an auxiliary file to store the extracted voxelwise features to. Finally select the file nucleusDetector_svmModel.h5 as model file and click OK. The nucleus detection will start and indicate progress.

Epidermis Labeling

Once the candidates are detected you can continue with the epidermis labeling. Select Plugins -> 02 - Label Epidermis setup the plugin and run it. This time choose as model epidermisLabelling_svmModel.h5. The classification will be much faster than the detection. The most time consuming part is the file IO for reading in the features (when you selected the same feature file as in the detection step) or re-computing them if you chose a different feature file. When the classification is finished epidermis nuclei should be labeled 2 (cyan), background 0 (black), and other nuclei -1 (white). Mitoses are indicated by a double circle.

Attach Coordinate System

Now you have to manually select the Quiescent Center. For this, create a new annotation channel using Channel -> New Annotation Channel. The marker type is not important. Scroll into the plane showing the quiescent center and mark it by a click. A new marker should appear. Now you can run Plugins -> 03 - Attach iRoCS. As marker channel select the channel containing the nucleus candidates, and as qc channel select the newly created one. The coordinate system attachment itself should be very fast and generates a new channel showing the estimated axis as projection within the three orthographic views. In the information snap-in the last entry should be a tripel of values, that shows the cursor position in iRoCS-coordinates (z, r, phi) while moving the mouse over the dataset. You can switch back to the nucleus candidate channel and choose the operation Edit Marker. Click a candidate in the orthoview, and check the Show all checkbox in the Marker Control widget. Additional read-only fields appear. The root intrinsic nucleus coordinates can be found in the attributes QC distance, Radial Distance and Phi. If the coordinate system has been attached successfully these values should be different from -1 and correspond to the live output.

Layer Assignment

You can now assign the nucleus candidates to the root layers incorporating the intrinsic marker positions. For that select Plugins -> 04 - Assign Layers. Follow the instructions and select layerAssignment_svmModel.h5 as Model file. The labels will be updated according to the following color encoding:

Label Cell layer Color
-1 unknown white (#FFFFFF)
0 no nucleus (background) black (#000000)
1 root cap blue (#0000FF)
2 epidermis cyan (#00FFFF)
3 cortex green (#00FF00)
4 endodermis yellow (#FFFF00)
5 pericycle red (#FF0000)
6 vasculature brown (#AA5500)