tcpl (version 1.2.2)

tcplVarMat: Create chemical by assay matrices

Description

tcplVarMat creates chemical by assay matrices.

Usage

tcplVarMat(chid = NULL, aeid = NULL, add.vars = NULL, row.id = "code", flag = TRUE, cyto.pars = list(), include.na.chid = FALSE, odir = NULL, file.prefix = NULL)

Arguments

chid

Integer, chemical ID values to subset on

aeid

Integer, assay endpoint ID values to subset on

add.vars

Character, mc4 or mc5 field(s) not included in the standard list to add additional matrices

row.id

Character, the chemical identifier to use in the output

flag

Integer or Logical of length 1, passed to tcplSubsetChid

cyto.pars

List, named list of arguments passed to tcplCytoPt

include.na.chid

Logical of length 1, whether to include the chemicals not listed in the tcpl databases (ie. controls)

odir

Directory to write comma separated file(s)

file.prefix

Character of length 1, prefix to the file name when odir is not NULL

Value

A list of chemical by assay matrices where the rownames are given by the 'row.id' paramter, and the colnames are given by assay endpoint name (aenm).

Details

The tcplVarMat function is used to create chemical by assay matrices for different paramters. The standard list of matrices returned includes:

1. "modl_ga" -- The logAC50 (in the gain direction) for the winning model.
2. "hitc" -- The hit-call for the winning model.
3. "m4id" -- The m4id, listing the concentration series selected by tcplSubsetChid.
4. "zscore" -- The z-score based on the output from tcplCytoPt. The formula used for calculating the z-score is $-(\mathit{modl\_ga} - \mathit{cyto\_pt})/\mathit{global\_mad}$
5. "tested" -- 1 or 0, 1 indicating the chemical/assay pair was tested in either the single- or multiple-concentration format
6. "tested_sc" -- 1 or 0, 1 indicating the chemical/assay pair was tested in the single-concentration format
7. "tested_mc" -- 1 or 0, 1 indicating the chemical/assay pair was tested in the multiple-concentration format
8. "ac50" -- a modified AC50 table (in non-log units) where assay/chemical pairs that were not tested, or tested and had a hitcall of 0 or -1 have the value 1e6.
9. "neglogac50" -- -log(AC50/1e6) where assay/chemical pairs that were not tested, or tested and had a hitcall of 0 or -1 have the value 0.

To add addtitional matrices, the 'add.vars' parameter can be used to specify the fields from the mc4 or mc5 tables to create matrices for.

When more than one sample is included for a chemical/assay pair, tcplVarMat aggregates multiple samples to a chemical level call utilizing tcplSubsetChid.

By setting odir the function will write out a csv with, naming the file with the convention: "var_Matrix_date.csv" where 'var' is the name of the matrix. A prefix can be added to the output files using the 'file.prefix' paramter.

When a concentration series has a sample id not listed in the tcpl database, and 'include.na.chid' is TRUE, the rowname for that series will be the concatenation of "SPID_" and the spid. Note, if the user gives a subset of chid values to the 'chid' parameter, 'include.na.chid' will be set to FALSE with a warning.

The tcplVarMat function calls both tcplSubsetChid and tcplCytoPt (which separately calls tcplSubsetChid). The input for the tcplVarMat 'flag' parameter is passed to the tcplSubsetChid call used to parse down the data to create the matrices. The tcplSubsetChid called within tcplCytoPt (to parse down the cytotoxicity data used to define the "zscore" matrix) can be modified by passing a separate 'flag' element in the list defined by the 'cyto.pars' parameter.

See Also

tcplSubsetChid

Examples

## Store the current config settings, so they can be reloaded at the end 
## of the examples
conf_store <- tcplConfList()
tcplConfDefault()

## Demonstrate the returned values. Note with no "burst" assays defined in
## the example database, the user must provide which aeid values to use 
## in calculating the cytotoxicity distributions for the 'zscore' matrix.
tcplVarMat(chid = 1:5, cyto.pars = list(aeid = 1:2))

## Other changes can be made
tcplVarMat(chid = 1:5, row.id = "chnm", cyto.pars = list(aeid = 1:2))
tcplVarMat(chid = 1:5, add.vars = "max_med", cyto.pars = list(aeid = 1:2))

## Reset configuration
options(conf_store)