Open Source Software

The iRoCS Toolbox - Interactive Arabidopsis Root Analysis

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

click to enlarge

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

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	Filesize	Download	Prerequisites
Linux (Ubuntu 18.04)	8.6 MB	iRoCS-Toolbox_1.2.4_x86_64-linux-gnu_gcc7_en.tar.gz (2019-07-31)	HDF5 1.10, FFTW 3.3.7, GSL 2.1, OpenCV 3.2, Qt 4.8.7, libc6 2.27 Contains: labelling, L_T_C Segmentation editor, command line tools and shared libraries
Linux (Ubuntu 18.04)	40 MB	iRoCS-Toolbox_1.2.4_x86_64-linux-gnu_gcc7_en-static_tools.tar.gz (2019-07-31)	HDF5 1.10, FFTW 3.3.7, GSL 2.1, OpenCV 3.2, Qt 4.8.7, libc6 2.27 Contains: labelling, L_T_C Segmentation editor, statically linked command line tools (minimum dependencies) and shared libraries
Linux (Ubuntu 18.04)	50 MB	iRoCS-Toolbox_1.2.4_x86_64-linux-gnu_gcc7_en-dev.tar.gz (2019-07-31)	HDF5 1.10, FFTW 3.3.7, GSL 2.1, OpenCV 3.2, Qt 4.8.7, libc6 2.27 Contains: labelling, L_T_C Segmentation editor, command line tools, shared and static libraries development headers and API documentation
Windows ≥7	46 MB	iRoCS-Toolbox_1.2.4_x64-win-msvc2015_en.zip (2019-07-30)	No requirements - unpack and play Contains: labelling GUI, L_T_C segmentation editor and command line tools
Windows ≥7	42 MB	iRoCS-Toolbox_1.2.0_x64-win-msvc2015_en-dev.zip (2017-07-20)	Contains: labelling GUI, L_T_C segmentation editor, command line tools, development headers and shared and static libraries
Older Versions
Linux (Ubuntu 16.04)	26 MB	iRoCS-Toolbox_1.2.1_x86_64-linux-gnu_gcc5.4.0_en.tar.gz (2017-11-28)	blitz++ 0.10, HDF5 1.8.16, FFTW 3.3.4, GSL 2.1, OpenCV 2.4, Qt 4.8.7, libc6 2.23 Contains: labelling, L_T_C Segmentation editor, command line tools, development headers and shared and static libraries
Windows ≥7	27 MB	iRoCS-Toolbox_1.2.1_x64-win-msvc2015_en.zip (2017-11-29)	No requirements - unpack and play Contains: labelling GUI, L_T_C segmentation editor and command line tools
Linux (Ubuntu 14.04)	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)	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)	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)	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	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.2.1, static build 2017-11-28 Contains: detectNuclei, labelEpidermis, attachIRoCS, assignLayers, segmentCells, computeCellFeatures, attachIRoCSToCellSegmentation, assignLayersToCellSegmentation	25 MB	iRoCS_Toolbox_1.2.1_cmdline.tar.gz	libc6 2.23
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.2.0, sources 2017-07-20	2.5 MB	iRoCS-Toolbox_1.2.0_src_en.tar.gz	blitz++ >=0.10,hdf5 >=1.8.4, fftw3 >= 3.2.2, gsl >= 1.13, OpenCV >= 2.0, Qt4 >=4.6.2, OpenMP
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

All releases of the iRoCS Toolbox are available on github.

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 / for Version 1.2.0 directly run bin/labelling) 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 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)