usage:division_detection [FAST]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== The Division Detection module ======

{{logos:Divisions.png?nolink&80 }}

In the [[usage:tracking|tracking]] module, we sought the optimal way to integrate feature information to pair detected objects between frames. Division detection is conceptually similar, but instead of linking one object to another we wish to optimally use feature information to pair each mother cell with two daughter cells. This is achieved using a similar algorithm to the tracking module, with a few key modifications:

  * Firstly, instead of assuming that features are stable between frames, we instead assume that they change instantaneously but predictably during cell division. An initial, pre-defined model of this process is refined by considering the statistics of a training set of divisions, automatically generated during an initial sweep through the dataset - further details of how this is implemented can be found [[usage:advanced_usage#updating_the_division_detection_format_structure_with_new_features|here]].

  * Secondly, we relax the assumption that detected divisions must come after the last timepoint of the mother cell's track. In many cases, the segmentation module does not stably split mother cells into separate daughters, resulting in some temporal overlap between mother and daughter tracks. Simply assuming that daughter tracks must begin after their mothers' tracks would therefore prevent accurate daughter assignment. Instead, the end of the maternal track is subtracted from the start of each putative daughter track, and this time difference used as a new feature. This allows the feature weighting machinery to take into account variability in the (apparent) time difference between the end of the maternal track and the start of the daughter tracks.

Despite these differences, most of the machinery responsible for performing these assignments remains the same. The layout and usage of the division detection module is therefore very similar to that of the tracking module. For the purposes of conciseness, the below usage guide focuses on the ways in which the two modules differ, rather than providing a complete guide on each aspect of the division detection process. To initialise it, simply press the 'Divisions' button on the home panel. The following GUI should now appear:

{{ :usage:divisiondetectionv2.png?nolink&800 |}}

===== Model training =====

Training the division detection module is very similar to training the tracking module. The processes of feature choice and training link inclusion proportion remain the same as before, although the relatively low number of division events compared to object-object links means that the histogram used to inform the choice of the training link inclusion proportion may not be very informative. One major difference does exist between the modules however: because temporal information is included as a feature, all 'training' divisions are effectively pooled into a single dataset, rather than being split by timepoint. As a result, the division detection module returns a single trackability score $R$, rather than a separate score for each timepoint. This is indicated in the top right-hand corner of the unnormalized step size distribution:

{{ :usage:histogram.png?nolink&400 |}}

<note tip>
Because there are no other internal values to compare it to, $R$ is not very useful for determining the ease of division assignment. Instead, it is recommended that the accuracy of division detection be assessed following its completion using the **View divisions** panel and the [[usage:overlays|overlays]] module.
</note>

<note tip>
Division events are much sparser than ordinary frame-frame links between objects, and typically need less feature information for assignment. Prediction of the location of daughter cells in feature space is also more noisy than the prediction of a single object's location in the subsequent frame, meaning some highly variable features can actually detract from the accuracy of division detection if included. It is therefore recommended that you initially try training the division detection model with only the **Position** feature active.
</note>

Model training is initialised as before, by clicking the **Calculate!** button. Once it has completed, division detection proper becomes available.

===== Division detection =====

In contrast to the Tracking module, the Division Detection module does not require the user to manually select a tracking threshold. Instead, the division detection algorithm automates selection of this threshold by iteratively modifying its value such that the resulting lineage structure is maximally connected while still remaining a tree (i.e. contains no loops). In practice, this generally gives a near-optimal balance between assigning true links - correct assignments between mother and daughter cells - and suppressing false links.

Once training has completed, it is therefore sufficient to simply press the **Find divisions!** button to launch this iterative algorithm and generate your lineage.
==== Validation ====

To validate detected division events and help choose an appropriate **division threshold** value, FAST provides three separate validation tools. Again, these are similar to those tools found in the tracking module:

  * The normalised division space viewer (top right hand corner) acts similarly to the normalised displacement space viewer. As in the tracking module, each feature (including time, denoted as 'd(t)') can be selected from the drop-down menus on the y- and x-axes. The normalised residual error between the internal model of division and the detected division events for the selected features will then be shown, allowing the user to verify that the error distribution is zero-centred and isotropic.

{{ :usage:divisionscatter.png?nolink&600 |}}

  * The division viewer (bottom left-hand corner) acts similarly to the test tracking viewport. For each division event, maternal cells will be marked in yellow, while the corresponding daughter cells will be marked in purple. To switch between mother and daughter timepoints, click the **Toggle A/B** button in the **View divisions** panel. To move to the next division event in the series, click the **Next division** button.

{{ :usage:divabtoggle.png?nolink&600 |}}

  * The lineage size distribution is similar to the track length distribution. It indicates the total number of tracks incorporated into each cell lineage. For example, a cell that divided 3 times would result in a lineage that contained 15 tracks - this cell would be indicated in the lineage size distribution as an additional count in the bin at 15. The **Minimum lineage size** variable can be used to define a minimum cut-off in this lineage size distribution, allowing lineages that are below this threshold to be excluded from the final output. This is indicated in the distribution as a vertical red line.

{{ :usage:lineagedist.png?nolink&400 |}}
===== Outputs =====

The division detection module does not produce a new variable as its output. Instead, it modifies the contents of the 'Tracks.mat' file. In particular, the following fields are added to the [[usage:tracking#outputs|procTracks]] structure:

  * **D1** and **D2:** The numerical ID of this cell's daughters, if they exist.
  * **M:** The numerical ID of this cell's mother, if it exists.
  * **Generational age:** The age of the current cell, relative to the first object in its lineage (generation 1). Values are interpolated between the start and end of the current cell's lifespan - for example, a 3rd generation cell that is halfway between its birth and its own division would have a generational age of 3.5.

**D1**, **D2** and **M** define a set of lineage trees for all the cells in the dataset. Tools for navigating and manipulating this lineage tree are available in the [[post:post-processing_toolbox|post-processing toolbox]]. In addition, tracks that are members of lineages below the **Minimum lineage size** threshold are removed from the **procTracks** structure. The **toMappings** and **fromMappings** structures are also updated to account for this change.

If needed, the original version of these track datasets (as output by the tracking module) is copied to the 'Pre-division_Tracks.mat' file, in the root directory.

===== Video demonstration =====

{{ youtube>e6IF4OKy3v0?large }}