DRomics (version 2.1-3)

drcfit: Dose response modelling for responsive items

Description

Fits dose reponse models to responsive items.

Usage

drcfit(itemselect, sigmoid.model = c("Hill", "log-probit"),
                  information.criterion = c("AIC", "BIC"),
                   progressbar = TRUE, saveplot2pdf = TRUE, 
                   parallel = c("no", "snow", "multicore"), ncpus)
# S3 method for drcfit
print(x, …)
# S3 method for drcfit
plot(x, items, 
  plot.type = c("dose_fitted", "dose_residuals","fitted_residuals"), 
   dose_log_transfo = FALSE, …)

Arguments

itemselect

An object of class "itemselect" returned by the function itemselect.

sigmoid.model

The chosen sigmoid model, "Hill" (default choice) or "log-probit".

information.criterion

The information criterion used to select the best fit model, "AIC" (default choice) or "BIC".

progressbar

If TRUE a progress bar is used to follow the fitting process.

saveplot2pdf

If TRUE a pdf file named drcfitplot.pdf is saved containing all the fitted dose-response curves sorted by adjusted p-values of the selection step.

parallel

The type of parallel operation to be used, "snow" or "multicore" (the second one not being available on Windows), or "no" if no parallel operation.

ncpus

Number of processes to be used in parallel operation : typically one would fix it to the number of available CPUs.

x

An object of class "drcfit".

items

Argument of the plot.drcfit function : the number of the first fits to plot (20 items max) or the character vector specifying the identifiers of the items to plot (20 items max).

plot.type

the type of plot, by default "dose_fitted" for the plot of fitted curves with the observed points added to the plot and the observed means at each dose added as black plain circles, "dose_residuals" for the plot of the residuals as function of the dose, and "fitted_residuals" for the plot of the residuals as function of the fitted value.

dose_log_transfo

to put at TRUE to use a log transformation for the dose axis (only available if the dose is in x-axis, so not available for plot.type "fitted_residuals").

…

further arguments passed to graphical or print functions.

Value

drcfit returns an object of class "drcfit", a list with 4 components:

fitres

a data frame reporting the results of the fit on each selected item for which a successful fit is reached (one line per item) sorted in the ascending order of the adjusted p-values returned by function itemselect. The different columns correspond to the identifier of each item (id), the row number of this item in the initial data set (irow), the adjusted p-value of the selection step (adjpvalue), the name of the best fit model (model), the number of fitted parameters (nbpar), the values of the parameters b, c, d, e and f, (NA for non used parameters), the residual standard deviation (SDres), the typology of the curve (typology), the rough trend of the curve (trend) defined with four classes (U, bell, increasing or decreasing shape), the theoretical value at the control y0), the theoretical y range for x within the range of tested doses (yrange), for biphasic curves the x value at which their extremum is reached (xextrem) and the corresponding y value (yextrem).

omicdata

The corresponding object of class "microarraydata" given in input (component of itemselect).

information.criterion

The information criterion used to select the best fit model as given in input.

information.criterion.val

a data frame reporting AIC (or BIC) values for each selected item (one line per item) and each fitted model (one colum per model with the AIC (or BIC) value fixed at Inf when the fit failed).

n.failure

The number of previously selected items on which the workflow failed to fit an acceptable model.

unfitres

A data frame reporting the results on each selected item for which no successful fit is reached (one line per item) sorted in the ascending order of the adjusted p-values returned by function itemselect. The different columns correspond to the identifier of each item (id), the row number of this item in the initial data set (irow), the adjusted p-value of the selection step (adjpvalue), and code for the reason of the fitting failure (cause, equal to "constant.model" if the best fit model is a constant model or "trend.in.residuals" if the best fit model is rejected due to quadratic trend on residuals.)

Details

For each selected item, five dose-response models (linear, Hill, exponential, Gauss-probit and log-Gauss-probit, see Larras et al. 2018 for their definition) were fitted by non linear regression, using the nls function. The best one was chosen as the one giving the lowest AIC (or BIC) value. Items with the best AIC (or BIC) value not lower than the AIC (or BIC) value of the null model (constant model) minus 2 were eliminated. Items with the best fit showing a global significant quadratic trend of the residuals as a function of the dose (in rank-scale) were also eliminated (the best fit is considered as not reliable in such cases). Each retained item is classified in a twelve class typology depending of the chosen model and of its parameter values :

• H.inc for increasing Hill curves (or lP.inc if sigmoid.model = "log-probit"),

• H.dec for decreasing Hill curves (or lP.dec if sigmoid.model = "log-probit"),

• L.inc for increasing linear curves,

• L.dec for decreasing linear curves,

• E.inc.convex for increasing convex exponential curves,

• E.dec.concave for decreasing concave exponential curves,

• E.inc.concave for increasing concave exponential curves,

• E.dec.convex for decreasing convex exponential curves,

• GP.U for U-shape Gauss-probit curves,

• GP.bell for bell-shape Gauss-probit curves,

• lGP.U for U-shape log-Gauss-probit curves,

• lGP.bell for bell-shape log-Gauss-probit curves.

Each retained item is also classified in four classes by its global trend :

• inc for increasing curves,

• dec for decreasing curves ,

• U for U-shape curves,

• bell for bell-shape curves.

Some curves fitted by a Gauss-probit model can be classified as increasing or decreasing when the dose value at which their extremum is reached is at zero.

References

Larras F, Billoir E, Baillard V, Siberchicot A, Scholz S, Wubet T, Tarkka M, Schmitt-Jansen M and Delignette-Muller ML (2018). DRomics: a turnkey tool to support the use of the dose-response framework for omics data in ecological risk assessment. Environmental science & technology.https://doi.org/10.1021/acs.est.8b04752

See Also

See nls for details about the non linear regression function and targetplot to plot target items (even if non responsive or unfitted).

Examples

# NOT RUN {
# (1) a toy example (a very small subsample of a microarray data set) 
#
datafilename <- system.file("extdata", "transcripto_very_small_sample.txt", package="DRomics")

# to test the package on a small (for a quick calculation) but not very small data set
# use the following commented line
# datafilename <- system.file("extdata", "transcripto_sample.txt", package="DRomics")

o <- microarraydata(datafilename, check = TRUE, norm.method = "cyclicloess")
s_quad <- itemselect(o, select.method = "quadratic", FDR = 0.05)
f <- drcfit(s_quad, progressbar = TRUE)

# Default plot
plot(f)

# }
# NOT RUN {
# The same plot with log transformation of the doses
plot(f, dose_log_transfo = TRUE)

# The same plot in x log scale choosing x limits for plot
if (require(ggplot2))
plot(f, dose_log_transfo = TRUE) + 
        scale_x_log10(limits = c(0.1, 10))

# Plot of residuals as function of the dose
plot(f, plot.type = "dose_residuals")

# Same plot of residuals with log transformation of the doses
plot(f, plot.type = "dose_residuals", dose_log_transfo = TRUE)

# plot of residuals as function of the fitted value
plot(f, plot.type = "fitted_residuals")


# (2) an example on a microarray data set (a subsample of a greater data set) 
#

datafilename <- system.file("extdata", "transcripto_sample.txt", package="DRomics")

(o <- microarraydata(datafilename, check = TRUE, norm.method = "cyclicloess"))
(s_quad <- itemselect(o, select.method = "quadratic", FDR = 0.05))
(f <- drcfit(s_quad, progressbar = TRUE))

# Default plot
plot(f)

# Plot of the fit of the first 12 most responsive items
plot(f, items = 12)

# Plot of the chosen items in the chosen order
plot(f, items = c("301.2", "363.1", "383.1"))

# Look at the table of results for successful fits
head(f$fitres)

# Look at the table of results for unsuccessful fits
head(f$unfitres)


# (3) Comparison of parallel and non paralell implementations on a 
#     larger selection of items
#

   s_quad <- itemselect(o, select.method = "quadratic", FDR = 0.05)
    system.time(f1 <- drcfit(s_quad, progressbar = TRUE))
   system.time(f2 <- drcfit(s_quad, progressbar = FALSE, parallel = "snow", ncpus = 2))
   
   
# }