drcfit | R Documentation |

Fits dose reponse models to responsive items.

drcfit(itemselect, information.criterion = c("AICc", "BIC", "AIC"), postfitfilter = TRUE, preventsfitsoutofrange = TRUE, enablesfequal0inGP = TRUE, enablesfequal0inLGP = TRUE, progressbar = TRUE, parallel = c("no", "snow", "multicore"), ncpus) ## S3 method for class 'drcfit' print(x, ...) ## S3 method for class 'drcfit' plot(x, items, plot.type = c("dose_fitted", "dose_residuals","fitted_residuals"), dose_log_transfo = FALSE, BMDoutput, BMDtype = c("zSD", "xfold"), ...) plotfit2pdf(x, items, plot.type = c("dose_fitted", "dose_residuals", "fitted_residuals"), dose_log_transfo = FALSE, BMDoutput, BMDtype = c("zSD", "xfold"), nrowperpage = 6, ncolperpage = 4, path2figs = getwd())

`itemselect` |
An object of class |

`information.criterion` |
The information criterion used to select the best fit model, |

`postfitfilter` |
If |

`preventsfitsoutofrange` |
If |

`enablesfequal0inGP` |
If |

`enablesfequal0inLGP` |
If |

`progressbar` |
If |

`parallel` |
The type of parallel operation to be used, |

`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 |

`items` |
Argument of the |

`plot.type` |
The type of plot, by default |

`dose_log_transfo` |
Put at |

`BMDoutput` |
Argument that can be used to add BMD values
and optionally their confidence intervals on a plot of type |

`BMDtype` |
The type of BMD to add on the plot, |

`nrowperpage` |
Number of rows of plots when plots are saved in a pdf file using
plotfit2pdf() (passed to |

`ncolperpage` |
Number of columns of plots when plots are saved in a pdf file using
plotfit2pdf() (passed to |

`path2figs` |
File path when plots are saved in a pdf file using plotfit2pdf() |

`...` |
Further arguments passed to graphical or print functions. |

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) are fitted by non linear regression,
using the `nls`

function. If a fit of a biphasic model gives a extremum
value out of the range of the observed signal, it is eliminated (this may happen in rare cases,
especially on observational data when the number of samples is high and the dose in uncontrolled,
if doses are not distributed all along the dose range).
The best fit is chosen as the one giving the lowest AICc
(or BIC or AIC) value. The use of the AICc (second-order Akaike criterion)
instead of the AIC
is strongly recommended to prevent the overfitting that may occur with dose-response designs
with a small number of data points (Hurvich and Tsai, 1989; Burnham and Anderson DR, 2004).
Note that in the extremely rare cases where the number of
data points would be great, the AIC would converge to the AICc and both procedures would be equivalent.
Items with the best AICc value not lower than the AICc value of the null model (constant model) minus 2
are eliminated. Items with the best fit showing a global significant quadratic trend of the residuals
as a function of the dose (in rank-scale) are also eliminated (the best fit is considered as
not reliable in such cases).

Each retained item is classified in four classes by its global trend, which can be used to roughly describe the shape of each dose-response curve:

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 or if their simplified version with `f = 0`

is retained (corresponding to the probit model).
Some curves fitted by a log-Gauss-probit model can be classified as increasing or decreasing
if their simplified version with `f = 0`

is retained (corresponding to the log-probit model).

Each retained item is thus classified in a 16 class typology depending of the chosen model and of its parameter values :

H.inc for increasing Hill curves,

H.dec for decreasing Hill curves,

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,

GP.inc for increasing Gauss-probit curves,

GP.dec for decreasing Gauss-probit curves,

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

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

lGP.inc for increasing log-Gauss-probit curves,

lGP.dec for decreasing log-Gauss-probit curves,

`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 |

`omicdata` |
The object containing all the data, as given in input of |

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

`information.criterion.val` |
A data frame reporting the IC values (AICc, BIC or AIC) values for each selected item (one line per item) and each fitted model (one colum per model with the IC value fixed at |

`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 |

`residualtests` |
A data frame of P-values of the tests performed on residuals,
on the mean trend ( |

Marie-Laure Delignette-Muller

Burnham, KP, Anderson DR (2004). Multimodel inference: understanding AIC and BIC in model selection. Sociological methods & research, 33(2), 261-304.

Hurvich, CM, Tsai, CL (1989). Regression and time series model selection in small samples. Biometrika, 76(2), 297-307.

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.doi: 10.1021/acs.est.8b04752

See `nls`

for details about the non linear regression function and
`targetplot`

to plot target items (even if non responsive or unfitted).

# (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) # 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) # save all plots to pdf using plotfit2pdf() plotfit2pdf(f, path2figs = tempdir()) plotfit2pdf(f, plot.type = "fitted_residuals", nrowperpage = 9, ncolperpage = 6, path2figs = tempdir()) # 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) # count the number of unsuccessful fits for each cause table(f$unfitres$cause) # (3) Comparison of parallel and non paralell implementations on a larger selection of items # if(!requireNamespace("parallel", quietly = TRUE)) { if(parallel::detectCores() > 1) { 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)) }}

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.