Build kymographs to monitor the evolution of the level of a liquid in capillary tubes (Java 8)
Warning: Update your Java environment. To run this plugin, you will need at least Java 8 (java 1.8 SDK).
Capillarytrack was designed to analyze images where 5-20 glass capillaries disposed in a 3D printed box and filled with a liquid can be ingested by flies. A webcam placed over this box takes images at regular intervals (1 image per min for ex), which are stored as a stack of jpg or as an AVI. We want to follow the level of the liquid in each of the capillaries along time. The idea is to place a ROI line over each capillary and to build kymographs to follow the upper limit and lower limit of the column of liquid. One limitation is that the box and capillaries must remain stable during the whole course of the experiment. 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.
2) add ROIS lines
3) generate kymographs 4) detect limits
5) display graphs and export results to Excel
To run this plugin:
1) Open an AVI or a stack of images.
To load images, select “Open” and select either a directory or a file from a list in that directory (which contains a stack of jpg or an avi). The list of files or images will then be loaded in memory and the data will be read “on the fly”, bypassing the canonic way implemented in Icy.
Opening a stack of files (or a “sequence” in Icy parlance), will allow you to define how to analyze this stack, namely by defining an interval of “time” (between frame “start” and “end”) and a step between frames (1 to …). By default, the program proposes from start to end and with a step of 1. If you change either of these values, press “update”.
Once you have loaded data, and analyzed it, you can clear the work area by selecting “close views”, which will close the sequence and all dependent views.
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, select adjust line tab, display yellow lines and place them over areas where the capillaries are without dark objects. The button “Center lines” will use the parameter “jitter” (pixels) and the bars to center the lines over the capillaries. 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 “capillarytrack.xml” and is stored in the same directory as the images.
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). By default, when you select load/save, they will be stored into a subdirectory named “results”.
The “Filter” tab works in conjunction with the checkbox registration. If the checkbox registration is selected, each image of the stack is controlled for movements (sliding in x or y direction, rotation) and realigned using routines proposed by Alexandre Dufour and Vannary (http://icy.bioimageanalysis.org/plugin/rigid-registration/). A further realignment can be performed by “Filter”, which simply correlates each column of pixels with the first column and realign them.
The “Display” tab allow visualizing the kymographs, to display rois that summarize results (see next section) and to scroll/browse through each kymograph. For speed reasons (to avoid re-creating kymographs on the fly), each kymograph is displayed in its own window, and browsing is simply made by putting the selected kymograph on the top of the stack of windows. 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.
The “Load/Save” tab, allow users to store kymographs and to read them back.
4) Measure data
Two types 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/Export results
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.