plot_growth_attr_fit: Plot fitted growth curves of an attribute
In vicstefanou/ViSCA: Cell-Movie Analysis and Visualization

Description Usage Arguments Details Value

Plots the fitted single-cell growth curves (fitted time-series data) of a numeric attribute for all cells in a division tree. The growth curves can be plotted per colony or generation or for the whole population. The average growth curve of each group is also computed and plotted separately.

plot_growth_attr_fit(DT, LT, attr, unit = "", model = c("lin", "exp"),
  grouped = c("col", "gen", "pop"), groups = -1, Ngroups, attrC = "",
  unitC = "", NC = NULL, dur = 1, sizeL = 0.7, save = FALSE,
  savePars = list(w = 1500, h = 1000, res = 150, path = getwd(), name =
  "my_growth_attr_fit"))

`DT`	The division tree, an object of class `"igraph"`.
`LT`	The corresponding lineage tree of the `DT`, an object of class `"igraph"`.
`attr`	The name of the attribute in the `LT`, a character string. It can be any numeric attribute, as returned from `get_attr_names`, except for `"colony"`, `"generation"`, `"frame"` and `"age"`.
`unit`	The unit of `attr`, a character string. It should be in the format `"<string>,<number>"`, where `",<number>"` represents the power and is optional (e.g. `"m"` for meters and `"cm,3"` for cubic centimeters). The default value is the empty character `""`, which implies that `attr` is in arbitrary units..
`model`	A character string naming the type of the fitted growth models to be plotted, `"lin"` for plotting the fitted linear models `"exp"` for plotting the fitted exponential models Parameters of the model must have already been estimated using `add_attr_growth_fit_pars`.
`grouped`	A character string naming the grouping method: `"col"` for grouping by colony `"gen"` for grouping by generation `"pop"` for no grouping (whole population)
`groups`	The IDs of the groups for which to create the plot, a vector of positive integer values. This argument is ignored in case `grouped = "pop"`. The default value `-1` stands for all existing groups in the `DT`.
`Ngroups`	Number of colonies in the movie (if `grouped = "col"`) or number of generations in the movie (if `grouped = "gen"`), a non-zero positive integer value. This argument is ignored in case `grouped = "pop"`.
`attrC`	The name of the attribute in the `DT` by which the cells' growth curves will be colored, a character string. It can be any numeric or boolean attribute, as returned from `get_attr_names`. Coloring is applied to all depicted cells of all groups specified in `groups`, except for cells with `NA` value in this attribute which are colored gray. When the default value `""` (the empty character) is used, cells' colors are the default.
`unitC`	The unit of `attrC`, a character string. It should be in the format `"<string>,<number>"`, where `",<number>"` represents the power and is optional (e.g. `"m"` for meters and `"cm,3"` for cubic centimeters). The default value is the empty character `""`, which implies that `attrC` is in arbitrary units. This argument is ignored in case `attrC = ""`.
`NC`	Number of colonies in the movie (if `attrC = "colony"`) or number of generations in the movie (if `attrC = "generation"`), a non-zero positive integer value. This argument is ignored in case `attrC != "colony"` and `attrC != "generation"`.
`dur`	The time span in `hours`, a non-zero positive numeric value. The default value is `1`.
`sizeL`	Size of explanatory legends, a non-zero positive numeric value. The default value is `0.7`.
`save`	A logical value (`TRUE` or `FALSE`) indicating whether the generated plot(s) will be saved in `.png` file(s) or displayed in the Plots Pane of RStudio, respectively. The default value is `FALSE`.
`savePars`	A named list specifying the parameters of each generated image file. This argument is ignored in case `save = FALSE`. Elements of the list are the following: `w` The width of the image file in pixels, a non-zero positive integer value. The default value is `1500`. `h` The height of the image file in pixels, a non-zero positive integer value. The default value is `1000`. `res` The resolution of the image file in pixels per inch (ppi), a non-zero positive integer value. The smaller this value, the larger the plot area in inches, and the smaller the text relative to the graph itself. The default value is `150`. `path` A character string naming the directory where the image file will be saved (excluding the last `"/"`). If it does not contain an absolute path, the image file will be saved relative to the current working directory `getwd()`. The default value is the current working directory `getwd()`. NOTE: The components should be separated by `"/"` on Windows. `name` The image file name, a character string. The suffix `".png"` is added automatically. The default value is `"my_growth_attr_fit"`.

For each group specified in groups, two types of plots are generated. The first plot depicts the single-cell growth curves of all cells that are included in the analysis, as returned from get_cells, except for cells with NA values in the attributes/parameters of the model, as estimated by add_attr_growth_fit_pars. By default, each single-cell growth curve is randomly colored.

The second plot depicts the average growth curve of the group, +/- one standard deviation. When model = "lin", the following curves are drawn:

y = aMean * t + bMean
y = (aMean + aSD) * t + (bMean + bSD)
y = (aMean - aSD) * t + (bMean - bSD)

When model = "exp", the following curves are drawn:

y = y0Mean * e^{kMean * t}
y = (y0Mean + y0SD) * e^{(kMean + kSD) * t}
y = (y0Mean - y0SD) * e^{(kMean - kSD) * t}

The parameters of these curves are computed based on the corresponding parameters of the single-cell growth curves. See the Value field for more details. Color of the area between the curves denotes the corresponding group.

In both types of plots, x-axis represents the time in hours in the range [0, dur]. Value 0 is considered to be the birth time of each cell. The range of y-axis values is common among the plots of the same type and is calculated as the range of the corresponding values of all specified groups (excluding the outliers).

When model = "lin", a dataframe with the following columns is returned:

group is the ID of the group (a positive integer value) or -2 in case grouped = "pop"
Ncells is the number of cells, a positive integer value
aMean is the mean of "<attr>_a" (a non-zero positive numeric value in units of attr per hour), or NA in case Ncells = 0
aSD is the standard deviation of "<attr>_a" (a non-zero positive numeric value in units of attr per hour), or NA in case Ncells = 0 or Ncells = 1
bMean is the mean of "<attr>_b" (a positive numeric value in units of attr) or NA in case Ncells = 0
bSD is the standard deviation of "<attr>_b" (a positive numeric value in units of attr) or NA in case Ncells = 0 or Ncells = 1

When model = "exp", a dataframe with the following columns is returned:

group is the ID of the group (a positive integer value) or -2 in case grouped = "pop"
Ncells is the number of cells, a positive integer value
kMean is the mean of "<attr>_k" (a non-zero positive numeric value in units of attr per hour), or NA in case Ncells = 0
kSD is the standard deviation of "<attr>_k" (a non-zero positive numeric value in units of attr per hour), or NA in case Ncells = 0 or Ncells = 1
y0Mean is the mean of "<attr>_0" (a non-zero positive numeric value in units of attr) or NA in case Ncells = 0
y0SD is the standard deviation of "<attr>_0" (a non-zero positive numeric value in units of attr) or NA in case Ncells = 0 or Ncells = 1

For groups with Ncells = 0, no plot of first or second type is generated. For groups with Ncells = 1, no plot of second type is generated. In case no cells exist, no plot is generated and NULL is returned.

vicstefanou/ViSCA documentation built on May 31, 2019, 10:50 p.m.