Help for package toxpiR

Type:

Package

Title:

Create ToxPi Prioritization Models

Version:

1.3.0

Description:

Enables users to build 'ToxPi' prioritization models and provides functionality within the grid framework for plotting ToxPi graphs. 'toxpiR' allows for more customization than the 'ToxPi GUI' (https://toxpi.org) and integration into existing workflows for greater ease-of-use, reproducibility, and transparency. toxpiR package behaves nearly identically to the GUI; the package documentation includes notes about all differences. The vignettes download example files from https://github.com/ToxPi/ToxPi-example-files.

Imports:

grDevices, methods, S4Vectors, grid, rlang, stats, BiocGenerics, pryr, tidyr, utils, ggplot2

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.2.3

Depends:

R (≥ 4.0)

Suggests:

rmarkdown, knitr, testthat (≥ 3.0.0), covr, DBI

Config/testthat/edition:

Config/testthat/parallel:

true

VignetteBuilder:

knitr

License:

GPL (≥ 3)

URL:

https://github.com/ToxPi/toxpiR, https://toxpi.github.io/toxpiR/

BugReports:

https://github.com/ToxPi/toxpiR/issues

NeedsCompilation:

Packaged:

2024-08-29 13:40:12 UTC; flemingjf

Author:

Jonathon F Fleming

[aut, cre], Dayne L Filer

[aut, fnd], Dillon T Lloyd [aut], Preethi Thunga

[aut], Skylar W Marvel [aut], Alison A Motsinger-Reif

[fnd], David M Reif

[aut, fnd]

Maintainer:

Jonathon F Fleming <jffleming0129@gmail.com>

Repository:

CRAN

Date/Publication:

2024-09-12 16:00:02 UTC

toxpiR: Create ToxPi Prioritization Models

Description

Author(s)

Maintainer: Jonathon F Fleming jffleming0129@gmail.com (ORCID)

Authors:

Dayne L Filer dayne.filer@gmail.com (ORCID) [funder]
Dillon T Lloyd
Preethi Thunga (ORCID)
Skylar W Marvel
David M Reif reif.david@gmail.com (ORCID) [funder]

Other contributors:

Alison A Motsinger-Reif (ORCID) [funder]

ToxPi Model

Description

S4 class to store ToxPi models

Usage

TxpModel(txpSlices, txpWeights = NULL, txpTransFuncs = NULL)

## S4 method for signature 'TxpModel'
txpSlices(x)

## S4 replacement method for signature 'TxpModel'
txpSlices(x) <- value

## S4 method for signature 'TxpModel'
txpWeights(x, adjusted = FALSE)

## S4 replacement method for signature 'TxpModel'
txpWeights(x) <- value

## S4 method for signature 'TxpModel'
txpTransFuncs(x)

## S4 replacement method for signature 'TxpModel'
txpTransFuncs(x) <- value

## S4 method for signature 'TxpModel'
txpValueNames(x, simplify = FALSE)

## S4 method for signature 'TxpModel'
names(x)

## S4 replacement method for signature 'TxpModel'
names(x) <- value

## S4 method for signature 'TxpModel'
length(x)

## S4 method for signature 'TxpModel,TxpModel'
merge(x, y)

Arguments

txpSlices

Passed to txpSlices slot

txpWeights

Passed to txpWeights slot

txpTransFuncs

Passed to txpTransFuncs slot

x, y

TxpModel object

value

Replacement value

adjusted

Scalar logical, should the returned weights be adjusted such that they sum to 1?

simplify

Scalar logical, when TRUE the returned list is simplified

Functions

txpSlices(TxpModel): Return txpSlices slot
txpWeights(TxpModel): Return txpWeights slot
txpTransFuncs(TxpModel): Return txpTransFuncs slot
txpValueNames(TxpModel): Return list of txpValueNames slots for the contained TxpSliceList object, or vector when simplify = TRUE
names(TxpModel): Return slice names; shortcut for names(txpSlices(x))
length(TxpModel): Return number of slices in model; shortcut for length(txpSlices(x))
merge(x = TxpModel, y = TxpModel): Merge two TxpModel objects into a single model

Slots

txpSlices: TxpSliceList object
txpWeights: numeric vector specifying the relative weight of each slice; when NULL, defaults to 1 (equal weighting) for each slice
txpTransFuncs: TxpTransFuncList object (or list of functions coercible to TxpTransFuncList)

Examples

## Create TxpSliceList & TxpTransFuncList objects
s1 <- list(S1 = TxpSlice("inpt1"), S2 = TxpSlice("inpt2"))
tf <- list(NULL, sqrt = function(x) sqrt(x))

## Create TxpModel object
m1 <- TxpModel(txpSlices = s1, txpWeights = 2:1, txpTransFuncs = tf)
m1

## Access TxpModel slots
txpSlices(m1)
txpWeights(m1)
txpWeights(m1, adjusted = TRUE)
txpTransFuncs(m1)

## length
length(m1) ## equal to length(txpSlices(m1))
length(m1) == length(txpSlices(m1))

## names
names(m1) ## equal to names(txpSlices(m1))
all(names(m1) == names(txpSlices(m1)))

## Replacement
m2 <- m1
txpSlices(m2) <- list(S3 = TxpSlice("inpt3"), S4 = TxpSlice("inpt4"))
m2
names(m2)[2] <- "hello"
names(m2)
txpTransFuncs(m2) <- NULL
m2
txpTransFuncs(m2)[[1]] <- function(x) x^2
names(txpTransFuncs(m2))[1] <- "sq"
m2

## merge
m3 <- merge(m1, m2)
m3

List of TxpModel objects

Description

Extension of S4Vectors::SimpleList that holds only TxpModel objects.

Usage

TxpModelList(...)

## S4 method for signature 'TxpModelList'
duplicated(x)

as.TxpModelList(x)

Arguments

...

TxpModel object to create TxpModelList object

x

TxpModelList object

Functions

duplicated(TxpModelList): Returns logical vector of length(x), where TRUE indicates a duplicate model in the list; see base::duplicated
as.TxpModelList(): Coerce list or TxpModel objects to TxpModelList

Examples

## Create some TxpModel objects; see ?TxpModel for more details
s1 <- list(S1 = TxpSlice("inpt1"), S2 = TxpSlice("inpt2"))
tf <- list(NULL, sqrt = function(x) sqrt(x))
m1 <- TxpModel(txpSlices = s1, txpWeights = 2:1, txpTransFuncs = tf)
m2 <- m1
txpSlices(m2) <- list(S3 = TxpSlice("inpt3"), S4 = TxpSlice("inpt4"))
m3 <- merge(m1, m2)

## Build a TxpModelList object
TxpModelList(m1 = m1, m2 = m2, m3 = m3)

## Note: names are printed as '' when all are NULL
TxpModelList(m1, m2, m3)
names(TxpModelList(m1, m2, m3))

## Test for duplicates
duplicated(TxpModelList(m1 = m1, m2 = m2, m3 = m3))
duplicated(TxpModelList(m1 = m1, m2 = m1, m3 = m3))

## Coerce lists/TxpModel objects to TxpModelList
as(list(m1 = m1, m2 = m2, m3 = m3), "TxpModelList")
as.TxpModelList(list(m1 = m1, m2 = m2, m3 = m3))

as(m1, "TxpModelList")
as.TxpModelList(m1)

ToxPi Result

Description

S4 class to store ToxPi results

Usage

## S4 method for signature 'TxpResult'
txpScores(x)

## S4 method for signature 'TxpResult'
txpSliceScores(x, adjusted = TRUE)

## S4 method for signature 'TxpResult'
txpRanks(x)

## S4 method for signature 'TxpResult'
txpMissing(x)

## S4 method for signature 'TxpResult'
txpResultParam(x)

## S4 method for signature 'TxpResult'
txpModel(x)

## S4 method for signature 'TxpResult'
txpIDs(x)

## S4 replacement method for signature 'TxpResult'
txpIDs(x) <- value

## S4 method for signature 'TxpResult'
txpWeights(x, adjusted = FALSE)

## S4 method for signature 'TxpResult'
txpSlices(x)

## S4 method for signature 'TxpResult'
txpTransFuncs(x, level, simplify = FALSE)

## S4 method for signature 'TxpResult'
txpValueNames(x, simplify = FALSE)

## S4 method for signature 'TxpResult,logical,missing'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'TxpResult,integer,missing'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'TxpResult,numeric,missing'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'TxpResult,character,missing'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'TxpResult'
length(x)

## S4 method for signature 'TxpResult'
sort(x, decreasing = TRUE, na.last = TRUE, ...)

## S4 method for signature 'TxpResult'
names(x)

## S4 replacement method for signature 'TxpResult'
names(x) <- value

## S4 method for signature 'TxpResult'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  id.name = "id",
  score.name = "score",
  rank.name = "rank",
  adjusted = FALSE
)

Arguments

x

TxpResult object

adjusted

Logical scalar, when TRUE the weights are adjusted to sum to 1 or the slice scores are scaled to their respective weight

value

Replacement value

level

c('model', 'slices'); indicates whether to retrieve txpTransFuncs slot from the model or underlying slices

simplify

Logical scalar, flatten txpValueNames or txpTransFunc slots when retrieving slice-level information

i

Subsetting index

j, drop, optional

Not currently implemented

...

Passed to base::data.frame in as.data.frame or base::sort in sort

decreasing, na.last

Passed to base::sort

row.names

Passed to base::data.frame

id.name, score.name, rank.name

Character scalar; when coercing to base::data.frame, the name for the txpIDs, txpScores, and txpRanks columns, respectively

Functions

txpScores(TxpResult): Return txpScores slot
txpSliceScores(TxpResult): Return txpSliceScores slot; default adjusted = TRUE, i.e. return slice scores adjusted for weight
txpRanks(TxpResult): Return txpRanks slot
txpMissing(TxpResult): Return txpMissing slot
txpResultParam(TxpResult): Return txpResultParam slot
txpModel(TxpResult): Return txpModel slot
txpIDs(TxpResult): Return txpIDs slot
txpWeights(TxpResult): Return txpWeights slot from model – shortcut for txpWeights(txpModel(x)); default adjusted = FALSE, i.e. return unadjusted weights
txpSlices(TxpResult): Return txpSlices slot from model – shortcut for txpSlices(txpModel(x))
txpTransFuncs(TxpResult): Return txpTransFuncs slot from model – shortcut for txpTransFuncs(txpModel(x))
txpValueNames(TxpResult): Return txpValueNames slot from slices – shortcut for txpValueNames(txpSlices(txpModel(x)))
length(TxpResult): Return the number of observations; shortcut for length(txpScores(x))
sort(TxpResult): Sort the “TxpResult' object by their ranks
names(TxpResult): Returns IDs; equal to txpIDs(x)
as.data.frame(TxpResult): Coerce TxpResult to base::data.frame object with IDs, scores, ranks, and slice scores

Slots

txpScores: ⁠vector(<numeric>)⁠ of model scores
txpSliceScores: ⁠matrix(<numeric>)⁠, sample by slice matrix with individual slice scores
txpRanks: ⁠vector(<numeric>)⁠ with rank of scores
txpMissing: ⁠vector(<numeric>)⁠ with data missingness
txpModel: TxpModel object
txpIDs: ⁠vector(<character>)⁠ of observation IDs
txpResultParam: TxpResultParam object

Examples

## Load example dataset & model; see ?TxpModel for building model objects
data(txp_example_input, package = "toxpiR")
data(txp_example_model, package = "toxpiR")

## Calculate scores for single model; returns TxpResult object
res <- txpCalculateScores(model = txp_example_model, 
                          input = txp_example_input, 
                          id.var = "name")

## Accessors
txpScores(res)

txpSliceScores(res) ## adjusted for weight, by default
apply(txpSliceScores(res), 2, max, na.rm = TRUE)

txpSliceScores(res, adjusted = FALSE) ## each score should have maximum of 1
apply(txpSliceScores(res, adjusted = FALSE), 2, max, na.rm = TRUE)

txpRanks(res)

txpMissing(res)

txpModel(res)
identical(txpModel(res), txp_example_model)

txpIDs(res)
names(res) ## identical to txpIDs(res)
identical(txpIDs(res), names(res))

# Can access TxpModel slots directly
txpWeights(res)
txpWeights(res, adjusted = TRUE)
txpSlices(res)
# When retrieving transform functions, must specify level because both
# models and slices have transform functions
txpTransFuncs(res, level = "model")

# Can access TxpSliceList slots directly
txpValueNames(res)
txpValueNames(res, simplify = TRUE)
txpTransFuncs(res, level = "slices")
txpTransFuncs(res, level = "slices", simplify = TRUE)

## Subsetting
res[1]
res[c("chem01", "chem09")]
res[grepl("4|6", txpIDs(res))]
## Not run: 
res[c(TRUE, FALSE)] ## gets recycled with warning

## End(Not run)

## length -- returns number of observations
length(res)
length(res[1:5])

## sort
names(res)
names(sort(res))

txpScores(res)
txpScores(sort(res))
txpScores(sort(res, decreasing = FALSE))

## as.data.frame
as.data.frame(res)
as.data.frame(res, id.name = "nm", score.name = "scr", rank.name = "rnk")

Plot TxpResult objects

Description

Plot TxpResult objects

Usage

## S4 method for signature 'TxpResult,missing'
plot(
  x,
  package = c("grid", "ggplot2"),
  fills = NULL,
  showScore = TRUE,
  gp = NULL,
  vp = NULL,
  name = NULL,
  newpage = TRUE,
  ...,
  ncol = NULL,
  bgColor = "grey80",
  borderColor = "white",
  sliceBorderColor = "white",
  sliceValueColor = NULL,
  sliceLineColor = NULL,
  showMissing = TRUE,
  showCenter = TRUE
)

## S4 method for signature 'TxpResult,numeric'
plot(
  x,
  y,
  labels = NULL,
  newpage = TRUE,
  margins = c(4, 0, 1, 1),
  name = NULL,
  gp = NULL,
  vp = NULL,
  ...
)

Arguments

x

TxpResult object

package

Character scalar, choice of "grid" or "ggplot2" for plotting ToxPi profiles

fills

Vector of colors to fill slices. Set to NULL to use default

showScore

Logical scalar, overall score printed below the name when TRUE

gp, vp, name

Passed to grid::frameGrob when creating the plotting area

newpage

Logical scalar, grid::grid.newpage called prior to plotting when TRUE

...

Passed to pieGridGrob when plotting ToxPi and to pointsGrob when plotting ranks

ncol

Number of columns for ggplot2 ToxPi profiles

bgColor, borderColor, sliceBorderColor, sliceValueColor, sliceLineColor

Various color options when creating ggplot2 ToxPi profiles. Set to NULL for no color

showMissing

Boolean for coloring data missingness in ggplot2 ToxPi profiles

showCenter

Boolean for showing inner circle in ggplot2 ToxPi profiles. When set to False overrides showMissing

y

Rank vector, i.e. txpRanks(x)

labels

Integer vector, indices of x to label in the rank plot

margins

Passed to grid::plotViewport; only affects the scatterplot region margins

Details

It is strongly recommended to use a specific device (e.g., grDevices::png, grDevices::pdf) when creating rank plots. Using a GUI device will likely lead to inaccurate labeling, and any changes to the device size WILL lead to inaccurate labeling.

The plotting is built on the grid::grid-package, and can be adjusted or edited as such.

If the labels are running of the device, the top or bottom margins can be increased with the margins parameter.

ToxPi profiles can also be plotted using the ggplot2 package.

Value

No return value when using grid; called for side effect (i.e. drawing in current graphics device). Will return ggplot2 object otherwise.

Functions

plot(x = TxpResult, y = missing): Plot ToxPi diagrams
plot(x = TxpResult, y = numeric): Plot ToxPi ranks

Examples

## Load example dataset & model; see ?TxpModel for building model objects
data(txp_example_input, package = "toxpiR")
data(txp_example_model, package = "toxpiR")

## Calculate scores for single model; returns TxpResult object
res <- txpCalculateScores(model = txp_example_model, 
                          input = txp_example_input, 
                          id.var = "name")

library(grid)
plot(res)
plot(res[order(txpRanks(res))[1:4]])

library(ggplot2)
plot(res, package = "gg")
plot(res[order(txpRanks(res))], package = "gg", ncol = 5) +
  theme(legend.position = "bottom")

plot(res, txpRanks(res))
plot(res, txpRanks(res), pch = 16, size = unit(0.75, "char"))

## Will likely make inaccurate labels within a GUI, e.g. RStudio
## use png, pdf, etc. to get accurate labels
## Not run: 
tmpPdf <- tempfile()
pdf(tmpPdf)
plot(res, txpRanks(res), labels = c(10, 4, 2), pch = 16)
dev.off()

## End(Not run)

List of TxpResult objects

Description

Extension of S4Vectors::SimpleList that holds only TxpResult objects.

Usage

TxpResultList(...)

## S4 method for signature 'TxpResultList'
duplicated(x)

as.TxpResultList(x)

Arguments

...

TxpResult object to create TxpResultList object

x

TxpResultList object

Examples

## Load example dataset & model; see ?TxpModel for building model objects
data(txp_example_input, package = "toxpiR")
data(txp_example_model, package = "toxpiR")

## Calculate scores for list of models; returns TxpResultList object
txpCalculateScores(model = TxpModelList(m1 = txp_example_model, 
                                        m2 = txp_example_model), 
                   input = txp_example_input, 
                   id.var = "name")
resLst <- txpCalculateScores(model = list(m1 = txp_example_model, 
                                          m2 = txp_example_model), 
                             input = txp_example_input, 
                             id.var = "name")

## duplicated
duplicated(resLst)

## Coercion
as(list(resLst[[1]], resLst[[2]]), "TxpResultList")
as.TxpResultList(list(res1 = resLst[[1]], res2 = resLst[[2]]))

as(resLst[[1]], "TxpResultList")
as.TxpResultList(resLst[[1]])

ToxPi Result Parameters

Description

S4 class to store ToxPi result calculation parameters

Arguments

rank.ties.method

Passed to rank.ties.method slot

negative.value.handling

Passed to negative.value.handling slot

Details

If more than one value is passed to TxoResultParam scalar options, e.g. rank.ties.method, only the first value is kept.

The rank.ties.method slot is passed to base::rank for calculating the ranks of observations, with the highest-scoring observation having the rank of 1.

negative.value.handling indicates how to handle negative values in the inputs. The ToxPi algorithm originally intended to accept non-negative potency values; the GUI, therefore, treats negative values in the input as missing. By default, txpCalculateScores keeps negative values (negative.value.handling = "keep"). To replicate the GUI behavior, users can set negative.value.handling = "missing".

Slots

rank.ties.method: Character scalar, method used to calculate score ranks passed to base::rank
negative.value.handling: Character scalar, how negative values are handled, see details

ToxPi Slice

Description

S4 class to store ToxPi slices

Usage

TxpSlice(txpValueNames, txpTransFuncs = NULL)

## S4 method for signature 'TxpSlice'
txpValueNames(x)

## S4 replacement method for signature 'TxpSlice'
txpValueNames(x) <- value

## S4 method for signature 'TxpSlice'
txpTransFuncs(x)

## S4 replacement method for signature 'TxpSlice'
txpTransFuncs(x) <- value

## S4 method for signature 'TxpSlice'
length(x)

## S4 method for signature 'TxpSlice,TxpSlice'
merge(x, y)

Arguments

txpValueNames

Passed to txpValueNames slot

txpTransFuncs

Passed to txpTransFuncs slot

x, y

TxpSlice object

value

Replacement value

Details

If the user supplies txpTransFuncs a single function/TxpTransFunc object, the given function will be recycled for each input with a warning.

Functions

txpValueNames(TxpSlice): Return txpValueNames slot
txpTransFuncs(TxpSlice): Return txpTransFuncs slot
length(TxpSlice): Return number of inputs in slice; shortcut for length(txpValueNames(x))
merge(x = TxpSlice, y = TxpSlice): Merge two TxpSlice objects into a single slice

Slots

txpValueNames: ⁠vector(<character>)⁠ specifying the input columns to include in the slice
txpTransFuncs: TxpTransFuncList with one function per entry in txpValueNames or an object that can be coerced to TxpTransFuncList; when NULL, no transformation function applied

Examples

## Create TxpSlice object 
# Without transform functions
TxpSlice(txpValueNames = c("sqrData", "expData")) 
# With transform functions
TxpSlice(txpValueNames = c("sqrData", "expData"),
         txpTransFuncs = c(sq = function(x) x^2, log = function(x) log(x)))

# Transformation function recycled with warning when single function given
TxpSlice(txpValueNames = c("sqrData", "expData"), 
         txpTransFuncs = function(x) x^2) 
         

## Access TxpSlice slots
sl <- TxpSlice(txpValueNames = c("sqrData", "expData"),
               txpTransFuncs = c(sq = function(x) x^2, 
                                 log = function(x) log(x)))
txpValueNames(sl)
txpTransFuncs(sl)

## Replacement
txpValueNames(sl)[1] <- "hello"
sl

txpTransFuncs(sl)[[2]](exp(1))
txpTransFuncs(sl)[[2]] <- function(x) sqrt(x)
txpTransFuncs(sl)[[2]](exp(1))

# Note that replacing a single list element does NOT update the name
sl
names(txpTransFuncs(sl))[2] <- "sqrt" 
sl

# Replacing the whole list DOES update the names
txpTransFuncs(sl) <- list(sqrt = function(x) sqrt(x), 
                          log = function(x) log(x))
sl

## length -- returns number of inputs
length(TxpSlice(letters))

## merge
s1 <- TxpSlice("hello")
s2 <- TxpSlice("data")
merge(s1, s2)

# Note, input names still must be unique
## Not run: merge(s1, s1) ## produces error

List of TxpSlice objects

Description

Extension of S4Vectors::SimpleList that requires uniquely-named elements and holds only TxpSlice objects.

Usage

TxpSliceList(...)

## S4 method for signature 'TxpSliceList'
txpValueNames(x, simplify = FALSE)

## S4 method for signature 'TxpSliceList'
txpTransFuncs(x, simplify = FALSE)

## S4 method for signature 'TxpSliceList'
duplicated(x)

as.TxpSliceList(x)

Arguments

...

TxpSlice object to create TxpSliceList object; MUST give unique names to each slice

x

TxpSliceList object

simplify

Scalar logical, when TRUE the returned list is simplified to a vector/TxpTransFuncList object

Details

Note, there is no coercion for TxpSlice to TxpSliceList because unique names are required.

Functions

txpValueNames(TxpSliceList): Return list of txpValueNames slots for the contained TxpSlice objects, or vector when simplify = TRUE
txpTransFuncs(TxpSliceList): Return list of txpTransFuncs slots for the contained TxpSlice objects, or TxpTransFuncList when simplify = TRUE
duplicated(TxpSliceList): Returns logical vector of length(x), where TRUE indicates a duplicate slice in the list; see base::duplicated

Examples

## Create TxpSlice objects
s1 <- TxpSlice("input1", list(linear = function(x) x))
s2 <- TxpSlice(c("input2", "input3"), 
               list(log = function(x) log(x), sqrt = function(x) sqrt(x)))

## Create TxpSliceList
sl <- TxpSliceList(s1 = s1, s2 = s2)

## Accessors
txpValueNames(sl)
txpValueNames(sl, simplify = TRUE)

txpTransFuncs(sl)
txpTransFuncs(sl, simplify = TRUE)

## Coercion
as(list(s1 = TxpSlice("hello"), s2 = TxpSlice("user")), "TxpSliceList")
as.TxpSliceList(c(s1 = TxpSlice("hello"), s2 = TxpSlice("user")))

## Concatenation
c(sl, TxpSliceList(s3 = TxpSlice("input4")))

## Reduce TxpSliceList to single slice
Reduce(merge, sl)

Numeric transformation function

Description

S4 class to store numeric transformation functions

Usage

TxpTransFunc(x)

Arguments

x

function, see details

Details

TxpTransFunc inherits from a standard R function, but specifies a single input and a numeric output of the same length.

Functions can be passed directly to TxpTransFuncList list and the functions will be coerced to TxpTransFunc.

We have an imperfect system for dealing with primitive functions (e.g., base::sqrt). To coerce primitives to TxpTransFunc's, we wrap them in another function cal; wrapping the primitives obscures the original function and requires the user to explore the function environment to understand the primitive called. We recommend wrapping primitives in separate functions to make the intent clear, .e.g., mysqrt <- function(x) sqrt(x).

Examples

f1 <- function(x) "hello"
f2 <- function(x) 3
f3 <- function(x) x + 5
## Not run: 
t1 <- TxpTransFunc(x = f1) ## Produces error
t2 <- TxpTransFunc(x = f2) ## Produces error

## End(Not run)
t3 <- TxpTransFunc(x = f3)

## TxpTransFunc objects act as any other function
body(t3)
formals(t3)
t3(1:10)

## Coercion from functions
## Not run: 
TxpTransFuncList(f1, f2, f3) ## Produces error because f1, f3 not valid

## End(Not run)

List of TxpTransFunc objects

Description

Extension of S4Vectors::SimpleList that holds only NULL or TxpTransFunc objects.

Usage

TxpTransFuncList(...)

as.TxpTransFuncList(x)

Arguments

...

TxpTransFunc object or function to create TxpTransFuncList object

x

list, function, or TxpTransFunc object to coerce to TxpTransFuncList

Details

When ... includes function objects, TxpTransFuncList will attempt to coerce them to TxpTransFunc and return an error if any of the elements cannot be coerced to TxpTransFunc.

Examples

## Create TxpTransFunc objects
tf1 <- TxpTransFunc(function(x) x)
tf2 <- TxpTransFunc(function(x) sqrt(x))

## Create TxpTransFuncList 
tfl <- TxpTransFuncList(linear = tf1, sqrt = tf2, cube = function(x) x^3)
tfl[[3]](3) == 27
tfl[["sqrt"]](4) == 2

## Concatenate
c(tfl, tfl)

## names
names(c(tfl, tfl))

# note: names are printed as '' when missing; NULL is printed when list item
# is NULL
names(TxpTransFuncList(function(x) x, NULL))
TxpTransFuncList(function(x) x, NULL)

## coercion
as(function(x) x, "TxpTransFuncList")
as.TxpTransFuncList(function(x) x)

as(TxpTransFunc(function(x) x), "TxpTransFuncList")
as.TxpTransFuncList(TxpTransFunc(function(x) x))

as(list(function(x) x, sqrt = function(x) sqrt(x)), "TxpTransFuncList")
as.TxpTransFuncList(list(function(x) x, sqrt = function(x) sqrt(x)))

Create a filled-box legend

Description

Create a filled-box legend

Usage

boxLegendGrob(labels, fills, name = NULL, vp = NULL, gp = NULL)

Arguments

labels

Character, the legend labels

fills

Colors to fill the slices

name, vp, gp

Passed to grid::frameGrob

Details

Not yet exported. Need to break out the creation of viewports and grobs as done in the exported grobs. This will allow better grobEdit methods, which also needs to be created for the boxLegendGrob. Also need to do some input checks.

Also, if grid::legendGrob gets updated to use the 'has.fill' option this function should be removed and grid::legendGrob can be used instead.

Make grid of pieGrobs

Description

Make grid of pieGrobs

Usage

pieGridGrob(
  radMat,
  wts = NULL,
  fills = NULL,
  labels = NULL,
  showRadSum = FALSE,
  ncol = NULL,
  nrow = NULL,
  byrow = TRUE,
  name = NULL,
  gp = NULL,
  vp = NULL
)

grid.pieGridGrob(
  radMat,
  wts = NULL,
  fills = NULL,
  labels = NULL,
  showRadSum = FALSE,
  ncol = NULL,
  nrow = NULL,
  byrow = TRUE,
  name = NULL,
  gp = NULL,
  vp = NULL
)

Arguments

radMat

⁠matrix(<numeric>)⁠, observations by slice radii

wts

⁠vector(<numeric>)⁠, relative weights of each slice

fills

Vector of colors to fill slices

labels

⁠vector(<character>)⁠, (optional) label for each observation

showRadSum

Logical scalar, when TRUE show the weighted sum of slices below the label

nrow, ncol

Integer scalar, number of rows and columns for the grid

byrow

Logical scalar, fill the grid by rows when TRUE

name, gp, vp

Passed to grid::gTree

Value

pieGrob grid::grob object

Examples


library(grid)

s <- seq(0.2, 1, by = 0.1)
smat <- do.call("rbind", replicate(20, s, simplify = FALSE))
grid.newpage()
grid.pieGridGrob(radMat = smat)

rownames(smat) <- sprintf("obs%02d", 1:20)
grid.newpage()
grid.pieGridGrob(radMat = smat, wts = s)
grid.newpage()
grid.pieGridGrob(radMat = smat, wts = s, showRadSum = TRUE, labels = FALSE)
grid.newpage()
grid.pieGridGrob(radMat = smat, labels = "hello")
grid.newpage()
grid.pieGridGrob(radMat = smat, labels = 1:20)

## Can edit like normal grid objects
grid.newpage()
grid.pieGridGrob(radMat = smat, wts = s, showRadSum = TRUE)
grid.ls() ## shows grid elements
grid.edit("pie-20", fills = 1:9)
grid.edit("pie-19-label", gp = gpar(font = 2, col = "red"))
grid.edit("pie-1", wts = rep(1, 9), rads = rep(1, 9))
for (s in sprintf("pie-%d-radSum", 2:4)) {
  grid.edit(s, gp = gpar(font = 2, col = "blue"))
}

Create a pie grob

Description

Create a pie grob

Usage

pieGrob(rads, fills = NULL, wts = NULL, name = NULL, vp = NULL, gp = NULL)

grid.pieGrob(rads, fills = NULL, wts = NULL, name = NULL, vp = NULL, gp = NULL)

Arguments

rads

Numeric, radius values for each slice from 0 to 1

fills

Colors to fill the slices

wts

Numeric, the relative portion of each slice

name, vp, gp

Passed to grid::gTree

Details

The default coloring can be set with options("txp.fills").

Value

pieGrob grid::grob object

Examples

library(grid)

s <- seq(0.2, 1, by = 0.1)
grid.newpage()
grid.pieGrob(rads = s)
grid.newpage()
grid.pieGrob(rads = s, wts = s)

curr_txp_fills <- options()$txp.fills
options(txp.fills = 1:8)
grid.newpage()
grid.pieGrob(rads = s)
options(txp.fills = curr_txp_fills)

## Can edit
grid.newpage()
grid.pieGrob(rads = s, name = "myPie")
grid.ls() ## show the grid elements
grid.edit("myPie", fills = 1:9, wts = 9:1)

toxpiR data objects

Description

Objects included in the toxpiR package, loaded with utils::data

Usage

data(txp_example_input, package = "toxpiR")

data(txp_example_model, package = "toxpiR")

txp_example_input

Small example input data to be used with txpCalculateScores in creating TxpResult objects. A base::data.frame with 10 rows and 9 variables

name: Observation names
metric#: Input data for ToxPi models

txp_example_model

Example TxpModel object intended for txp_example_data; model with 4 slices.

Source

https://github.com/ToxPi/ToxPi-example-files

Examples

data(txp_example_input, package = "toxpiR")
data(txp_example_model, package = "toxpiR")
txp_example_input
txp_example_model

## Code to create txp_example_model
tf1 <- TxpTransFuncList(linear = function(x) x)
sl <- TxpSliceList(s1 = TxpSlice(sprintf("metric%d", 1:2)),
                   s2 = TxpSlice("metric3"),
                   s3 = TxpSlice(sprintf("metric%d", 4:7),
                                 tf1[rep("linear", 4)]),
                   s4 = TxpSlice("metric8", tf1))
tf2 <- TxpTransFuncList(NULL, linear = function(x) x, NULL, NULL)
TxpModel(txpSlices = sl, txpWeights = c(2, 1, 3, 2), txpTransFuncs = tf2)

Calculate ToxPi Scores for the given model and input data

Description

Calculate ToxPi Scores for the given model and input data

Usage

txpCalculateScores(model, input, ...)

## S4 method for signature 'TxpModel,data.frame'
txpCalculateScores(
  model,
  input,
  id.var = NULL,
  rank.ties.method = c("average", "first", "last", "random", "max", "min"),
  negative.value.handling = c("keep", "missing")
)

## S4 method for signature 'TxpModelList,data.frame'
txpCalculateScores(
  model,
  input,
  id.var = NULL,
  rank.ties.method = c("average", "first", "last", "random", "max", "min"),
  negative.value.handling = c("keep", "missing")
)

## S4 method for signature 'list,data.frame'
txpCalculateScores(
  model,
  input,
  id.var = NULL,
  rank.ties.method = c("average", "first", "last", "random", "max", "min"),
  negative.value.handling = c("keep", "missing")
)

Arguments

model

TxpModel object or TxpModelList object

input

data.frame object containing the model input data

...

Included for extendability; not currently used

id.var

Character scalar, column in 'input' to store in

rank.ties.method

Passed to rank.ties.method slot

negative.value.handling

Passed to negative.value.handling slot

Details

txpCalculateScores is implemented as an S4 generic function with methods for TxpModel and TxpModelList.

Ranks are calculated such that the highest ToxPi score has a rank of 1.

Missingness is determined after applying input-level transformations but before applying slice-level transformations.

Value

TxpResult or TxpResultList object

Examples

## Load example dataset & model; see ?TxpModel for building model objects
data(txp_example_input, package = "toxpiR")
data(txp_example_model, package = "toxpiR")

## Calculate scores for single model; returns TxpResult object
res <- txpCalculateScores(model = txp_example_model, 
                          input = txp_example_input, 
                          id.var = "name")

## Calculate scores for list of models; returns TxpResultList object
txpCalculateScores(model = TxpModelList(m1 = txp_example_model, 
                                        m2 = txp_example_model), 
                   input = txp_example_input, 
                   id.var = "name")
resLst <- txpCalculateScores(model = list(m1 = txp_example_model, 
                                          m2 = txp_example_model), 
                             input = txp_example_input, 
                             id.var = "name")

Export comma-separated file intended for ToxPi GUI

Description

Export comma-separated file intended for ToxPi GUI

Usage

txpExportGui(
  fileName = "txpModel.csv",
  input,
  model,
  id.var = NULL,
  fills = NULL
)

Arguments

fileName

Character scalar, the path to the output file

input

data.frame object containing the model input data

model

TxpModel object or TxpModelList object

id.var

Character scalar, column in 'input' to store in

fills

Colors to fill the slices

Details

The GUI differs in two meaninful ways for exporting toxpiR models: (1) the GUI only allows for integer weights; (2) the GUI applies transformation functions differently.

txpExporGui will not work for models with non-integer weights.

The GUI only applies a single transformation function to every input within a slice, and only functions from a pre-determined list; toxpiR allows users to apply any valid function individually to each input, then a second transformation function on the summed slice values. Because of this complexity, any exported models with slice-level transformation functions will not export at the input level. In other words, the export will have only the final slice scores. Otherwise, all input-level transformations will be performed, the and the export will contain transformed input-level data with the linear(x) GUI transformation.

toxpiR package generics

Description

toxpiR package generics; see class man pages for associated methods

Usage

txpValueNames(x, ...)

txpValueNames(x, ...) <- value

txpTransFuncs(x, ...)

txpTransFuncs(x, ...) <- value

txpSlices(x, ...)

txpSlices(x, ...) <- value

txpWeights(x, ...)

txpWeights(x, ...) <- value

txpScores(x, ...)

txpSliceScores(x, ...)

txpModel(x, ...)

txpIDs(x, ...)

txpIDs(x, ...) <- value

txpRanks(x, ...)

txpMissing(x, ...)

txpResultParam(x, ...)

Arguments

x

toxpiR S4 object

...

Included for extendability; not currently used

value

Replacement value

Value

See specific methods for details.

Import data file generated by ToxPi GUI

Description

Import data file generated by ToxPi GUI

Usage

txpImportGui(guiDataFile)

Arguments

guiDataFile

Character scalar, the path to a 'data' export from the ToxPi GUI

Details

This function takes the '_data.csv' files generated by the GUI. See https://toxpi.org for more information.

Because of the way toxpiR implements transformation functions, there is not a way currently to use the GUI 'hitcount' function.

Value

list with ⁠$model⁠ containing TxpModel object; ⁠$input⁠ containing data.frame with input data; ⁠$fills⁠ containing a vector of fill colors.

toxpiR: Create ToxPi Prioritization Models

Description

Author(s)

See Also

ToxPi Model

Description

Usage

Arguments

Functions

Slots

Examples

List of TxpModel objects

Description

Usage

Arguments

Functions

Examples

ToxPi Result

Description

Usage

Arguments

Functions

Slots

See Also

Examples

Plot TxpResult objects

Description

Usage

Arguments

Details

Value

Functions

Examples

List of TxpResult objects

Description

Usage

Arguments

See Also

Examples

ToxPi Result Parameters

Description

Arguments

Details

Slots

See Also

ToxPi Slice

Description

Usage

Arguments

Details

Functions

Slots

Examples

List of TxpSlice objects

Description

Usage

Arguments

Details

Functions

Examples

Numeric transformation function

Description

Usage

Arguments

Details

Examples

List of TxpTransFunc objects

Description

Usage

Arguments

Details

Examples

Create a filled-box legend

Description

Usage

Arguments

Details

Make grid of pieGrobs

Description

Usage