createFDT: Create cells' FDT
In vicstefanou/ViSCA: Cell-Movie Analysis and Visualization

Description Usage Arguments Details Value See Also

Creates the cells' Forest of Division Trees (FDT) given the corresponding Forest of Lineage Trees (FLT).

1	createFDT(LTmain, minLife = 5, frameR)

`LTmain`	The main part of the overall FLT, a connected lineage tree containing the imaginary root cells (object of class `"igraph"`).
`minLife`	Minimum life in frames for a cell to be included in the analysis, a positive integer value. The default value is `5`. Use value `0` to exclude all leaf cells from the analysis.
`frameR`	Frame rate of the movie in frames per minute, a non-zero positive numeric value.

A continuous segment (sequence) of LT nodes between two successive cell divisions represents the lifespan of a cell. A cell is divided if

it gives birth to 2 daughter cells in the next frame,
it disappears from the field of view in the next frame or
it is not linked to any cell instant in the next frame due to tracking errors.

The fuction creates the Forest of Division Tree (FDT) by reducing all LT cell segments down to single nodes (DT nodes), except for the imaginary root cells.

Each node of the FDT represents a cell at its full lifespan, having as character string attributes the concatenation of all attributes of the collapsed LT nodes by ", ", with the following exceptions:

The "colony" attribute is not concatenated, since the ID of the colony from which the cell emanated characterizes both cell and its instants. The "colony" attribute is again a non-zero positive integer number.
Attributes "age" and/or "generation" are also not concatenated in case they exist, since they are (re)evaluated by the function and updated/stored in the FLT. See below for more details.
Each boolean attribute in the FLT forms also a boolean attribute in the FDT, with value (TRUE or FALSE) based on the majority vote of the corresponding values of the collapsed LT nodes.

The concatenated "name" attribute represents the labels of the collapsed cells (instants of the cell) and is renamed to "cellInstants". The "name" attribute is again a non-zero positive integer number stored as a character string, denoting the label of the cell in the FDT. Value "1" corresponds to the main root cell. Values "1+<i>" correspond to the colonies' root cells, where "<i>" is the colony ID. The rest values correspond to the cells.

For each numeric attribute in the FLT (except for "colony" and "frame", plus "age" and/or "generation" in case they exist), the concatenation represents the cell's time-series of the attribute. Given each cell's time-series of an attribute "<attr>", the following numeric life attributes are estimated and stored as attributes in the corresponding FDT node:

"<attr>_birth" is the "<attr>" value of the first instant of the cell
"<attr>_division" is the "<attr>" value of the last instant of the cell
"<attr>_mean" is the mean of "<attr>"
"<attr>_sd" is the standard deviation of "<attr>", or NA in case the cell has only one instant
"<attr>_min" is the minimum value of "<attr>"
"<attr>_max" is the maximum value of "<attr>"

These numeric attributes are in units of "<attr>".

The following attributes are also life attributes and are stored in each DT node:

"generation" is the ID of the generation of the cell, a positive integer value. This value is also updated/stored in the "generation" attribute of the instants of the cell in the FLT, since the ID of the generation characterizes both cell and its instants.
"birthTime" is the ID of the frame at which the cell is firstly spotted (born), a non-zero positive integer value. This value is the "frame" value of the first instant of the cell.
"divisionTime" is the ID of the frame at which the cell is lastly spotted (a frame before its division), a non-zero positive integer value. This value is the "frame" value of the last instant of the cell.
"lifeFrames" is the duration of the cell life in frames, a non-zero positive integer value. This value is computed as lifeFrames = divisionTime - birthTime + 1.
"lifeHours" is the duration of the cell life in hours, a non-zero positive numeric value. This value is computed as lifeHours = lifeFrames / (60 * frameR).
"isConsidered" is a logical value (TRUE or FALSE) indicating whether the cell will be included in the analysis or not. This value is FALSE for the imaginary root cells. The value for the cells is computed based on the minLife argument. It is FALSE for all leaf cells and TRUE for the rest, in case minLife = 0, or FALSE for all leaf cells with "lifeFrames" <= minLife and TRUE for the rest, in case minLife != 0.

A named list with the following components:

`DTmain`	The corresponding main part of the overall FDT, a connected division tree containing the imaginary root cells (object of class `"igraph"`).
`LTmain`	The updated LTmain with the attributes `"generation"` and `"age"` updated/added, an object of class `"igraph"`. The `"age"` attribute denotes the age of each cell instant in frames.
`Ngens`	Number of generations in the movie, a non-zero positive integer value. IDs of generations are in the range `[0, Ngens-1]`.