dod_utils: Utility functions for the Degree-of-Difference model

In sensR: Thurstonian Models for Sensory Discrimination

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))

sensR documentation built on Nov. 2, 2023, 6:02 p.m.