Need help or advice ? Come to the Icy club ! - Every Wenesday morning from 9h30 to 12h30 - Francois Jacob Building - Main hall - Pasteur
Register

User reviews

This plugin is not rated yet


Please log-in to post a review

CapillaryTrack

by Frederic Marion-Poll

Build kymographs to monitor the evolution of the level of a liquid in capillary tubes (Java 8)

Publication Id
ICY-V5N6C4
See technical details
View complete changelog

Documentation

Warning: Update your Java environment to the latest version as to run this plugin, you will need at leas Java 8, java 1.8 SDK.

Capillarytrack was designed to analyze images where 5-20 capillaries filled with a liquid can be ingested by flies. A webcam placed over this box takes 1 image per min. We want to follow the position of the liquid in each of the capillaries across time. The idea is to place a ROI line over each capillary and to follow the profile of the pixels over time using kymographs. This plugin allows to:

  • read a stack of jpg files or an AVI in "virtual" mode (images read are "buffered" in a separates thread)
  • place an array of line ROIs over the image
  • generate an array of kymographs corresponding to the profile of each line across time
  • filter the kymographs
  • detect a path from each kymograph (using an adjustable threshold) over the raw data or the filtered data and export the results to Excel.

 To run this plugin:

1) Open an AVI or a stack of images.

To load images, select the proper format (AVI or stack). If stack is selected, you can either select a directory or a file from a list, and the plugin will get the whole list of files stored within that directory, sort them according to their numerical order and use this list to browse through the stack. A parameter is accessible which is called pre-fetch. This corresponds to the size of a buffer in which flies are pre-loaded. By default it is set to 100 frames, which means that the program tries to load in memory up to 100 images. This procedure allows one to read any size of AVI or stack, and is analogous to the virtual stack mechanism used within ImageJ. The actual routine is borrowed from Fabrice de Chaumont plugin "Mice Profiler Tracker". Currently, you cannot access a stack or AVI loaded within Icy by the regular file open procedure. Once a source of images is defined, it will make accessible the buttons and elements of the next box "capillaries".

2) define capillaries

This section lets the user place ROI lines over each capillary. In order to facilitate the procedure, you can place a Polygon2D ROI over the entire array of capillaries, set the number of capillaries, the type of spacing (equally or grouped by 2), and the ratio of the distance between capillaries of the same group and within a group (a pair actually); the distances are expressed in pixels. When you press the "generate ROIs" button, it will generate lines over the entire span of the polygon.

In order to help centering the lines over the capillaries, the button "Center lines" will use the parameter "jitter" (pixels) and the bars to center the lines. By default, display bars is not selected. If you select it, 2 "yellow" lines will be overlayed on the image. Place these yellow lines in two areas devoid of other objects around the capillaries, preferably as 2 lines near the top and the bottom of the capillary lines. The adjustement algorithm is such that it searches for the extent of a "valley" around the line and then takes the center of that valley to position the capillary line. "Jitter" defines the width (in pixels) analyzed around the capillary. In addition, you can manually adjust the size and position of each capillary line as they are defined as ROIs.

Since we want to estimate how much liquid is consumed, we need to correlate the number of pixels with a liquid volume. To this mean, 2 textboxes are provided: "volume (µl)" which is meant to save how much liquid is contained into one capillary tube and "length (pixels)", which is the length of one capillary. In order to measure the length of a capillary, the plugin "Ruler helper" from Fabrice de Chaumont is particularly useful. These 2 parameters are used to transform the number of pixels into a volume value when the measures are exported to an excel file.

Once the capillary lines and these parameters are defined, you can save (and recall) these lines and parameters within an xml file. By default, this file is named "roiline.xml" and is stored in the same directory as the images.

3) Kymographs

Once the capillary lines are defined (or loaded) the section "kymographs" becomes accessible. This section of the plugin compute a kymograph for each of the capillaries, by storing side by side the value of the pixels along each line. The kymographs can be computed over the entire span of the stack (default) or from a starting frame (start) to a last frame (end), either by collecting data from each frame (step = 1, default) or every other frame (2, 5, 10, etc). An additional parameter (area = 5, default), defines how many pixels are averaged around each position along the capillary line to be stored in the kymograph.

In order to start building the kymographs, hit the button "start". If you hit the button "stop", it will interrupt the procedure and the kymographs will be incomplete (kymographs will be remain partly black). This computation takes time and depends on the size of your images and the depth of your stack. The kymographs can be stored as tiff files (each pixel is stored as 3 double values if the original image was RGB) named after the order of appearance of each capillary line. You can store them anywhere. It is convenient to define a subdirectory (for example result 0-500, etc).

 4) Measure data

Two kind of measures can be performed on the kymographs: follow the position of the upper and lower meniscus ("detect level"),  and detect fast changes in these levels ("detect gulps"). In our experiments, the liquid is colored in blue (with a food dye) which makes it easier to detect the position of the upper and lower limit of the water column.

For detecting level, you need to select if you wish to detect the top and / or the bottom levels together (2 checkboxes), and you need to choose which transform to apply to the kymograph. The transformations available are:

  • (G+B)/2-R: assuming a source image RGB, each pixel of the transformed image is equal to (G+B)/2 - R.
  • XDiffn: the transformed pixel at time t = sum(n pixels before) - sum(n pixels after), n defined by "span" (3 by default)
  • XYDiffn: the transformed pixel at time t = sum(n pixels before along t & y) - sum(n pixels after along t & y), n defined by "span"
  • R, B, or G: only 1 channel is considered
  • H(HSB), S(HSB), B(HSB): transform RGB image into HSB space, and keep only 1 channel (H, S or B)

The most efficient transformation in our case is  "(G+B)/2-R". The detection routine (button "Detect level") will explore the transformed kymograph to find a transition of a pixel intensity crossing the threshold (text box "threshold") either from low to high (combobox = "threshold>") or from high to low (combobox = "threshold> ") . The result of the computation is shown as green ROIs displayed over the entire span of the kymograph (with 1 point per pixel). They are called "upperlevel" and "lowerlevel" and are stored in each kymograph sequence.

For detecting gulps, you need to select the transform applied to the kymograph and a threshold (and span). By default, we use "XDiffn" & "span=3". The gulps are then stored in rois, called "gulpxxx" (xxx = pixel where it starts) and displayed in red color. They are also stored in the kymograph sequence.

Each roi can be manually edited. Gulps can be manually added or deleted and they will be stored along in the kymograph when another kymograph is selected (in other word, to save your edited rois, select another kymograph).

Next to each detect button, a checkbox ("all") defines if the operation must be performed on all kymographs or only on the current selection. The results of the detection can be stored on disk (and recalled). 

5) Display/Edit/Export results

Kymographs can be displayed provided that the checkbox "view kymos" is checked. The kymographs are displayed one by one. If a kymograph is not displayed, press the button "update". The kymograph displayed is selected by the combobox on the left of that button. On its left and on its right, the 2 buttons ("<" and ">") allow to select the previous or the next one. In order to facilitate the examination, the upper and lower level rois can be displayed or not (check box "edit capill.level") as well as the gulps (check box "edit gulps"). In order to get the same zoom as before when you select a different kymograph, the button "previous zoom" allow you to recall previous zoom level and location.

In order to display the results as graphs, press the button "display results". If you have detected only the upper and lower levels, the corresponding rois will be displayed in a window with as many graphs that you have defined capillary groups (in our case, 20 capillaries total are grouped by 2, so that we display 10 graphs side by side). If you have detected gulps, 2 additional windows will be displayed. The first one displays the level of XDiffn, so that you can check that your detection threshold has been properly set. The second one displays the cumulated consumption.

To export the results to an XLS file, press the button "export to xls file..". It will export your data in three-four worksheets "toplevel", "bottomlevel", "derivative" and "consumption", as a series of tables organized as time on each row, and each kymograph value disposed on a different column. The first 1-2 columns are the time interval (frame number) and the file name if data come from a stack. These file names can be useful as with our frame grabbing software, the filename includes the date and the time of the acquisition.

A button on the bottom allows the user to close all windows before exiting or before selecting a new file.