/ 
Statistics-SDT-0.02
River stage zero No dependents
/ Statistics::SDT

NAME

Statistics::SDT - Signal detection theory measures of sensitivity and response-bias

VERSION

This is documentation for Version 0.02 of Statistics-SDT (2006-11-20).

SYNOPSIS

use Statistics::SDT;

$sdt = Statistics::SDT->new(
    { 
        hits => 50,
        signal_trials => 50,
        false_alarms => 17,
        noise_trials => 25,
        correct => 2,
    }
);

$d = $sdt->d_sensitivity();
$c = $sdt->decision_bias();

DESCRIPTION

Signal Detection Theory algorithms (e.g., of d', A', decision bias), as prescribed by Stanislav & Todorov (1999). Both object- and function-oriented interfaces are provided.

KEY VALUES

For both object- and function-oriented styles, the following named parameters must be given as a hash-reference: either to the new constructor method, or (with the function-oriented style) into each function. Basically, either all of the first four parameters are required (in order to calculate the hit-rate and false-alarm-rate), or the required rates are themselves supplied.

hits

The number of hits.

false_alarms

The number of false alarms.

signal_trials

The number of signal trials. The hit-rate is derived by dividing the number of hits by the number of signal trials.

noise_trials

The number of noise trials. The false-alarm-rate is derived by dividing the number of false-alarms by the number of noise trials.

alternatives

The number of response alternatives. Default = 2 (for the classic signal-detection situation of discriminating between signal+noise and noise-only). If the number of alternatives is greater than 2, the measure of sensitivity, when calling d_sensitivity, is based on the Smith (1982) algorithms.

correct

A parameter that indicates whether or not to perform a correction on the number of hits and false-alarms as a corrective when the hit-rate or false-alarm-rate equals 0 or 1 (due, e.g., to strong inducements against false-alarms, or easy discrimination between signals and noise). This is relevant to all functions that make use of the inverse phi function (all except a_sensitivity and griers_bias).

If set to greater than 1, the loglinear transformation is applied, i.e., 0.5 is added to both the number of hits and false-alarms, and 1 is added to the number of signal and noise trials. These adjustments are made irrespective of the extremity of the rates themselves.

If set to 1, extreme rates (of 0 and 1, only) are replaced with the number of signal/noise trials, moderated by a value of 0.5 (specifically, where n = number of signal or noise trials: 0 is replaced with 0.5 / n; 1 is replaced with (n - 0.5) / n.

Stanislav and Todorov (1999) advise that the latter correction is the most common method of handling extreme rates, but that it might bias sensitivity measures and not be as satisfactory as the loglinear transformation applied to all hits and false-alarms.

If set to zero (the default), no correction is performed to the calculation of the rates. This should only be used when you are using (1) the parametric measures and are sure the rates are not at the extremes of 0 and 1; or (2) the nonparametric algorithms (a_sensitivity and griers_bias). An alternative to these corrections is, indeed, to use the nonparametric measures.

hr

This is the hit-rate. Instead of passing the number of hits and signal trials, give the hit-rate directly - but, if doing so, ensure the rate does not equal zero or 1 in order to avoid errors thrown by the inverse-phi function (which will be given as "ndtri domain error").

far

This is the false-alarm-rate. Instead of passing the number of false alarms and noise trials, give the false-alarm-rate directly - but, if doing so, ensure the rate does not equal zero or 1 in order to avoid errors thrown by the inverse-phi function (which will be given as "ndtri domain error").

METHODS

The methods can be accessed by an object- or function-oriented style:

Object-oriented style: firstly construct a class object by supplying KEY VALUES to the new method, and then call each method by supplying the class object as the first argument.

$sdt = Statistics::SDT->new({hr => => 10/12, far => 1/12});
$bias = $sdt->likelihood_bias();

Function-oriented style: firstly explicitly import the functions to be used, and then simply call the function, with KEY VALUES.

use Statistics::SDT qw(likelihood_bias);
$bias = likelihood_bias({hr => => 10/12, far => 1/12});

Class constructor

new

This method may be used to construct a class object that holds the values of the parameters, as above, and to call the following methods, without having to resubmit all the values.

As well as holding the values of the parameters submitted to it, the class-object returned by new will hold two arguments, hr, the hit-rate, and far, the false-alarm-rate.

This method can be skipped, and the following methods used directly (all optionally exported), as long as the parameters, as above, are passed to each one.

You can supply the hit-rate and false-alarm-rate themselves, but ensure that they do not equal zero or 1 in order to avoid errors thrown by the inverse-phi function. The calculation of the hit-rate and false-alarm-rate by the module corrects for this limitation - see the notes on the correct parameter, above.

Sensitivity measures

d_sensitivity

Returns the index of sensitivity, or discrimination, d' (d prime). (dprime is an alias for this function.)

  • d' = phi^-1(hr) - phi^-1(far)

d' is found by subtracting the z-score that corresponds to the false-alarm rate (far) from the z-score that corresponds to the hit rate (hr). Sensitivity is measured in standard deviation units, larger positive values indicating greater sensitivity.

If both the hit-rate and false-alarm-rate are either 0 or 1, then d_sensitivity returns 0.

If there are more than two alternatives (as specified by the parameter named alternatives in the hash-reference passed to the new constructor or this method, then Smith's (1982) algorithms are used.

A value of 0 indicates no sensitivity to the presence of the signal, i.e., it cannot be discriminated from noise.

Values less than 0 indicate a lack of sensitivity that might result from response-confusion.

a_sensitivity

Returns the nonparametric index of sensitivity, A'. (aprime is an alias for this function.)

Ranges from 0 to 1. Values greater than 0.5 indicate positive discrimination (1 = perfect performance); values less than 0.5 indicate a failure of discrimination (perhaps due to response-confusion); and a value of 0.5 indicates no sensitivity to the presence of the signal, i.e., it cannot be discriminated from noise.

area_d_sensitivity

The area under the receiver-operating-characteristic (ROC) curve, simply equalling the proportion of correct responses that would have been yielded had the task been a two-alternative forced-choice task rather than a yes/no task. (area_dprime is an alias for this function.)

If both the hit-rate and false-alarm-rate are either 0 or 1, then area_d_sensitivity returns 0.5.

Bias measures

likelihood_bias

Returns the beta measure of response bias, based on the ratio of the likelihood the decision variable obtains a certain value on signal trials, to the likelihood that it obtains the value on noise trials.

Values less than 1 indicate a bias toward the yes response, values greater than 1 indicate a bias toward the no response, and the value of 1 indicates no bias toward yes or no.

log_likelihood_bias

Returns the natural logarithm of the likelihood bias, beta.

Ranges from -1 to +1, with values less than 0 indicating a bias toward the yes response, values greater than 0 indicating a bias toward the no response, and a value of 0 indicating no response bias.

decision_bias

Implements the c parametric measure of response bias. Ranges from -1 to +1, with deviations from zero, measured in standard deviation units, indicating the position of the decision criterion with respect to the neutral point where the signal and noise distributions cross over, there is no response bias, and c = 0.

Values less than 0 indicate a bias toward the yes response (the decision variable exceeds the criterion); values greater than 0 indicate a bias toward the no response (the decision variable is less than the criterion); and a value of 0 indicates no response bias.

griers_bias

Implements Griers B'' nonparametric measure of response bias.

Ranges from -1 to +1, with values less than 0 indicating a bias toward the yes response, values greater than 0 indicating a bias toward the no response, and a value of 0 indicating no response bias.

EXAMPLES

Object-oriented style

use strict;

use Statistics::SDT;

# 1. Create SDT object, loading it with the key values:
my $sdt = Statistics::SDT->new(
 { 
    hits           => 50,
    signal_trials  => 50,
    false_alarms   => 17,
    noise_trials   => 25,
    correct        => 2,
  }
);

# you could also give the hit and false-alarm rates directly:
# my $sdt = Statistics::SDT->new({hr => 50/50, far => 17/25});
# but this will throw an error when calling a parametric measure, 
# as 1 is being given as the hit-rate.

# 2. Use the SDT object to access methods (and the rates), e.g.: 
print 'd = ' . $sdt->d_sensitivity() . "\n"; # d = 1.85864907492633
print 'c = ' . $sdt->decision_bias() . "\n"; # c = -1.39702333657767
print 'hr = ' . $sdt->{'hr'} . "\n"; # hr = 0.99

Function-oriented style

# 1. Explicitly import the required methods:
use Statistics::SDT qw(d_sensitivity decision_bias);

# 2. Access the methods, supplying the key values to each, e.g.:
my $d = d_sensitivity(
  { 
      hits => 10,
      signal_trials => 12,
      false_alarms => 0,
      noise_trials => 12,
      correct => 1,
   }
);

# you could also give the hit and false-alarm rates directly:
# my $d = d_sensitivity({hr => 10/12, far => 0/12});
# but this will throw an error, as zero is being given as the false-alarm-rate,
# and a parametric measure of sensitivity is being called.

my $bias = decision_bias(
   { 
      hits => 10,
      signal_trials => 12,
      false_alarms => 0,
      noise_trials => 12,
      correct => 1,
   }
);

print "d = $d\nbias = $bias\n";
# d = 2.69908596222395
# bias = 0.382121415010272

REFERENCES

Smith, J. E. K. (1982). Simple algorithms for M-alternative forced-choice calculations. Perception and Psychophysics, 31, 95-96.

Stanislaw, H., & Todorov, N. (1999). Calculation of signal detection theory measures. Behavior Research Methods, Instruments, and Computers, 31, 137-149.

SEE ALSO

Math::Cephes : The present module imports the ndtri or inverse phi function from this package, which is used to calculate z-scores from probabilities.

Statistics::ROC : Receiver operating characteristic curves.

AUTHOR/LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Copyright (C) 2006 Roderick Garton

DISCLAIMER

To the maximum extent permitted by applicable law, the author of this module disclaims all warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with regard to the software and the accompanying documentation.