opiPresent: Use OPI to present stimulus.

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/opi.r

Description

Generic function for presentation of stimulus stim. Depending on your choice of OPI implementation set using chooseOpi(), different parameters are available for opiPresent.

Usage

1
opiPresent(stim, nextStim=NULL, ...)

Arguments

stim

A list of class opiStaticStimulus, opiKineticStimulus, or opiTemporalStimulus.

nextStim

As for stim, but the next presentation to be made. This might be useful on some machines, particularly projector based systems, where preparations for the next presentation can be made while waiting for a response to the current.

...

Parameters specific to your chosen opi implementation.

Details

opiPresent is blocking in that it will not return until either a response is obtained, or at least the responseWindow milliseconds has expired. (Note that more time might have expired.) Specifying nextStim allows the implementing machine to use the time waiting for a response to stim to make preparations for the next stimuli. (For example retargeting the projector or moving aperture and/or filter wheels.) There is no guarantee that the next call to opiPresent will have nextStim as the first argument; this could be checked by the machine specific implementations (but currently is not, I think).

Also note that to allow for different parameters depending on the implementation chosen with chooseOpi, every parameter MUST be named in a call to opiPresent.

SimHenson

opiPresent(stim, nextStim=NULL, fpr=0.03, fnr=0.01, tt=30)

If the chosen OPI implementation is SimHenson, then the response to a stimuli is determined by sampling from a Frequency-of-Seeing (FoS) curve (also known as the psychometric function) with formula

\code{fpr+(1-fpr-fnr)*(1-pnorm(x, tt, pxVar))},

where \code{x} is the stimulus value in Humphrey dB, and pxVar is

\code{min(simH.cap, exp(A*tt + B))}.

The ceiling simH.global.cap is set with the call to opiInitialize, and A and B are from Table 1 in Henson et al (2000). Which values are used is determined by simH.type which is also set in the call to opiInitialize.

Note that if the stimulus value is less than zero, then the Henson formula is not used. The probability of seeing is fpr.

opiPresent(stim, nextStim=NULL, fpr=0.03, fnr=0.01, tt=NULL, criteria=0.95, rt_shape=5.3, rt_rate=1.4, rt_scale=0.1)

For determinng seen/not-seen for kinetic, the first location (to a fidelity of 0.01 degrees) on the path (it only works for single paths now) where the probability of seeing is equal to criteria is found. If no such location exists, then the stimuli is not seen. The probability of seeing at each location is determined using a frequency-of-seeing curve defined as a cumulative Gaussian with parameters controlled by tt and opiInitialize. At each location along the path, the mean of the FoS is taken from the tt function, which takes a distance-along-path (in degrees) as an argument, and returns a dB value which is the static threshold at that distance along the path. Function tt can return NA for not thresholds that are always not seen. At each location along the path, the standard deviation of the FoS is sampled from a Gaussion with mean taken from the formula of Henson et al (2000), as parametrised by opiInitialize, and standard deviation 0.25.

The location of a false positive response (for the total kinetic path) is sampled uniformly from the start of the path to the 'seeing' location, or the entire path if the stimuli is not seen.

Note that the false positive rate fpr and the false negative rate fnr are specified for the whole path, and not for the individual static responses along the way.

The actual location returned for a seen response is the location where the probability of seeing equals criteria, plus a response time sampled from a Gamma distribution parameterised by rt_shape and rt_rate and multiplied by rt_scale. That is: rgamma(1, shape=rt_shape, rate=rt_rate) / rt_scale.

SimHensonRT

opiPresent(stim, nextStim=NULL, fpr=0.03, fnr=0.01, tt=30, dist=stim$level - tt)

For static stimuli, this function is the same as for SimHenson, but reaction times are determined by sampling from rtData as passed to opiInitialize. The dist parameter is the distance of the stimulus level from the true threshold, and should be in the same units as the Dist column of rtData. The default is just the straight difference between the stimulus level and the true threshold, but you might want it scaled somehow to match rtData.

SimGaussian

opiPresent(stim, nextStim=NULL, fpr=0.03, fnr=0.01, tt=30)

If the chosen OPI implementation is SimGaussian, then the response to a stimuli is determined by sampling from a Frequency-of-Seeing (FoS) curve (also known as the psychometric function) with formula fpr+(1-fpr-fnr)*(1-pnorm(x, tt, simG.global.sd)), where x is the stimulus value in Humphrey dB, and simG.global.sd is set with opiInitialize.

SimYes

opiPresent(stim, nextStim=NULL)

If the chosen OPI implementation is SimYes, then the response to a stimuli is always yes, hence opiPresent always returns err=NULL, seen=TRUE, and time=0.

SimNo

opiPresent(stim, nextStim=NULL)

If the chosen OPI implementation is SimNo, then the response to a stimuli is always no, hence opiPresent always returns err=NULL, seen=FALSE, and time=0.

Octopus900F310

opiPresent(stim, nextStim=NULL)

This functions as for the Octopus900, but responses are taken from the F310 Controller. If the L button is pressed, seen is set to 1. If the R button is pressed, seen is set to 2. If no button is pressed within responseWindow, then seen is set to 0.

Octopus600

opiPresent(stim, nextStim=NULL)

If the chosen OPI implementation is Octopus600, then nextStim is ignored. If eyeControl is non-zero, as set in opiInitialize, answer codes describing patient state may arise (see answer field in the Value section).

KowaAP7000

opiPresent(stim, nextStim=NULL)

If the chosen OPI implementation is KowaAP7000, then nextStim is ignored.

Compass

opiPresent(stim, nextStim=NULL)

If the chosen OPI implementation is Compass, then nextStim is ignored. Note that the dB level is rounded to the nearest integer.

Value

A list containing

err

NULL if no error occurred, otherwise a machine specific error message. This should include errors when the specified size cannot be achieved by the device (for example, in a projection system with an aperture wheel of predefined sizes.) If stim is NULL, then err contains the status of the machine.

seen

TRUE if a response was detected in the allowed responseWindow, FALSE otherwise. (Note, see Octopus900F310 above).

time

The time in milliseconds from the onset (or offset, machine specific) of the presentation until the response from the subject if seen is TRUE. If seen is FALSE, this value is undefined.

answer

Only returned for Octopus600. Can be the following values:

  • 0 = stimulus not seen;

  • 1 = stimulus seen;

  • 132 = Response button was pressed before stimulus presentation (Patient needs a break - hold on examination);

  • 36 = Eye is closed before stimulus presentation;

  • 68 = Fixation lost before stimulus presentation (pupil center is out of green window in video image);

  • 260 = Forehead rest lost before stimulus presentation;

  • 516 = Fast Eye movements before stimulus presentation;

  • 258 = Forehead rest lost during stimulus presentation;

  • 66 = Fixation lost during stimulus presentation (pupil center is out of green window in video image);

  • 34 = Eye was closed during stimulus presentation;

  • 18 = Patient answer was too early (<=100ms after stimulus presentation) - lucky punch;

  • 514 = Fast Eye movements during stimulus presentation

pupilX

Only returned for KowaAP7000 and an opiStaticStimulus or O900 and staic/kinetic if gazeFeed==1. x-coordinate of centre of pupil in pixels during presentation.

pupilY

Only returned for KowaAP7000 and an opiStaticStimulus or O900 and staic/kinetic if gazeFeed==1. y-coordinate of centre of pupil in pixels during presentation.

purkinjeX

Only returned for KowaAP7000 and an opiStaticStimulus. x-coordinate of centre of Purkinje Image in pixels during presentation.

purkinjeY

Only returned for KowaAP7000 and an opiStaticStimulus. y-coordinate of centre of Purkinje Image in pixels during presentation.

x

Only returned for KowaAP7000 or Octopus900 and an opiKineticStimulus. x coordinate of stimuli when button is pressed.

y

Only returned for KowaAP7000 or Octopus900 and an opiKineticStimulus. y coordinate of stimuli when button is pressed.

time_rec

Only returned for Compass. Time since epoch that the opiPresent command was received by the Compass in ms.

time_hw

Only returned for Compass. Hardware time of button press or response window expired (integer ms). To get the hardware time that a presentation began, subtract responseWindow from th (for aligning with fixation data returned by opiClose().

time_resp

Only returned for Compass. Time since epoch that the response was received or response window expired (in ms).

num_track_events

Only returned for Compass. The number of tracking events associated with this presentation.

num_motor_fails

Only returned for Compass. The number of time the motor could not keep pace with eye movements.

pupil_diam

Only returned for Compass. The diameter of the pupil on milimetres on presentation.

loc_x

Only returned for Compass. The x location in pixels of the presentation on the retinal image returned by opiInitialize.

loc_y

Only returned for Compass. The y location in pixels of the presentation on the retinal image returned by opiInitialize.

Author(s)

Andrew Tuprin <[email protected]>

References

Please cite: A. Turpin, P.H. Artes and A.M. McKendrick "The Open Perimetry Interface: An enabling tool for clinical visual psychophysics", Journal of Vision 12(11) 2012.

http://people.eng.unimelb.edu.au/aturpin/opi/index.html

David B. Henson, Shaila Chaudry, Paul H. Artes, E. Brian Faragher, and Alec Ansons. Response Variability in the Visual Field: Comparison of Optic Neuritis, Glaucoma, Ocular Hypertension, and Normal Eyes. Investigative Ophthalmology & Visual Science, February 2000, Vol. 41(2).

See Also

opiStaticStimulus, opiKineticStimulus, opiTemporalStimulus, chooseOpi opiInitialize

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
    # Stimulus is Size III white-on-white as in the HFA
makeStim <- function(db, n) { 
    s <- list(x=9, y=9, level=dbTocd(db, 10000/pi), size=0.43, color="white",
             duration=200, responseWindow=1500)
    class(s) <- "opiStaticStimulus"

    return(s)
}
chooseOpi("SimHenson")
if (!is.null(opiInitialize(type="C", cap=6)))
    stop("opiInitialize failed")

result <- opiPresent(stim=makeStim(10,0), tt=30, fpr=0.15, fnr=0.01)

    # Will not work as 'stim' is not named
#result <- opiPresent(makeStim(10,0), tt=30, fpr=0.15, fnr=0.01)

if (!is.null(opiClose()))
    warning("opiClose() failed")

    # Same but with simulated reaction times
chooseOpi("SimHensonRT")
data(RtSigmaUnits)
if (!is.null(opiInitialize(type="C", cap=6, rtData=RtSigmaUnits)))
    stop("opiInitialize failed")

dist <- (10 - 30)/min(exp(-0.098 * 30 + 3.62), 6)
result <- opiPresent(stim=makeStim(10,0), tt=30, fpr=0.15, fnr=0.01, dist=dist)

if (!is.null(opiClose()))
    warning("opiClose() failed")

OPI documentation built on Nov. 17, 2017, 6:15 a.m.