diff --git a/NAMESPACE b/NAMESPACE index 67c3e19..3eb7f9f 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -13,6 +13,6 @@ export(intelliframe) export(plot_curves) export(print) export(read_xmap) -importFrom(S7,"@") +export(refit_curves) importFrom(rlang,.data) importFrom(stats,reformulate) diff --git a/R/luminary-package.R b/R/luminary-package.R index e9e6850..01d1a03 100644 --- a/R/luminary-package.R +++ b/R/luminary-package.R @@ -2,7 +2,6 @@ "_PACKAGE" ## usethis namespace: start -#' @importFrom S7 @ #' @importFrom stats reformulate ## usethis namespace: end NULL diff --git a/R/refit_curves.R b/R/refit_curves.R index 9f83b4b..25fc722 100644 --- a/R/refit_curves.R +++ b/R/refit_curves.R @@ -4,26 +4,45 @@ #' and interpolate concentrations for all samples, based on the updated models. #' #' @details +#' Most of these details have been reproduced from the \code{\link{nplr}} function that is doing most of the heavy lifting. +#' #' The 5-parameter logistic regression is of the form: -#' y = B + (T - B)/[1 + 10^(b*(xmid - x))]^s +#' \deqn{y = B + (T - B)/[1 + 10^{(b*(x_{\text{mid}} - x))}]^s} +#' +#' where \eqn{B} and \eqn{T} are the bottom and top asymptotes, respectively, +#' \eqn{b} and \eqn{x_{\text{mid}}} are the Hill slope and the x-coordinate at +#' the inflection point, respectively, and \eqn{s} is an asymmetric coefficient. +#' This equation is sometimes referred to as the Richards' equation \[1,2\]. +#' When specifying \code{npars = 4}, the \eqn{s} parameter is forced to be 1, +#' and the corresponding model is a 4-parameter logistic regression, symmetrical +#' around its inflection point. When specifying \code{npars = 3} or \code{npars = 2}, +#' add 2 more constraints and force \eqn{B} and \eqn{T} to be 0 and 1, respectively. #' -#' where B and T are the bottom and top asymptotes, respectively, b and xmid are the Hill slope and the x-coordinate at the inflexion point, respectively, and s is an asymetric coefficient. This equation is sometimes refered to as the Richards' equation [1,2]. -#' When specifying npars = 4, the s parameter is forced to be 1, and the corresponding model is a 4-parameter logistic regression, symetrical around its inflexion point. When specifying npars = 3 or npars = 2, add 2 more constraints and force B and T to be 0 and 1, respectively. #' Weight methods: -#' The model parameters are optimized, simultaneously, using nlm, given a sum of squared errors function, sse(Y), to minimize: -#' sse(Y) = Σ [W.(Yobs - Yfit)^2 ] -#' where Yobs, Yfit and W are the vectors of observed values, fitted values and weights, respectively. -#' In order to reduce the effect of possible outliers, the weights can be computed in different ways, specified in nplr: -#' residual weights, "res": -#' W = (1/residuals)^LPweight -#' where residuals and LPweight are the squared error between the observed and fitted values, and a tuning parameter, respectively. Best results are generally obtained by setting LPweight = 0.25 (default value), while setting LPweight = 0 results in computing a non-weighted sum of squared errors. -#' standard weights, "sdw": -#' W = 1/Var(Yobs_r) -#' where Var(Yobs_r) is the vector of the within-replicates variances. -#' general weights, "gw": -#' W = 1/Yfit^LPweight -#' where Yfit are the fitted values. As for the residuals-weights method, setting LPweight = 0 results in computing a non-weighted sum of squared errors. -#' The standard weights and general weights methods are describes in [3]. +#' +#' The model parameters are optimized, simultaneously, using \code{\link{nlm}}, +#' given a sum of squared errors function, \eqn{\text{sse(Y)}}, to minimize: +#' \deqn{\text{sse}(Y) = Σ [W(Y_{\text{obs}} - Y_{\text{fit}})^2 ]} +#' where \eqn{Y_{\text{obs}}}, \eqn{Y_{\text{fit}}} and \eqn{W} are the vectors +#' of observed values, fitted values and weights, respectively. +#' In order to reduce the effect of possible outliers, the weights can be computed in different ways: +#' +#' residual weights, \code{"res"}: +#' \deqn{W = (1/\text{residuals})^\text{LPweight}} +#' where \eqn{\text{residuals}} and \eqn{\text{LPweight}} are the squared error +#' between the observed and fitted values, and a tuning parameter, respectively. +#' Best results are generally obtained by setting \code{LPweight = 0.25} (default value), +#' while setting \code{LPweight = 0} results in computing a non-weighted sum of squared errors. +#' +#' standard weights, \code{"sdw"}: +#' \deqn{W = 1/\text{Var}(Y_{\text{obs}_r})} +#' where \eqn{\text{Var}(Y_{\text{obs}_r})} is the vector of the within-replicates variances. +#' +#' general weights, \code{"gw"}: +#' \deqn{W = 1/Y_{\text{fit}}^\text{LPweight}} +#' where \eqn{Y_{\text{fit}}} are the fitted values. As for the residuals-weights method, +#' setting \eqn{LPweight = 0} results in computing a non-weighted sum of squared errors. +#' The standard weights and general weights methods are described in \[3\]. #' @param .data Intelliframe object to refit #' @param npars A numeric value (or \code{"all"}) to specify the number of #' parameters to use in the model. If \code{"all"} the logistic model will be @@ -31,17 +50,30 @@ #' See Details. #' @param weight_method A character string to specify what weight method to use. #' Options are \code{"res"}(default), \code{"sdw"}, \code{"gw"}. See Details. +#' @param LPweight a coefficient to adjust the weights. \code{LPweight = 0} will +#' compute a non-weighted np-logistic regression. #' @param add_to_zeroes A numeric value (\code{0.1} by default) added to zeros during #' the curve fitting procedure as it requires the concentration to be #' log10-transformed. #' @param silent Logical flag indicating whether warnings and/or messages during #' curve fitting should be silenced. Defaults to \code{FALSE}. #' -#' @return +#' @references +#' 1- Richards, F. J. (1959). A flexible growth function for empirical use. J Exp Bot 10, 290-300. +#' +#' 2- Giraldo J, Vivas NM, Vila E, Badia A. Assessing the (a)symmetry of +#' concentration-effect curves: empirical versus mechanistic models. Pharmacol Ther. 2002 Jul;95(1):21-45. +#' +#' 3- Motulsky HJ, Brown RE. Detecting outliers when fitting data with nonlinear +#' regression - a new method based on robust nonlinear regression and the false +#' discovery rate. BMC Bioinformatics. 2006 Mar 9;7:123. +#' +#' @return An intelliframe #' @export #' #' @examples -refit_curves <- function(.data, npars = "all", weight_method = "res", add_to_zeroes = 0.01, silent = FALSE) { +#' 1+1 +refit_curves <- function(.data, npars = "all", weight_method = "res", LPweight = 0.25, add_to_zeroes = 0.01, silent = FALSE) { well_data <- get_well_data(.data) @@ -66,11 +98,12 @@ refit_curves <- function(.data, npars = "all", weight_method = "res", add_to_zer ) fit <- nplr::nplr( - x = non_zero, - y = analyte$MFI/max(analyte$MFI), - npars = npars, - method = weight_method, - silent = silent + x = non_zero, + y = analyte$MFI/max(analyte$MFI), + npars = npars, + method = weight_method, + LPweight = LPweight, + silent = silent ) }) diff --git a/man/refit_curves.Rd b/man/refit_curves.Rd new file mode 100644 index 0000000..ebeb9d0 --- /dev/null +++ b/man/refit_curves.Rd @@ -0,0 +1,97 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/refit_curves.R +\name{refit_curves} +\alias{refit_curves} +\title{Refit standard curves} +\usage{ +refit_curves( + .data, + npars = "all", + weight_method = "res", + LPweight = 0.25, + add_to_zeroes = 0.01, + silent = FALSE +) +} +\arguments{ +\item{.data}{Intelliframe object to refit} + +\item{npars}{A numeric value (or \code{"all"}) to specify the number of +parameters to use in the model. If \code{"all"} the logistic model will be +tested with 2 to 5 parameters, and the best option will be returned. +See Details.} + +\item{weight_method}{A character string to specify what weight method to use. +Options are \code{"res"}(default), \code{"sdw"}, \code{"gw"}. See Details.} + +\item{LPweight}{a coefficient to adjust the weights. \code{LPweight = 0} will +compute a non-weighted np-logistic regression.} + +\item{add_to_zeroes}{A numeric value (\code{0.1} by default) added to zeros during +the curve fitting procedure as it requires the concentration to be +log10-transformed.} + +\item{silent}{Logical flag indicating whether warnings and/or messages during +curve fitting should be silenced. Defaults to \code{FALSE}.} +} +\value{ +An intelliframe +} +\description{ +Function to refit n-parameter logistic curves to standards in an intelliframe object +and interpolate concentrations for all samples, based on the updated models. +} +\details{ +Most of these details have been reproduced from the \code{\link{nplr}} function that is doing most of the heavy lifting. + +The 5-parameter logistic regression is of the form: +\deqn{y = B + (T - B)/[1 + 10^{(b*(x_{\text{mid}} - x))}]^s} + +where \eqn{B} and \eqn{T} are the bottom and top asymptotes, respectively, +\eqn{b} and \eqn{x_{\text{mid}}} are the Hill slope and the x-coordinate at +the inflection point, respectively, and \eqn{s} is an asymmetric coefficient. +This equation is sometimes referred to as the Richards' equation [1,2]. +When specifying \code{npars = 4}, the \eqn{s} parameter is forced to be 1, +and the corresponding model is a 4-parameter logistic regression, symmetrical +around its inflection point. When specifying \code{npars = 3} or \code{npars = 2}, +add 2 more constraints and force \eqn{B} and \eqn{T} to be 0 and 1, respectively. + +Weight methods: + +The model parameters are optimized, simultaneously, using \code{\link{nlm}}, +given a sum of squared errors function, \eqn{\text{sse(Y)}}, to minimize: +\deqn{\text{sse}(Y) = Σ [W(Y_{\text{obs}} - Y_{\text{fit}})^2 ]} + where \eqn{Y_{\text{obs}}}, \eqn{Y_{\text{fit}}} and \eqn{W} are the vectors +of observed values, fitted values and weights, respectively. +In order to reduce the effect of possible outliers, the weights can be computed in different ways: + +residual weights, \code{"res"}: +\deqn{W = (1/\text{residuals})^\text{LPweight}} +where \eqn{\text{residuals}} and \eqn{\text{LPweight}} are the squared error +between the observed and fitted values, and a tuning parameter, respectively. +Best results are generally obtained by setting \code{LPweight = 0.25} (default value), +while setting \code{LPweight = 0} results in computing a non-weighted sum of squared errors. + +standard weights, \code{"sdw"}: +\deqn{W = 1/\text{Var}(Y_{\text{obs}_r})} +where \eqn{\text{Var}(Y_{\text{obs}_r})} is the vector of the within-replicates variances. + +general weights, \code{"gw"}: +\deqn{W = 1/Y_{\text{fit}}^\text{LPweight}} +where \eqn{Y_{\text{fit}}} are the fitted values. As for the residuals-weights method, +setting \eqn{LPweight = 0} results in computing a non-weighted sum of squared errors. +The standard weights and general weights methods are described in [3]. +} +\examples{ +1+1 +} +\references{ +1- Richards, F. J. (1959). A flexible growth function for empirical use. J Exp Bot 10, 290-300. + +2- Giraldo J, Vivas NM, Vila E, Badia A. Assessing the (a)symmetry of +concentration-effect curves: empirical versus mechanistic models. Pharmacol Ther. 2002 Jul;95(1):21-45. + +3- Motulsky HJ, Brown RE. Detecting outliers when fitting data with nonlinear +regression - a new method based on robust nonlinear regression and the false +discovery rate. BMC Bioinformatics. 2006 Mar 9;7:123. +}