User Guide
This section describes how to install the Lineage Mapper plugin. Section Installing Fiji describes how to get Fiji. Section Lineage Mapper Plugin Installation describes how to add the plugin into Fiji. General help relating to Fiji and ImageJ can be found online.
To download Fiji go to http://fiji.sc/Downloads and follow their installation instructions for your platform.
See the wiki Install-Guide for instructions.
This section assumes you have already installed the plugin using the steps described in section Lineage Mapper Plugin Installation.
To launch the Lineage Mapper plugin:
-
Open Fiji
-
Menu item: Plugins >> Tracking >> LineageMapper
-
Lineage Mapper main window opens
The Lineage-Mapper tracks a series of labeled segmented images saved on disk. A labeled image is a segmented image where the regions of interest (ROI) are labeled from 1 to maximum number of objects per image. The ROI numbering does not need to reflect any organization. The labeled ROIs in the segmented images all consist of pixels that have the value of the ROI label. For example, every pixel in the ROI labeled 5 has a pixel value of 5. Background pixels have the value 0.
Lineage Mapper does not automatically label the input images because that would undo any previous segmentation of touching ROIs.
The input to the cell tracker is a set of labeled segmented images where each Region of Interest (ROI) is assigned a unique number starting from 1 to the maximum number of ROIs in that image.
In this section, we will walk through setting up running LineageMapper on the small test dataset in order to validate that the plugin is installed correctly.
- Download test images: LineageMapper_Test_Data.zip ~ 55 KB
- Extract LineageMapper_Test_Data.zip into a directory
- Launch LineageMapper plugin from Fiji
- Select Load Params and open '[extractionPath]/LineageMapper_Test_Data/tracking-params.txt'
- Modify the Input and Output directories appropriately
- Click Track to launch
-
(1) Save Params - Saves the current parameters to a file. When clicked, a save dialog will appear.
-
(2) Track - Launches the tracking. Prior to launching all parameters are validated. Any parameter that does not pass the argument checks will be highlighted. Lineage Mapper will query for confirmation before overwriting any files on disk. Additionally, any error messages will appear in the log file (see (6))
-
(3) Load Params - Loads parameters from a file. When clicked a load dialog will appear. Users can load the file that was saved using Save Params.
-
(4) Status Bar - Status bar showing the current status of the tracking.
-
(5) Log Level - Log Level control. Specifies what level of detail log messages are printed to (6). By default no logging is displayed.
-
(6) Log Window - The log window is a text area that contains useful information after you click the Track button. Any errors will be appended to the log window.
-
(1) Input Directory - The directory where the source segmented images are located. Select browse to open a directory browser. These input images must be labeled segmented masks.
-
(2) Filename Pattern - Used to select which images to load from a directory. Important: the character "%" cannot be used as part of a filename pattern.
Example: img_001.tif = img_{iii}.tif {iii} - Special text that represents index numbering between 0 and 999. Increase the number of i's to represent larger numbers.
- (3) Output Directory - Specifies the location to save output tracked images and associated tracking metadata.
Files that are saved:
- {namePrefix}{filenamePattern} - the tracked images
- **{namePrefix}**tracking-parameters.txt - tracking parameters used (can be loaded into the GUI)
- **{namePrefix}**birth-death.csv
- **{namePrefix}**confidence-index.csv
- **{namePrefix}**division.csv
- **{namePrefix}**fusion.csv
- **{namePrefix}**lineage-viewer/ - auto generated lineage viewer webpage and associated files
-
(4) Prefix - The prefix given to output files.
-
(5) Minimum Object Size - The minimum size a labeled foreground object must be in order to be recognized as a cell. Objects smaller than this threshold will be deleted if they were created by splitting the group of cellular area into single cell segments. This parameter is only used when a fusion cases is detected and the cells are cut apart. Otherwise no minimum object size will be enforced on the input labeled masks.
-
(6) Maximum Centroid Displacement - The maximum centroid distance (in pixels) is used to consider which cells could possibly be tracked together. The radius from a cell centroid to the max centroid distance represents the area of a possible cell migration. For example, the red cell represents the current frame, whereas the blue cells represent the next frame. The Cell Tracker would consider the upper blue cell as a possible tracking option to the red cell and the lower blue cell would be ignored.
-
(7) Enable Division - If cell division is enabled, the daughters cells of a mitotic event will be assigned new cell labels, different from their mother cell label. If disabled, the daughters will keep the same label as the mother cell and no mitotic event will be considered. This functionality is helpful when dealing with particle tracking or colony tracking.
-
(8) Enable Fusion - If cell fusion is enabled, the cell tracker will assign a new unique global ID number to the fused region and will consider all the cells from the previous frame as dead. If disabled, the cell tracker will separate the cellular area in the current frame into a group of single cells by relying on the previous frames information.
-
Cost Parameters - The cell tracker uses a cost function to create a tracking decision between cells in consecutive frames. The weights represent the importance of each term in the computation of the cost function. The higher the weight the more important is that term. The cost function that relates two Cellular objects between consecutive frames is computed using the following normalized weighted 3 time-lapse cell characteristics:
-
(1) Weight Cell Overlap - If cells tend to move slowly and have big overlapping areas between consecutive frames, then this value should be the highest among all other cost function weights.
-
(2) Weight Cell Centroid Distance - In the event when cells don’t overlap as much and/or amount of overlap is almost similar, the distance of their centroids movement will make the difference in the tracking decision.
-
(3) Weight Cell Size - If cells retain their size between consecutive frames then this weight value should be high. However, if cells go into mitosis and their respective size changes rapidly then this value should be low.
-
Some possible scenarios for cell tracking: Problem 1 is our typical problem encountered in most cases, when cells change shape often and go into mitosis and image acquisition rate is high enough that there are good cellular overlaps between consecutive acquisitions. In general, the overlap weight should be proportional to the acquisition rate. Problems 2 and Problem 3 are considered to have low acquisition rates. In Problem 2 cells change shape but don’t move long distances and in Problem 3 like for particle tracking problems where objects don’t change shape and we have low image acquisition rate. A proposed weight combination to solve each of these problems is given in the table below. It is important to note that the cell tracker is very robust with regards to the weights. The three weights don’t need to be changed for solving similar problems like the ones displayed in the table below.
-
Division Parameters - The cell tracker bases its decision on detecting mitotic events using cell overlap between mother and its 2 daughter cells. If the cell overlap between one frame and the next is above the Min Division Overlap threshold, the Cell Tracker will label that as a possible mitosis event. The Cell Tracker will then test the Daughter Size Similarity, Daughter Aspect Ratio Similarity, and Mother Circularity Index thresholds to determine if a mitotic event has occurred. If all of the tests pass, the Cell Tracker will record the mitotic event in the division table.
-
(4) Minimum Division Overlap - If cell overlap in percent is above this threshold between one frame and the next the Cell Tracker will record a possible mitotic event. The following table illustrates the value of this parameter with respect to the overlapping positions between a red cell from the current frame and the blue cell from the next frame. If this parameter is set to 0%, all cases will be considered as a potential mitotic event. If this parameter is set to 100% cell mitosis is discarded where the daughter cell that overlaps the most with the mother cell will keep its unique global ID label and the other one will get a new label.
-
(5) Daughter Size Similarity - This parameter is a measure of the size similarity between daughter cells. In a real mitotic event the size of the daughter cells should be very similar to each other. A mother cell doesn’t really produce a large daughter and a small one. Set this parameter to 0% to discard it.
-
(6) Daughter Aspect Ratio Similarity - This parameter is a measure of the aspect ratio similarity between daughter cells. In a real mitotic event daughter cells should have similar shapes to each other. Set this parameter to 0% to discard it.
-
(7) Mother Circularity Threshold - For a cell to be considered a mother cell in a possible mitotic event it must have been round within the previous Number of Frames to Check Circularity parameter. This circularity threshold determines what is round enough to be considered a mitotic cell. Set this parameter to 0% to discard it.
-
(8) Number Frames to Check Circularity - The Cell Tracker will determine if the cell had a circularity threshold above the Mother Circularity Index between the current frame and the previous number of frames. If the cell’s circularity is not above the threshold at least for one frame within this range, then the mitotic event will not be recorded.
-
-
Fusion Parameters - Cell fusion occurs when multiple cells get together and form one cellular object. It can come from an actual fusion where, for example, two colonies merge into one or from cells migrating so close together that segmentation technique considers them a single cell.
- (9) Minimum Fusion Overlap - This parameter represents the amount of overlap in percent of cell area, above which an area at the current frame is considered as a group of cells from the previous frame and that this area needs to be split into multiple single cells. For example: if 2 cells A & B at frame t have tracks to the same cell C at frame t+1 and the amount of overlap between A&C = 45% of size A and the overlap between B&C = 50% of size B, then C should be split into 2 single cells.
-
Confidence Index Parameters - The Lineage Mapper assigns a tracking confidence index for each tracked object in the time-lapse sequence. The confidence index is only an indicator of how well we trust the track of a given cell during its entire cell cycle. There are three components that can affect the computation of the confidence index; each one can be disabled if needed: cell lifetime threshold, neighbor density, and border distance. All cells start with the same confidence index value of 1, and then we analyze the confidence index parameters of each cell. For example, if a cell meets the minimum expected lifetime defined by the user, the confidence increases by a point. The confidence index decreases if a cell was in a very confluent area and was touching other cells or if a cell was too close to the border (as defined by the user).
-
(10) Minimum Cell Lifespan - The minimum cell life is the number of frames a cell must be present throughout to increase its confidence by a point. This index does not affect cells that are present at the beginning of the experiment (first frame).
-
(11) Cell Death Delta Centroids Threshold - If a cell centroid does not move more than this value (in pixels) the cell will be recorded as dead.
-
(12) Cell Density Affects Confidence Index - If enabled, a lower confidence index will be assigned to cells that have grouped into colonies or become close to other cells.
-
(13) Border Cell Affects Confidence Index - If enabled, only cells that never touch the image border (Field of View) boundaries will increase their corresponding confidence index by a point.
-
-
(14) Load Default Parameters - Loads the default tracking parameters into the GUI.