betafunctions (version 1.9.0)

HB.ROC: ROC curves for the Hanson and Brennan approach.

Description

Generate a ROC curve plotting the false-positive rate against the true-positive rate at different cut-off values across the observed-score scale.

Usage

HB.ROC(
  x = NULL,
  reliability,
  testlength,
  truecut,
  true.model = "4P",
  failsafe = TRUE,
  l = 0,
  u = 1,
  AUC = FALSE,
  maxJ = FALSE,
  maxAcc = FALSE,
  locate = NULL,
  raw.out = FALSE,
  grainsize = testlength
)

Value

A plot tracing the ROC curve for the test, or matrix of coordinates if raw.out is TRUE.

Arguments

x

A vector of observed results (sum scores) or a list of parameter values (see documentation for the HB.beta.tp.fit() function.

reliability

The reliability coefficient of the test.

testlength

The total number of test items (or maximum possible score). Must be an integer.

truecut

The point along the x-scale that marks true category membership.

true.model

The probability distribution to be fitted to the moments of the true-score distribution. Options are "4P" (default) and "2P", referring to four- and two-parameter Beta distributions. The "4P" method produces a four-parameter Beta distribution with the same first four moments (mean, variance, skewness, and kurtosis) as the estimated true-score distribution, while the "2P" method produces a two-parameter Beta distribution with the first two moments (mean and variance) as the estimated true-score distribution.

failsafe

If true-model == "4P": Whether to engage a fail-safe reverting to a two-parameter true-score distribution solution should the four-parameter fitting procedure produce impermissible results. Default is TRUE (engage fail-safe in the event of impermissible estimates).

l

If true.model == "2P" or failsafe == TRUE: The lower-bound location parameter of the two-parameter true-score distribution solution.

u

If true.model == "2P" or failsafe == TRUE: The upper-bound location parameter of the two-parameter true-score distribution solution.

AUC

Logical. Calculate and include the area under the curve? Default is FALSE.

maxJ

Logical. Mark the point along the curve where Youden's J statistic is maximized? Default is FALSE.

maxAcc

Logical. Mark the point along the curve where the Accuracy statistic is maximized? Default is FALSE.

locate

Ask the function to locate the cut-point at which sensitivity or NPV is greater than or equal to some value, or specificity or PPV is lesser than or equal to some value. Take as input a character-vector of length 2, with the first argument being which index is to be found (e.g., "sensitivity"), and the second argument the value to locate (e.g., "0.75"). For example: c("sensitivity", "0.75").

raw.out

Give raw coordinates as output rather than plot? Default is FALSE

grainsize

Specify the number of cutoff-points for which the ROC curve is to be calculated. The greater this number the greater the accuracy. Default is set to the stated test length (N).

Examples

# Generate some fictional data. Say, 1000 individuals take a test with a
# maximum score of 50.
# Generate some fictional data. Say, 1000 individuals take a 20-item test.
set.seed(1234)
p.success <- rBeta.4P(1000, 0.15, 0.85, 6, 4)
 for (i in 1:20) {
   if (i == 1) {
     rawdata <- matrix(nrow = 1000, ncol = 20)
     }
   rawdata[, i] <- rbinom(1000, 1, p.success)
 }

# Suppose the cutoff value for attaining a pass is 10 items correct, and
# that the reliability of this test was estimated using the Cronbach's Alpha
# estimator. To draw the ROC-graph and locate the points at which Youden's J
# and Accuracy are maximized:
HB.ROC(rowSums(rawdata), cba(rawdata), 20, 10, maxAcc = TRUE, maxJ = TRUE)

# For further examples regarding how to use the locate argument to locate
# points at which various criteria are satisfied, see documentation for the
# LL.ROC() function.