Package 'flexfit'

Title: Flexible Format Standard Curve Fitting and Data Processing
Description: More about what it does (maybe more than one line) Use four spaces when indenting paragraphs within the Description.
Authors: Who wrote it
Maintainer: The package maintainer <[email protected]>
License: GPL (>= 2)
Version: 0.99.0
Built: 2024-11-08 04:42:36 UTC
Source: https://github.com/eppicenter/flexfit

Help Index

Calculate Bounds Numerically

Description

Numerically finds roots for 4th derivative of the model function that are used to indicate "flat" portions of the curve.

Usage

calcBounds(FUNmod, par, xrange, seql = 200)

Arguments

FUNmod

model function
par

values of function parameters
xrange

range of function domain to be searched for roots
seql

length of the search grid

Details

to be added

Value

A named list with upper and lower bounds.

Calculate Bounds for Logistic function

Description

Calculates roots for 4th derivative of logistic function that are used to indicate "flat" portions of the curve.

Usage

calcBoundsSig(par, xrange)

Arguments

par

values of function parameters
xrange

range of function domain to be searched for roots

Details

to be added

Value

A named list with upper and lower bounds.

Extract Standards

Description

Separates specified serial dilutions for fitting, background, and samples

Usage

extractStd(MFI, stdstr, bgstr, stddil, smpdil, antigen, fname, pdate)

Arguments

MFI

data frame with variable "Sample" that contains information about standard concentrations in "1/dilution" format (e.g. "1/200").
stdstr

character string indicating standards in the file's "Sample" column. Not case sensitive. If "" (empty string), standards will be determined by the pattern "1/" only.
bgstr

character string indicating background in the file's "Sample" column. Not case sensitive.
stddil

standard dilutions to use for standard curve fitting. If NULL, all the dilutions indicated in a "Sample" variable are used.
smpdil

single value for sample dilutions (if dilutions are not provided in smp data frame). Ignored if dilvar is provided and the variable is included in smp data frame.
antigen

character string.
fname

name of the file that contains raw data.
pdate

date of the plate processing.

Details

details

Value

A list with standards for fitting, background values, sample values, indices for samples.

Fit Standards

Description

Fit a specified function to standards (serial dilutions). Optionally an interactive procedure that allows to remove outliers, evaluate resulting fits, perform revisions, and record a message regarding the fit.

Usage

fitStd(
  std,
  xvar,
  yvar,
  model = "sigmoid",
  Alow = NULL,
  asym = TRUE,
  interactive = TRUE,
  monot.prompt = FALSE,
  rm.before = FALSE,
  rm.after = interactive,
  maxrm = 2,
  set.bounds = FALSE,
  overwrite.bounds = FALSE,
  bg = NULL,
  vsmp = NULL,
  optmethod = "Nelder-Mead",
  maxit = 5000,
  extrapolate.low = FALSE,
  extrapolate.up = FALSE,
  info = "",
  ifix = NULL,
  tcklab = NULL,
  stdcol = c("firebrick3", "darkslategray"),
  rugcol = c("cadetblue", "purple", "firebrick2"),
  ...
)

Arguments

std

matrix or data frame with standards for fitting.
xvar, yvar

character strings for the variables used to fit a standard curve. If NULL, first two columns are assumed to be x and y variables.
model

the model to be fit.
Alow

lower asymptote for the sigmoid model. If NULL, the lower asymptote will be estimated, adding an extra parameter to the model. To fix the asymptote at the level of background, specify "bg". Numeric value of Alow will force the asymptote to be fixed at the provided level.
asym

if TRUE, asymmetry in the fit is allowed, adding an extra parameter to the model.
interactive

logical value. If TRUE, the user is prompted to evaluate the standards (and/or the fit) and asked to remove outliers if needed. TRUE value takes precedence over rm.before and rm.after: if both are FALSE, rm.after is reset to TRUE.
monot.prompt

if TRUE, the user is prompted to evaluate the standards and possibly remove outliers if the standards are not monotonic (increasing). FALSE value is ignored if interactive is TRUE.
rm.before

logical value indicating if potential outliers should be removed before the model is fitted. Ignored if interactive is FALSE.
rm.after

logical value indicating if potential outliers should be removed after the model is fitted. Ignored if interactive is FALSE.
maxrm

maximum number of outliers to remove.
set.bounds

if TRUE, the user is given the option to manually set the bound that is not set automatically. In that case, the prompt appears even if interactive is FALSE.
overwrite.bounds

logical value indicating the option to overwrite automatically set bounds. Ignored if interactive is FALSE.
bg

values for background spots.
vsmp

sample values.
optmethod

method to be used in optimization.
maxit

maximum number of iterations in optimization.
extrapolate.low

if TRUE, sample values beyond lower bounds will be processed by extrapolation of the standard curve (not recommended). Takes precedence over trim.flat value.
extrapolate.up

if TRUE, sample values beyond upper bounds will be processed by extrapolation of the standard curve (not recommended). Takes precedence over trim.flat value.
info

information about a particular run for warning messages.
ifix

sorted integer vector of length 3 with indices of standards to be used for getting starting values for optimization.
tcklab

tick labels for x-axis.
stdcol

vector of two colors for the standard points and the fit on the plot.
rugcol

vector of three colors for the rugplot, which indicates sample values (inside the bounds, between the bounds and extrema, and beyond extrema).
...

further graphical parameters.

Details

to be added

Value

A list containing parameters of the fit and bounds of the fit (named vectors), as well as indices of removed points (if any) and flags r.

Normalize Samples

Description

Calculate sample concentration based on the fit of standard dilutions.

Usage

normalizeSmp(
  smp,
  smpvar,
  resvar,
  dilvar,
  FUNinv,
  par,
  bounds,
  fitflag,
  fitlog,
  trim.flat = TRUE,
  extrapolate.low = FALSE,
  extrapolate.up = FALSE
)

Arguments

smp

data frame containing samples
smpvar

character string indicating sample variable.
dilvar, resvar

character strings for dilution variable and results.
FUNinv

inverse function to infer sample concentration
par

values of model function parameters
bounds

named vector with values for extrema and bounds indicating "flat" regions of the curve
fitflag

flag for the fit as returned by fitStd
fitlog

character string indicating if standard values should be log-transformed for fitting. If the string contains _x_, xvar will be transformed, if it contains _y_ - yvar.
trim.flat

logical value determining how the values of yvar are trimmed. If TRUE, they will be trimmed at the bounds where the curve starts to flatten out (automatically determined as maxima of the third derivative of the function). If FALSE, yvar will be trimmed at extrema, defined as the range of standards or asymptotes of the fit (whichever are less extreme).
extrapolate.low

if TRUE, sample values beyond lower bounds will be processed by extrapolation of the standard curve (not recommended). Takes precedence over trim.flat value.
extrapolate.up

if TRUE, sample values beyond upper bounds will be processed by extrapolation of the standard curve (not recommended). Takes precedence over trim.flat value.

Details

coming up

Value

A data frame.

Plot the fit for standards and the samples

Description

Produces a plot that includes points for standards, proposed fit, removed outliers, bounds for "flat" portions of the curve, and values for samples and for the background.

Usage

plotFit(
  std,
  xvar,
  yvar,
  fitpar = NULL,
  FUNmod = NULL,
  FUNinv = NULL,
  iout = NULL,
  bg = NULL,
  vsmp = NULL,
  smpflag = NULL,
  trimval = NULL,
  trimtype = NULL,
  extrapolate.low = FALSE,
  extrapolate.up = FALSE,
  ylim = NULL,
  tcklab = NULL,
  stdcol = c("firebrick3", "darkslategray"),
  rugcol = c("cadetblue", "purple", "firebrick2"),
  ...
)

Arguments

std

matrix or data frame with standards for fitting.
xvar, yvar

character strings for the variables used to fit a standard curve. If NULL, first two columns are assumed to be x and y variables.
fitpar

values of function parameters.
FUNmod

model function.
FUNinv

model inverse function.
iout

indices of removed standard points.
bg

background values.
vsmp

sample values.
smpflag

character vector, flags for each sample.
trimval

for final results, the values at which the samples are trimmed.
trimtype

integer vector of length two indicating if the values are trimmed at the extremum (lower and upper).
extrapolate.low

if TRUE, sample values beyond lower bounds will be processed by extrapolation of the standard curve (not recommended). Takes precedence over trim.flat value.
extrapolate.up

if TRUE, sample values beyond upper bounds will be processed by extrapolation of the standard curve (not recommended). Takes precedence over trim.flat value.
ylim

limits of the y-axis.
tcklab

tick labels for x-axis.
stdcol

vector of two colors for the standard points and the fit on the plot.
rugcol

vector of three colors for the rugplot, which indicates sample values (inside the bounds, between the bounds and extrema, and beyond extrema).
...

further graphical parameters.

Details

to be added

Reformat raw luminex files for processing

Description

Read in raw luminex files, extract standards and background (if provided), and format samples for processing.

Usage

prepLum(
  antigen,
  fname,
  fdir = NULL,
  dtype = "Median",
  stdstr = "std|stand",
  bgstr = "blank|background",
  stddil = NULL,
  smpdil = 1000,
  nwells = NULL,
  nsep = 2,
  ncolmax = 105,
  dformat = "%m/%d/%Y"
)

Arguments

antigen

character string.
fname

name of the file that contains raw data.
fdir

directory where the file is located (alternatively, full path can be included in fname).
dtype

character string for data type in the file.
stdstr

character string indicating standards in the file's "Sample" column. Not case sensitive. If "" (empty string), standards will be determined by the pattern "1/" only.
bgstr

character string indicating background in the file's "Sample" column. Not case sensitive.
stddil

a vector of standard dilutions. If NULL, dilutions are inferred from the file's "Sample" column. Non-null value can be used to exclude some dilutions from model fitting.
smpdil

single value for sample dilutions (if dilutions are not provided in smp data frame). Ignored if dilvar is provided and the variable is included in smp data frame.
nwells

number of wells. If NULL, inferred from the file.
nsep

number of lines separating different data types in the file.
ncolmax

maximum number of columns in the file.
dformat

date format in the file.

Details

to be added

Value

A list with standards for fitting, background values, sample values, indices for samples.

Process raw Luminex files

Description

Process data for a single antigen: fit a standard curve, establish bounds, normalize samples, and save a plot showing the fit and the samples.

Usage

processSmp(
  smp,
  std,
  bg = NULL,
  smpdil = 1,
  fitlog = "xy",
  ismp = 1:nrow(smp),
  plotdir = "./",
  pname = NULL,
  ptitle = "fit and samples",
  xvar = NULL,
  yvar = NULL,
  smpvar = NULL,
  addvar = NULL,
  dilvar = NULL,
  resvar = "concentration",
  model = "sigmoid",
  Alow = NULL,
  asym = TRUE,
  trim.flat = TRUE,
  interactive = TRUE,
  monot.prompt = FALSE,
  rm.before = FALSE,
  rm.after = interactive,
  maxrm = 2,
  set.bounds = interactive,
  overwrite.bounds = FALSE,
  ifix = NULL,
  extrapolate.low = FALSE,
  extrapolate.up = FALSE,
  optmethod = "Nelder-Mead",
  maxit = 5000,
  stdcol = c("firebrick3", "darkslategray"),
  rugcol = c("cadetblue", "purple", "firebrick2"),
  width = 7,
  height = 6,
  ...
)

Arguments

smp

data frame with sample ID, sample values and other optional variables (e.g. dilution).
std

matrix or data frame with standards for fitting.
bg

values for background spots.
smpdil

single value for sample dilutions (if dilutions are not provided in smp data frame). Ignored if dilvar is provided and the variable is included in smp data frame.
fitlog

character string indicating if standard values should be log-transformed for fitting. If the string contains _x_, xvar will be transformed, if it contains _y_ - yvar.
ismp

indices for samples to be plotted (e.g. to exclude standards that are included in smp data frame).
plotdir

directory for the plots to be saved.
pname

character string for fit plot. If NULL, will be based on ptitle with underscore substituted for space.
ptitle

character string for plot title.
xvar, yvar

character strings for the variables used to fit a standard curve. If NULL, first two columns are assumed to be x and y variables.
smpvar

character string indicating sample variable.
addvar

named vector for additional variables (e.g. date or plate), where element names will be used as variable names in smp.
dilvar, resvar

character strings for dilution variable and results.
model

the model to be fit.
Alow

lower asymptote for the sigmoid model. If NULL, the lower asymptote will be estimated, adding an extra parameter to the model. To fix the asymptote at the level of background, specify "bg". Numeric value of Alow will force the asymptote to be fixed at the provided level.
asym

if TRUE, asymmetry in the fit is allowed, adding an extra parameter to the model.
trim.flat

logical value determining how the values of yvar are trimmed. If TRUE, they will be trimmed at the bounds where the curve starts to flatten out (automatically determined as maxima of the third derivative of the function). If FALSE, yvar will be trimmed at extrema, defined as the range of standards or asymptotes of the fit (whichever are less extreme).
interactive

logical value. If TRUE, the user is prompted to evaluate the standards (and/or the fit) and asked to remove outliers if needed. TRUE value takes precedence over rm.before and rm.after: if both are FALSE, rm.after is reset to TRUE.
monot.prompt

if TRUE, the user is prompted to evaluate the standards and possibly remove outliers if the standards are not monotonic (increasing). FALSE value is ignored if interactive is TRUE.
rm.before

logical value indicating if potential outliers should be removed before the model is fitted. Ignored if interactive is FALSE.
rm.after

logical value indicating if potential outliers should be removed after the model is fitted. Ignored if interactive is FALSE.
maxrm

maximum number of outliers to remove.
set.bounds

if TRUE, the user is given the option to manually set the bound that is not set automatically. In that case, the prompt appears even if interactive is FALSE.
overwrite.bounds

logical value indicating the option to overwrite automatically set bounds. Ignored if interactive is FALSE.
ifix

sorted integer vector of length 3 with indices of standards to be used for getting starting values for optimization.
extrapolate.low

if TRUE, sample values beyond lower bounds will be processed by extrapolation of the standard curve (not recommended). Takes precedence over trim.flat value.
extrapolate.up

if TRUE, sample values beyond upper bounds will be processed by extrapolation of the standard curve (not recommended). Takes precedence over trim.flat value.
optmethod

method to be used in optimization.
maxit

maximum number of iterations in optimization.
stdcol

vector of two colors for the standard points and the fit on the plot.
rugcol

vector of three colors for the rugplot, which indicates sample values (inside the bounds, between the bounds and extrema, and beyond extrema).
width, height

optional parameters for the final saved plot.
...

further graphical parameters.

Details

Note that if fitlog contains _x_ and thus xvar in standards is log-transform before fitting, the results are still returned on a regular scale (values of inverse function are exponentiated and then multiplied by dilution).

Value

A list of length three. The first element is a data frame that contains the results; the second is a character string with a flag containing information about removed points, failure to fit the model, manually set bounds, and/or an optional custom note provided by the user during an interactive model-fitting procedure. The last element is the number of sample values for which the results are trimmed.

Read in raw luminex data

Description

Extract specified data type from the file.

Usage

read_data(fname, dtype = "Median", nwells = NULL, nsep = 2, ncolmax = 105)

Arguments

fname

name of the file that contains raw data.
dtype

character string for data type in the file.
nwells

number of wells. If NULL, inferred from the file.
nsep

number of lines separating different data types in the file.
ncolmax

maximum number of columns in the file.

Details

to be added

Value

A data frame.