From 7b38b3fa3872a8858d72eaeb5fa73106f113cde2 Mon Sep 17 00:00:00 2001 From: Hefin Rhys Date: Tue, 9 Jan 2024 14:51:21 +0000 Subject: [PATCH] Finished documenting u5plex data, and got mathjax working in refit_curves details. --- DESCRIPTION | 6 ++++-- NAMESPACE | 2 +- R/data.R | 21 +++++++++++++++++++++ R/luminary-package.R | 1 + R/refit_curves.R | 33 +++++++++++++++++---------------- man/extract_sheet_data.Rd | 7 ++++--- man/read_xmap.Rd | 3 ++- man/refit_curves.Rd | 33 +++++++++++++++++---------------- man/u5plex.Rd | 31 +++++++++++++++++++++++++++++++ 9 files changed, 98 insertions(+), 39 deletions(-) create mode 100644 R/data.R create mode 100644 man/u5plex.Rd diff --git a/DESCRIPTION b/DESCRIPTION index a038928..f741cbd 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -15,6 +15,7 @@ License: GPL (>= 3) + file LICENSE Encoding: UTF-8 Roxygen: list(markdown = TRUE) RoxygenNote: 7.2.3 +RdMacros: mathjaxr Suggests: knitr, rmarkdown, @@ -31,8 +32,9 @@ Imports: scales, nplr, utils, - S7 + mathjaxr Config/testthat/edition: 3 Depends: - R (>= 2.10) + R (>= 2.10), + S7 LazyData: true diff --git a/NAMESPACE b/NAMESPACE index 80a6e4d..3494dbd 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -2,7 +2,6 @@ S3method(print,intelliframe) S3method(str,intelliframe) -export(extract_sheet_data) export(get_analytes) export(get_curve_data) export(get_expected) @@ -15,6 +14,7 @@ export(intelliframe) export(plot_curves) export(read_xmap) export(refit_curves) +importFrom(S7,props) importFrom(rlang,.data) importFrom(stats,reformulate) importFrom(stats,setNames) diff --git a/R/data.R b/R/data.R new file mode 100644 index 0000000..a03658b --- /dev/null +++ b/R/data.R @@ -0,0 +1,21 @@ +#' 5-plex intelliframe +#' +#' Data from a single, 5-plex xMAP experiment. +#' +#' @format An intelliframe object containing 5 analytes, 80 standard samples, 20 +#' control samples, and 1820 unknown samples +#' \describe{ +#' \item{@metadata}{A tibble of keyword-value pairs of instrument metadata.} +#' \item{@analytes}{A tibble of analyte metadata.} +#' \item{@expected}{A tibble containing the expected concentrations of analyte +#' standards.} +#' \item{@recovery}{A tibble containing the recovery values of analyte +#' standards (recovery = predicted / expected). } +#' \item{@recovery_avg}{A tibble of mean recovery values across replicates.} +#' \item{@well_data}{A tibble of predicted concentrations for all individual +#' wells.} +#' \item{@summary_data}{A tibble of mean predicted concentrations across all +#' replicates.} +#' \item{@curve_data}{A tibble of standard curve metadata.} +#' } +"u5plex" diff --git a/R/luminary-package.R b/R/luminary-package.R index e2f03fa..fc69efc 100644 --- a/R/luminary-package.R +++ b/R/luminary-package.R @@ -3,6 +3,7 @@ ## usethis namespace: start #' @importFrom rlang .data +#' @importFrom S7 props #' @importFrom stats reformulate #' @importFrom stats setNames #' @importFrom utils str diff --git a/R/refit_curves.R b/R/refit_curves.R index 3d78c4e..7e4a90e 100644 --- a/R/refit_curves.R +++ b/R/refit_curves.R @@ -1,5 +1,6 @@ #' Refit standard curves #' +#' \loadmathjax #' Function to refit n-parameter logistic curves to standards in an intelliframe object #' and interpolate concentrations for all samples, based on the updated models. #' @@ -7,41 +8,41 @@ #' 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} +#' \mjdeqn{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. +#' where \mjeqn{B}{} and \mjeqn{T}{} are the bottom and top asymptotes, respectively, +#' \mjeqn{b}{} and \mjeqn{x_{\text{mid}}}{} are the Hill slope and the x-coordinate at +#' the inflection point, respectively, and \mjeqn{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, +#' When specifying \code{npars = 4}, the \mjeqn{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. +#' add 2 more constraints and force \mjeqn{B}{} and \mjeqn{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 +#' given a sum of squared errors function, \mjeqn{\text{sse(Y)}}{}, to minimize: +#' \mjdeqn{\text{sse}(Y) = \sum{W(Y_{\text{obs}} - Y_{\text{fit}})^2 }}{} +#' where \mjeqn{Y_{\text{obs}}}{}, \mjeqn{Y_{\text{fit}}}{} and \mjeqn{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 +#' \mjdeqn{W = (1/\text{residuals})^\text{LPweight}}{} +#' where \mjeqn{\text{residuals}}{} and \mjeqn{\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. +#' \mjdeqn{W = 1/\text{Var}(Y_{\text{obs}_r})}{} +#' where \mjeqn{\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. +#' \mjdeqn{W = 1/Y_{\text{fit}}^\text{LPweight}}{} +#' where \mjeqn{Y_{\text{fit}}}{} are the fitted values. As for the residuals-weights method, +#' setting \mjeqn{\text{LPweight} = 0}{} results in computing a non-weighted sum of squared errors. #' The standard weights and general weights methods are described in \[3\]. #' @param .intelliframe Intelliframe object to refit #' @param npars A numeric value (or \code{"all"}) to specify the number of diff --git a/man/extract_sheet_data.Rd b/man/extract_sheet_data.Rd index 1c44bd3..05a01b8 100644 --- a/man/extract_sheet_data.Rd +++ b/man/extract_sheet_data.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/extract_sheet_data.R \name{extract_sheet_data} \alias{extract_sheet_data} -\title{Extract blocks of data from xlsx file exported from Belysa} +\title{Extract blocks of data from an xlsx file exported from Belysa} \usage{ extract_sheet_data(file, sheet, numeric_data = TRUE) } @@ -14,10 +14,11 @@ extract_sheet_data(file, sheet, numeric_data = TRUE) \item{numeric_data}{Whether the data being read are numeric (default = \code{TRUE}).} } \value{ -A tibble of sheet data data. +A tibble. } \description{ -this is a description +Read an single sheet from an .xlsx file exported from the Belysa software, +and return an intelliframe object. Not meant to be called by the user. } \examples{ 1 + 1 diff --git a/man/read_xmap.Rd b/man/read_xmap.Rd index b39a0a5..514c284 100644 --- a/man/read_xmap.Rd +++ b/man/read_xmap.Rd @@ -13,7 +13,8 @@ read_xmap(file) A tibble } \description{ -Read data from xMAP instrument (this is the description) +Reads a single xMap experiment exported from the Belysa software +as an .xlsx file, and returns an intelliframe object. } \examples{ 1 + 1 diff --git a/man/refit_curves.Rd b/man/refit_curves.Rd index ff47736..b599f5e 100644 --- a/man/refit_curves.Rd +++ b/man/refit_curves.Rd @@ -38,6 +38,7 @@ curve fitting should be silenced. Defaults to \code{FALSE}.} An intelliframe } \description{ +\loadmathjax Function to refit n-parameter logistic curves to standards in an intelliframe object and interpolate concentrations for all samples, based on the updated models. } @@ -45,41 +46,41 @@ and interpolate concentrations for all samples, based on the updated models. 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} +\mjdeqn{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. +where \mjeqn{B}{} and \mjeqn{T}{} are the bottom and top asymptotes, respectively, +\mjeqn{b}{} and \mjeqn{x_{\text{mid}}}{} are the Hill slope and the x-coordinate at +the inflection point, respectively, and \mjeqn{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, +When specifying \code{npars = 4}, the \mjeqn{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. +add 2 more constraints and force \mjeqn{B}{} and \mjeqn{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 +given a sum of squared errors function, \mjeqn{\text{sse(Y)}}{}, to minimize: +\mjdeqn{\text{sse}(Y) = \sum{W(Y_{\text{obs}} - Y_{\text{fit}})^2 }}{} +where \mjeqn{Y_{\text{obs}}}{}, \mjeqn{Y_{\text{fit}}}{} and \mjeqn{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 +\mjdeqn{W = (1/\text{residuals})^\text{LPweight}}{} +where \mjeqn{\text{residuals}}{} and \mjeqn{\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. +\mjdeqn{W = 1/\text{Var}(Y_{\text{obs}_r})}{} +where \mjeqn{\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. +\mjdeqn{W = 1/Y_{\text{fit}}^\text{LPweight}}{} +where \mjeqn{Y_{\text{fit}}}{} are the fitted values. As for the residuals-weights method, +setting \mjeqn{\text{LPweight} = 0}{} results in computing a non-weighted sum of squared errors. The standard weights and general weights methods are described in [3]. } \examples{ diff --git a/man/u5plex.Rd b/man/u5plex.Rd new file mode 100644 index 0000000..17d5519 --- /dev/null +++ b/man/u5plex.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/data.R +\docType{data} +\name{u5plex} +\alias{u5plex} +\title{5-plex intelliframe} +\format{ +An intelliframe object containing 5 analytes, 80 standard samples, 20 +control samples, and 1820 unknown samples +\describe{ +\item{@metadata}{A tibble of keyword-value pairs of instrument metadata.} +\item{@analytes}{A tibble of analyte metadata.} +\item{@expected}{A tibble containing the expected concentrations of analyte +standards.} +\item{@recovery}{A tibble containing the recovery values of analyte +standards (recovery = predicted / expected). } +\item{@recovery_avg}{A tibble of mean recovery values across replicates.} +\item{@well_data}{A tibble of predicted concentrations for all individual +wells.} +\item{@summary_data}{A tibble of mean predicted concentrations across all +replicates.} +\item{@curve_data}{A tibble of standard curve metadata.} +} +} +\usage{ +u5plex +} +\description{ +Data from a single, 5-plex xMAP experiment. +} +\keyword{datasets}