batch: Batch-processing function for immunoassay data.
In immunoassay: Functions for working with immunoassay data.

Description Usage Arguments Details Value Note Author(s) See Also Examples

This is a wrapper function making use of other lower-level functions in this package. It looks for immunoassay data files in a given folder, processes these files and accumulates results into a single data frame. Optionally, it can create a project report - either in a simple text form, or in LaTeX format.

batch(path, subfolder = "", kit.file = NULL, analytes = "all", 
    run.options     = list(CTS = 20, MFI = "last", CV = 20), 
    model.options   = list(model = "L.5", weights = "sqrt", 
                      refit = 0.2, use = 1, stvals = "adaptive"), 
    project.options = list(report = "text", template = "short", 
                      trace = TRUE), 
    correct.errors  = NULL)

`path`	Character string. Path to the main project folder. A csv file with kit data should be located in that folder. Also, all subfolders are created in this folder.
`subfolder`	Character string. If the csv files with immunoassay data are located in the subfolder of the main folder, provide its name here. Otherwise, leave blank.
`kit.file`	Character string. File name of the csv file containing kit information. If a `data.frame` named `"immunoassay.kits"` exists, it will be used, and this parameter will be ignored.
`analytes`	Character or numeric. This parameter is passed to `read.multiplex` function. See more information there.
`run.options`	List of 3 elements that provide validation criteria: `CTS` - numeric, is the threshold for COUNTS; `MFI` - character, either "last" or "first", that is the last of first calibrator becomes the criteria for lowest MFI; and `CV` - numeric, percent CV that is threshold for between-replicate variability.
`model.options`	A list of 5 elements. Element `model` - a character or list of character values of length N, where "N" is the number of data files in the folder. Element `weights` - a character or list of character values of length N. Element `refit` - a numeric value or list of numeric values of length N. Element `use` - a numeric value or list of numeric values of length N. Element `stvals` - a character or list of character values of length N. For more information on these parameters, see help for `sigfit`
`project.options`	A list of 3 elements. Element `report` - character, either "text" or "latex" options are currently available, defaults to "text". Element `template` - character. For `report="text"` option two templates are built-in: `"short"`, that produces quick summary of each analyte for each plate, and `"full"` - an extended template with more information. Defaults to `"short"`. For `report="latex"` option, this is the name of a LaTeX template, located in the main project folder. For more information, see details below. Element `trace` - logical, debugging option. If true, trace information will be displayed when the function is processing data files. Defaults to `FALSE`.
`correct.errors`	A list - an alternative means to introduce corrections to the fit parameters for a small number of items. In this list, each named element is a list. The named element's name must be the name of the datafile that is to be corrected. There must be two elements in each named sub-list: `name`, that names the parameter to be corrected (currently only `name="use"` is implemented), and the second element `value` is the new value of the named parameter. Defaults to `NULL`.

The batch function is the core function of this library. It implements automation in processing of entire folders of immunoassay data files. The function first looks for immunoassay files (currently limited to multiplex data files) under the provided path - it does so intelligently, so it can distinguish immunoassay run files from other .csv files. Then it creates a list of names of these files and processes through this list according to provided options.

For each file from the list, this function loads it using read.multiplex and fits the sigmoidal model using sigfit function with the set of parameters given in model.options. Next, it validates the fitted data using the criteria provided in run.options parameter, and finally, it creates a report as set in the project.options.

There are two major advantages of using this function, instead of manually processing the data: it can save substantial amount of time in processing of large number of data files, while preserving considerable flexibility in setting fit parameters and applying corrections. The second major advantage is the ability to create reports. Text reports are useful for obtaining general insight into the data and fitting process, but this function can really shine in connection with Sweave LaTeX report templates, that can be elaborate programs on themselves.

In order to use LaTeX template option, the user must create a minimum of two template files. These must be named: "my-project-name.run-report.r" - a template for each plate, and "my-project-name.project-report.r" - a project-wide template incorporating (or not) individual plate reports. The "my-project-name" part of the template name must be provided as the template= parameter, when report="latex" option is used. These templates are "Sweaved" in the process of running this function.

There is one known problem associated with use of the Sweave function - it's that the Sweave works in global environment and doesn't "see" the environment within the batch function it has been called from. To overcome this, the batch function sets a global variable - a pointer to its environment, named "immunoassay.environment". Objects and data from within batch function can be then accessed within the Sweave templates using immunoassay.environment$ pre-fix.

For LaTeX template programmers, the list of the accessible objects within immunoassay.environment is as follows: validate - validation function; immunoassay.coefs (global) - list of all fit coefficients; immunoassay.kits (global) - a data.frame with kits information; ppath - full path to the data files; files - list of valid immunoassay files; N - number of files (length(files)); l.analytes - vector of analyte names; n - number of analytes (length(l.analytes)); l.run - a data.frame of class ima, containing the validated run data; and fits - a list of fitted nls models, of length "n". After all the plates are processed, additional object becomes available: results - a data.frame being a collection of all results from all plates, for use in the project-wide report.

This function returns a simple data frame that is the collection of results from all processed files. It does not contain any fit information - if fit information are required, some form of report must be called.
In addition to the returned data.frame this function by default creates three global objects: the immunoassay.coefs list - a list of model coefficients for each fitted run file, and each model type; the immunoassay.options - a list of model parameters for all run files; and immunoassay.environment - a pointer to the environment of the batch function for use by the Sweave report templates.

Examples of LaTeX report templates from an example project are located in the "templates" directory in the main package folder. See help for the example project for more information.

Michal J. Figurski, PhD mfigrs@gmail.com of the Biomarker Research Laboratory, University of Pennsylvania, Philadelphia, PA.

immunoassay package, example project, read.multiplex, read.kits and sigfit.

## Not run: 

a <- batch("path-to-my-project", subfolder="Results", 
     kit.file="kit-file-name.csv",  analytes=1:2, 
     model.options   = list(model="L.5", weights=c("sqrt","1/y"), refit=0.2, 
                       use=1, stvals="adaptive"),
     project.options = list(report="latex", template="my-project-name", 
                       trace=FALSE),
     correct.errors  = list(`Plasma Pl072.csv`=list(name="use", 
                       value=c(0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1))))


## End(Not run)