plot_pdf_attr: Plot the PDF of an attribute

Description Usage Arguments Details Value

Description

Computes and plots the Probability Density Function (PDF) of a numeric attribute of a lineage or division tree. The PDF can be plotted for each colony or generation or for the whole population. Each PDF is computed by fitting a distribution model (Normal, Gamma or Lognormal) to the corresponding data.

Usage

1
2
3
4
5
plot_pdf_attr(tree, treeT = c("LT", "DT"), attr, unit = "",
  grouped = c("col", "gen", "pop"), groups = -1, Ngroups,
  model = c("norm", "gamma", "lnorm", "auto"), plot3D = TRUE,
  save = FALSE, savePars = list(w = 2000, h = 2000, res = 250, path =
  getwd(), name = "my_pdf_attr"))

Arguments

tree

The lineage or division tree, an object of class "igraph".

treeT

A character string naming the type of tree:

  • "LT" if tree is a lineage tree

  • "DT" if tree is a division tree

attr

The name of the attribute in the tree, a character string. It can be any numeric attribute, as returned from get_attr_names, except for "colony", "generation" and "frame".

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.

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 plot the PDF, 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 tree.

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".

model

A character string naming the distribution model to be fitted:

  • "norm" is for fitting the Normal distribution.

  • "gamma" is for fitting the Gamma distribution.

  • "lnorm" is for fitting the Lognormal distribution.

  • "auto" is for finding the best-fit distribution. This is accomplished by fitting separately the Normal, Gamma and Lognormal distribution. The best-fit distribution is then chosen using the Bayesian Inference Criterion (BIC), according to which the best model is the one with the lowest numeric BIC value.

Each model is fitted using the maximum likelyhood estimation (MLE) method provided by fitdist.
Note that the Gamma and Lognormal distributions can be fitted to attributes with non-zero positive numeric values. Zero values are automatically replaced by value 1e-6. For negative values, an error is produced.

plot3D

A logical value (TRUE or FALSE) indicating whether a 3D or 2D plot will be generated, respectively. When the default value TRUE is used, a common 3D plot for all groups specified in groups is generated. When the value FALSE is used, a separate 2D plot for each group specified in groups is generated. This argument is ignored (regarded as FALSE) in case grouped = "pop" or if only one group is specified in groups.

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 2000.

h

The height of the image file in pixels, a non-zero positive integer value. The default value is 2000.

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 250.

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_pdf_attr".

Details

Each PDF is computed considering all cells that are included in the analysis, as returned from get_cells, except for cells with NA value in attr.

The range of x-axis (attribute) values depicted in each 2D plot is common and is calculated as the range of values of all groups specified in groups.

Color denotes the corresponding group.

Value

A dataframe with the following columns:

  1. group is the ID of the group (a positive integer value) or -2 in case grouped = "pop".

  2. Ncells is the number of cells, a positive integer value.

  3. distr is a character string naming the distribution model that was fitted: "norm" for Normal, "gamma" for Gamma and "lnorm" for Lognormal distribution or NA if no distribution was fitted (less than 2 unique values of attr exist).

  4. mean is the mu parameter (mean) of the Normal distribution (a numeric value), or NA in case distr != "norm".

  5. sd is the sigma parameter (standard deviation) of the Normal distribution (a non-zero positive numeric value), or NA in case distr != "norm".

  6. shape is the alpha parameter (shape) of the Gamma distribution (a non-zero positive numeric value), or NA in case distr != "gamma".

  7. rate is the beta parameter (rate) of the Gamma distribution (a non-zero positive numeric value), or NA in case distr != "gamma".

  8. meanlog is the mu parameter of the Lognormal distribution (a numeric value), or NA in case distr != "lnorm".

  9. sdlog is the sigma parameter of the Lognormal distribution (a non-zero positive numeric value), or NA in case distr != "lnorm".

  10. BIC is the BIC value of the fitted distribution (a numeric value), or NA in case distr = NA.

  11. dBIC is a character string summarizing the strength of the chosen distribution model specified in distr against the other models with higher BIC values. Value is NA in case model != "auto" or if distr = NA.

    The format of the string is "<dBIC_norm>, <dBIC_gamma>, <dBIC_lnorm>". Each <dBIC_model> value is rounded. The larger a <dBIC_model> value, the stronger the evidence that attribute attr of the group follows the chosen distr distribution against the <model> distribution. Values >10 typically indicate strong preference to the chosen distribution.

For groups with distr = NA, no plot 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.