dod_utils {sensR}

Utility functions for the Degree-of-Difference model

Description

Various utility functions supporting the Degree-of-Difference (DOD) model.

Usage

optimal_tau(d.prime, d.prime0 = 0, ncat=3,
            method=c("equi.prob", "LR.max", "se.min"),
            tau.start=NULL, equi.tol = 1e-4, grad.tol = 1e-2,
            do.warn=TRUE)

par2prob_dod(tau, d.prime)

dod_nll(tau, d.prime, same, diff, integer.tol=1e-8)

dod_null(same, diff, integer.tol=1e-8)

dod_null_tau(same, diff)

Arguments

d.prime

the value of d-prime; non-negative numerical scalar.

d.prime0

d-prime under the null hypothesis; only used in optimal_tau when method = "LR.max".

ncat

the number of response categories in the DOD model.

method

the method with which to choose the boundary parameters — see dodSim for details on the methods.

tau.start

optional vector of starting values.

equi.tol

convergence tolerence for the "equi.prob" method.

grad.tol

gradient convergence tolerence.

do.warn

issue warning if estimation of optimal tau does not converge?

same

The answers to same-pairs; either 1) a numeric vector of counts of length equal to the number of response categories ordered appropriately or 2) a factor where the levels indicate the response categories.

diff

the answers to different-pairs in the same format as same.

tau

vector of boundary parameters in the DOD model.

integer.tol

tolerence for when same or diff arguments are considered non-integer counts: a warning is issued if non-integer counts are encountered.

Value

optimal_tau

computes optimal boundary parameters (tau) using various criteria.

par2prob_dod

computes the multinomial probability vectors from DOD model parameters.

dod_nll

implements the negative log-likelihood function for the DOD model.

dod_null

implements the negative log-likelihood function for the DOD model where d-prime = 0.

dod_null_tau

Estimates tau for the DOD model where d-prime = 0.

Author(s)

Rune Haubo B Christensen

See Also

dod, dod_fit, dodSim, dodPwr, dodControl

Examples

## Compute optimal boundary parameters using the LR.max criterion for
## d.prime=1 with 4 categories:
dp <- 1
(Tau <- optimal_tau(d.prime=dp, d.prime0 = 0, ncat=4,
                    method="LR.max")$tau)
##  [1] 1.244642 2.109140 3.098985
## This set of boundary parameters optimize the power of the DOD test
## with d.prime = 1 under the alternative hypothesis.

## Compute the probability that an observation will fall in each of
## the (here 2*4=8) response categories given values of tau and d.prime:
par2prob_dod(tau=Tau, d.prime=dp)
##              [,1]      [,2]      [,3]       [,4]
##  p.same 0.6211921 0.2429480 0.1074307 0.02842911
##  p.diff 0.5124361 0.2571691 0.1596425 0.07075227

## Compute the negative log-likelihood given data and parameters:
Same <- c(10, 20, 30, 20)
Diff <- c(10, 10, 20, 40)
dod_nll(tau=Tau, d.prime=dp, same=Same,
        diff=Diff)
##  [1] 334.0986

## Compute the negative log-likelihood under the null hypothesis
## (where d.prime = 0):
dod_null(same=Same, diff=Diff)
##  [1] 208.8154
##  ## The boundary parameters for this:
(Tau0 <- dod_null_tau(same=Same, diff=Diff))
##  [1] 0.2224709 0.5688675 1.2546147

## Some equalities:
stopifnot(
    dod_nll(tau=Tau0, d.prime=0, same=Same, diff=Diff) ==
    dod_null(same=Same, diff=Diff))
stopifnot(
    dod_null(same=Same, diff=Diff) ==
    -dod_fit(same=Same, diff=Diff, d.prime=0)$logLik
    )
stopifnot(
    dod_nll(same=Same, diff=Diff, tau=Tau, d.prime=dp) ==
    -dod_fit(same=Same, diff=Diff, tau=Tau, d.prime=dp)$logLik
    )
stopifnot(all(
    dod_null_tau(same=Same, diff=Diff) ==
    dod_fit(Same, Diff, d.prime=0)$tau))