metadpy.mle.metad#

metadpy.mle.metad(data: None, nRatings: int, nR_S1: None, nR_S2: None, stimuli: Union[list, ndarray], accuracy: Union[list, ndarray], confidence: Union[list, ndarray], within=None, between=None, subject=None, padAmount: Optional[float] = None, s: int = 1, padding: bool = True, collapse: Optional[int] = None, fncdf: Callable[[...], float] = norm.cdf, fninv: Callable[[...], float] = norm.ppf, verbose: int = 1) → Union[dict, DataFrame][source]#
metadpy.mle.metad(data: None, nRatings: int, nR_S1: Union[list, ndarray], nR_S2: Union[list, ndarray], stimuli: None, accuracy: None, confidence: None, within=None, between=None, subject=None, padAmount: Optional[float] = None, s: int = 1, padding: bool = True, collapse: Optional[int] = None, fncdf: Callable[[...], float] = norm.cdf, fninv: Callable[[...], float] = norm.ppf, verbose: int = 1) → DataFrame
metadpy.mle.metad(data: DataFrame, nRatings: int, nR_S1: None, nR_S2: None, stimuli: str = 'Stimuli', accuracy: str = 'Accuracy', confidence: str = 'Confidence', within: Optional[str] = None, between: Optional[str] = None, subject: Optional[str] = None, padAmount: Optional[float] = None, s: int = 1, padding: bool = True, collapse: Optional[int] = None, fncdf: Callable[[...], float] = norm.cdf, fninv: Callable[[...], float] = norm.ppf, verbose: int = 1) → DataFrame

Estimate meta-d’ using maximum likelihood estimation (MLE).

This function is adapted from the transcription of fit_meta_d_MLE.m (Maniscalco & Lau, 2012) by Alan Lee: http://www.columbia.edu/~bsm2105/type2sdt/.

Parameters
data

Dataframe. Note that this function can also directly be used as a Pandas method, in which case this argument is no longer needed.

nRatings

Number of discrete ratings. If a continuous rating scale was used, and the number of unique ratings does not match nRatings, will convert to discrete ratings using metadpy.utils.discreteRatings(). Default is set to 4.

stimuli

Name of the column containing the stimuli.

accuracy

Name of the columns containing the accuracy.

confidence

Name of the column containing the confidence ratings.

within

Name of column containing the within factor (condition comparison).

between

Name of column containing the between subject factor (group comparison).

subject

Name of column containing the subject identifier (only required if a within-subject or a between-subject factor is provided).

nR_S1, nR_S2

These are vectors containing the total number of responses in each response category, conditional on presentation of S1 and S2. If nR_S1 = [100, 50, 20, 10, 5, 1], then when stimulus S1 was presented, the subject had the following response counts: * responded ‘S1’, rating=`3` : 100 times * responded ‘S1’, rating=`2` : 50 times * responded ‘S1’, rating=`1` : 20 times * responded ‘S2’, rating=`1` : 10 times * responded ‘S2’, rating=`2` : 5 times * responded ‘S2’, rating=`3` : 1 time

The ordering of response / rating counts for S2 should be the same as it is for S1. e.g. if nR_S2 = [3, 7, 8, 12, 27, 89], then when stimulus S2 was presented, the subject had the following response counts: * responded ‘S1’, rating=`3` : 3 times * responded ‘S1’, rating=`2` : 7 times * responded ‘S1’, rating=`1` : 8 times * responded ‘S2’, rating=`1` : 12 times * responded ‘S2’, rating=`2` : 27 times * responded ‘S2’, rating=`3` : 89 times

s

Ratio of standard deviations for type 1 distributions as: s = np.std(S1) / np.std(S2). If not specified, s is set to a default value of 1. For most purposes, it is recommended to set s=1. See http://www.columbia.edu/~bsm2105/type2sdt for further discussion.

padding

If True, a small value will be added to the counts to avoid problems during fit.

padAmount

The value to add to each response count if padding is set to 1. Default value is 1/(2*nRatings)

collapse

If an integer N is provided, will collpase ratings to avoid zeros by summing every N consecutive ratings. Default set to None.

fncdf

A function handle for the CDF of the type 1 distribution. If not specified, fncdf defaults to scipy.stats.norm.cdf().

fninv

A function handle for the inverse CDF of the type 1 distribution. If not specified, fninv defaults to scipy.stats.norm.ppf().

verbose

Level of algorithm’s verbosity (can be 0, 1, 2 or 3): * 0 (default) : work silently. * 1 : display a termination report. * 2 : display progress during iterations. * 3 : display progress during iterations (more complete report).

Returns
results

In the following, S1 and S2 represent the distributions of evidence generated by stimulus classes S1 and S2: * ‘dprime’ : mean(S2) - mean(S1), in

root-mean-square(sd(S1), sd(S2)) units

  • ‘s’ : sd(S1) / sd(S2)

  • ‘meta_da’ : meta-d’ in RMS units

  • ‘M_diff’ : meta_da - da

  • ‘M_ratio’ : meta_da / da

  • ‘meta_ca’ : type 1 criterion for meta-d’ fit, RMS units.

  • ‘t2ca_rS1’type 2 criteria of “S1” responses for meta-d’ fit,

    RMS units.

  • ‘t2ca_rS2’type 2 criteria of “S2” responses for meta-d’ fit,

    RMS units.

  • ‘logL’ : log likelihood of the data fit

  • ‘est_HR2_rS1’estimated (from meta-d’ fit) type 2 hit rates

    for S1 responses.

  • ‘obs_HR2_rS1’ : actual type 2 hit rates for S1 responses.

  • ‘est_FAR2_rS1’estimated type 2 false alarm rates for S1

    responses.

  • ‘obs_FAR2_rS1’actual type 2 false alarm rates for S1

    responses.

  • ‘est_HR2_rS2’ : estimated type 2 hit rates for S2 responses.

  • ‘obs_HR2_rS2’ : actual type 2 hit rates for S2 responses.

  • ‘est_FAR2_rS2’estimated type 2 false alarm rates for S2

    responses.

  • ‘obs_FAR2_rS2’actual type 2 false alarm rates for S2

    responses.

Notes

Given data from an experiment where an observer discriminates between two stimulus alternatives on every trial and provides confidence ratings, provides a type 2 SDT analysis of the data.

Warning

If nR_S1 or nR_S2 contain zeros, this may interfere with estimation of meta-d’. Some options for dealing with response cell counts containing zeros are:

  • Add a small adjustment factor (e.g. 1/(len(nR_S1), to each input

    vector. This is a generalization of the correction for similar estimation issues of type 1 d’ as recommended in [1]_. When using this correction method, it is recommended to add the adjustment factor to ALL data for all subjects, even for those subjects whose data is not in need of such correction, in order to avoid biases in the analysis (cf [2]_). Use padding==True to activate this correction.

  • Collapse across rating categories. e.g. if your data set has 4

    possible confidence ratings such that len(nR_S1)==8, defining new input vectors:

    >>> nR_S1 = nR_S1.reshape(int(len(nR_S1)/collapse), 2).sum(axis=1)

    This might be sufficient to eliminate zeros from the input without using an adjustment. Use collapse=True to activate this correction.

If there are N ratings, then there will be N-1 type 2 hit rates and false alarm rates.

References

..[1] Hautus, M. J. (1995). Corrections for extreme proportions and their

biasing effects on estimated values of d’. Behavior Research Methods,

Instruments, & Computers, 27, 46-51.

..[2] Snodgrass, J. G., & Corwin, J. (1988). Pragmatics of measuring

recognition memory: Applications to dementia and amnesia. Journal of Experimental Psychology: General, 117(1), 34–50. https://doi.org/10.1037/0096-3445.117.1.34

Examples

No correction >>> nR_S1 = [36, 24, 17, 20, 10, 12, 9, 2] >>> nR_S2 = [1, 4, 10, 11, 19, 18, 28, 39] >>> fit = fit_meta_d_MLE(nR_S1, nR_S2, padding=False)

Correction by padding values >>> nR_S1 = [36, 24, 17, 20, 10, 12, 9, 2] >>> nR_S2 = [1, 4, 10, 11, 19, 18, 28, 39] >>> fit = fit_meta_d_MLE(nR_S1, nR_S2, padding=True)

Correction by collapsing values >>> nR_S1 = [36, 24, 17, 20, 10, 12, 9, 2] >>> nR_S2 = [1, 4, 10, 11, 19, 18, 28, 39] >>> fit = fit_meta_d_MLE(nR_S1, nR_S2, collapse=2)