DRomics (version 2.6-2)

bmdplot: BMD plot optionally with confidence intervals on BMD

Description

Provides an ECDF plot of BMD values optionally with confidence intervals on each BMD value and/or labels of items.

Usage

bmdplot(extendedres, BMDtype = c("zSD", "xfold"),
                                  add.CI = FALSE, 
                                   facetby, facetby2, 
                                   shapeby,  colorby,
                                   point.size = 1.5,
                                   point.alpha = 0.8,
                                   line.size = 0.5, 
                                   line.alpha = 0.8,
                                   ncol4faceting, 
                                   add.label = FALSE, label.size = 2,
                                    BMD_log_transfo = TRUE)

Value

a ggplot object.

Arguments

extendedres

the dataframe of results provided by plot.bmdcalc or plot.bmdboot (res) or a subset of this data frame (selected lines). This dataframe can be extended with additional columns coming for example from the functional annotation of items, and some lines can be replicated if their corresponding item has more than one annotation. This dataframe must at least contain the column giving the BMD values (BMD.zSD or BMD.xfold depending of chosen BMDtype), identification of each curve (id), and if add.CI is TRUE, the columns BMD.zSD.lower, BMD.zSD.upper or BMD.xfold.lower, BMD.xfold.upper depending of the argument BMDtype.

BMDtype

The type of BMD to plot, "zSD" (default choice) or "xfold".

add.CI

If TRUE (default choice at FALSE) for each item the confidence interval is added.

facetby

optional argument naming the column of extendedres chosen to split the plot in facets using ggplot2::facet_wrap (no split if omitted).

facetby2

optional argument naming the column of extendedres chosen as an additional argument to split the plot in facets using ggplot2::facet_grid, with columns defined by facetby and rows defined by facetby2 (no split if omitted).

shapeby

optional argument naming the column of extendedres chosen to shape the BMD points (no difference if shapeby if omitted).

colorby

optional argument naming the column of extendedres chosen to color the BMD points (no difference if colorby if omitted).

point.size

Size of the BMD points.

point.alpha

Transparency of the points.

line.size

Width of the lines.

line.alpha

Transparency of the lines.

ncol4faceting

Number of columns for facetting (not used if facetby2 is also provided.

add.label

Points are replaced by labels of items if TRUE.

label.size

Size of labels if add.label is TRUE.

BMD_log_transfo

If TRUE, default option, a log transformation of the BMD is used in the plot.

Author

Marie-Laure Delignette-Muller

Details

BMD values are plotted as an ECDF plot, as with plot.bmdcalc using "ecdf" as plottype with confidence intervals on each BMD value and/or labels of items if requested. The optional use of columns to code for shape and/or facets for each item is particularly intended to give a view of all the dose-response per group (e.g. metabolic pathways). Those groups must be coded in a column of extendedres. In case where one item is allocated to more than one group during the annotation process, the line of this item must be replicated in extendedres as many times as the number of annotation groups in which it was allocated.

See Also

See plot.bmdcalc, plot.bmdboot and ecdfplotwithCI.

Examples

# (1)
# Plot of BMD values with color dose-response gradient
# faceted by metabolic pathway (from annotation of the selected items)
# and shaped by dose-response trend

# An example from the paper published by Larras et al. 2020
# in Journal of Hazardous Materials
# https://doi.org/10.1016/j.jhazmat.2020.122727
# A example of plot obtained with this function is in Figure 5 in Larras et al. 2020

# the dataframe with metabolomic results (output $res of bmdcalc() or bmdboot() functions)
resfilename <- system.file("extdata", "triclosanSVmetabres.txt", package="DRomics")
res <- read.table(resfilename, header = TRUE, stringsAsFactors = TRUE)
str(res)

# the dataframe with annotation of each item identified in the previous file
# each item may have more than one annotation (-> more than one line)
annotfilename <- system.file("extdata", "triclosanSVmetabannot.txt", package="DRomics")
annot <- read.table(annotfilename, header = TRUE, stringsAsFactors = TRUE)
str(annot)

# Merging of both previous dataframes
# in order to obtain an extenderes dataframe
metabextendedres <- merge(x = res, y = annot, by.x = "id", by.y = "metab.code")
head(metabextendedres)


### (1.a) BMDplot by pathway shaped by trend
bmdplot(metabextendedres, BMDtype = "zSD",
                     facetby = "path_class", 
                       shapeby = "trend") 

# \donttest{

### (1.b) BMDplot by pathway with items labels
bmdplot(metabextendedres, BMDtype = "zSD",
                     facetby = "path_class", 
                       add.label = TRUE,
                       label.size = 2) 

### (1.c) BMDplot by pathway with confidence intervals
bmdplot(metabextendedres, BMDtype = "zSD",
                     facetby = "path_class", 
                       add.CI = TRUE) 

### (1.d) BMDplot by pathway with confidence intervals 
#         in BMD raw scale (not default log scale)
bmdplot(metabextendedres, BMDtype = "zSD",
                     facetby = "path_class",
                     add.CI = TRUE,
                     BMD_log_transfo = FALSE) 

### (1.e) BMDplot by pathway with confidence intervals 
#         colored by trend and playing with graphical parameters
bmdplot(metabextendedres, BMDtype = "zSD",
                     facetby = "path_class",
                     add.CI = TRUE,
                     colorby = "trend", 
                     point.size = 2,
                     point.alpha = 0.5,
                     line.size = 0.8,
                     line.alpha = 0.5) 


# (2) 
# An example with two molecular levels
#
# Import the dataframe with transcriptomic results 
contigresfilename <- system.file("extdata", "triclosanSVcontigres.txt", package = "DRomics")
contigres <- read.table(contigresfilename, header = TRUE, stringsAsFactors = TRUE)
str(contigres)

# Import the dataframe with functional annotation (or any other descriptor/category 
# you want to use, here KEGG pathway classes) 
contigannotfilename <- system.file("extdata", "triclosanSVcontigannot.txt", package = "DRomics")
contigannot <- read.table(contigannotfilename, header = TRUE, stringsAsFactors = TRUE)
str(contigannot)

# Merging of both previous dataframes   
contigextendedres <- merge(x = contigres, y = contigannot, by.x = "id", by.y = "contig")
# to see the structure of this dataframe
str(contigextendedres)

### Merge metabolomic and transcriptomic results
extendedres <- rbind(metabextendedres, contigextendedres)
extendedres$molecular.level <- factor(c(rep("metabolites", nrow(metabextendedres)),
                              rep("contigs", nrow(contigextendedres))))
str(extendedres)

### BMD plot per pathway with molecular level coding for color
bmdplot(extendedres, BMDtype = "zSD",
                     facetby = "path_class",
                     colorby = "molecular.level",
                     point.alpha = 0.3) 

### BMD plot per pathway and per molecular level 
# for a selection of pathways
chosen_path_class <- c("Membrane transport", "Lipid metabolism")
ischosen <- is.element(extendedres$path_class, chosen_path_class)
bmdplot(extendedres[ischosen, ], BMDtype = "zSD",
                     facetby = "path_class",
                     facetby2 = "molecular.level",
                     colorby = "trend",
                     point.size = 2,
                     add.CI = TRUE) 


# }