- Notifications
You must be signed in to change notification settings - Fork1
Development of an R package for metacognition researchers
License
ManuelRausch/StatConfR
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
ThestatConfR
package provides functions to fit static models ofdecision-making and confidence derived from signal detection theory forbinary discrimination tasks with confidence ratings on the data fromindividual subjects (Rausch et al., 2025). Up to now, the followingmodels have been included:
- signal detection rating model (Green & Swets, 1966),
- Gaussian noise model (Maniscalco & Lau, 2016),
- weighted evidence and visibility model (Rausch et al., 2018),
- post-decisional accumulation model (Rausch et al., 2018),
- independent Gaussian model (Rausch & Zehetleitner, 2017),
- independent truncated Gaussian model (the model underlying themeta-d
$^\prime$ /d$^\prime$ method, see Rausch et al., 2023), - lognormal noise model (Shekhar & Rahnev, 2021), and
- lognormal weighted evidence and visibility model (Shekhar & Rahnev,2023).
In addition, thestatConfR
package provides functions for estimatingdifferent kinds of measures of metacognition:
meta-d
$^\prime$ /d$^\prime$ , the most widely-used measure ofmetacognitive efficiency, allowing both Maniscalco and Lau (2012)’sand Fleming (2017)’s model specification. Fitting models of confidenceis a way to test the assumptions underlyingmeta-d$^\prime$ /d$^\prime$ .information-theoretic measures of metacognition (Dayan, 2023),including
- meta-I, an information-theoretic measures of metacognitivesensitivity,
$meta-I_{1}^{r}$ and$meta-I_{2}^{r}$ , two measures ofmetacognitive efficiency proposed by Dayan (2023),- meta-
$I_{1}^{r\prime}$ , a novel variant of$meta-I_{1}^{r}$ , - RMI, a novel measure of metacognitive accuracy, also derived frominformation theory.
The models included in the statConfR package are all based on signaldetection theory (Green & Swets, 1966). It is assumed that participantsselect a binary discrimination response
- sensitivity parameters
$d_1, ..., d_K$ ($K$ : number of difficultylevels), - decision criterion
$c$ , - confidence criterion
$\theta_{-1,1}, ..., \theta_{-1,L-1}, \theta_{1,1}, ,...,\theta_{1,L-1}$ ($L$ : number of confidencecategories available for confidence ratings).
According to SDT, the same sample of sensory evidence is used togenerate response and confidence, i.e.,
Conceptually, the Gaussian noise model reflects the idea that confidenceis informed by the same sensory evidence as the task decision, butconfidence is affected by additive Gaussian noise. According to GN,
Conceptually, the WEV model reflects the idea that the observer combinesevidence about decision-relevant features of the stimulus with thestrength of evidence about choice-irrelevant features to generateconfidence. For this purpose, WEV assumes that
PDA represents the idea of on-going information accumulation after thediscrimination choice. The parameter
According to IG, the information used for confidence judgments isgenerated independently from the sensory evidence used for the taskdecision. For this purpose, it is assumed that
Conceptually, the two ITG models just as IG are based on the idea thatthe information used for confidence judgments is generated independentlyfrom the sensory evidence used for the task decision. However, incontrast to IG, the two ITG models also reflect a form of confirmationbias in so far as it is not possible to collect information thatcontradicts the original decision. According to the version of ITGconsistent with the HMetad-method (Fleming, 2017),
According to the version of the ITG consistent with the original meta-d’method (Maniscalco & Lau, 2012, 2014),
According to logN, the same sample of sensory evidence is used togenerate response and confidence, i.e.,
The logWEV model is a combination of logN and WEV proposed by .Conceptually, logWEV assumes that the observer combines evidence aboutdecision-relevant features of the stimulus with the strength of evidenceabout choice-irrelevant features. The model also assumes that noiseaffecting the confidence decision variable is lognormal. According tologWEV, the confidence decision variable is
The conceptual idea of meta-d
It is assumed that a classifier (possibly a human being performing adiscrimination task) or an algorithmic classifier in a classificationapplication, makes a binary prediction
- Meta-I is a measure of metacognitive sensitivity defined as the mutualinformation between the confidence and accuracy and is calculated asthe transmitted information minus the minimal information given theaccuracy of the classification response:
It can be shown that this is equivalent to Dayan’s formulation of meta-Ias the information that confidence transmits about the correctness of aresponse:
- Meta-
$I_{1}^{r}$ is meta-I normalized by the value of meta-Iexpected assuming a signal detection model (Green & Swets, 1966) withGaussian noise, based on calculating the sensitivity index d’:
Meta-
$I_{1}^{r\prime}$ is a variant of meta-$I_{1}^{r}$ , whichnormalizes by the meta-I that would be expected from an underlyingnormal distribution with the same accuracy (this is similar to thesensitivity approach but without considering variable thresholds).Meta-
$I_{2}^{r}$ is meta-I normalized by its theoretical upperbound, which is the information entropy of accuracy,$H(S = R)$ :
Notably, Dayan (2023) pointed out that a liberal or conservative use ofthe confidence levels will affected the mutual information and thus allinformation-theoretic measures of metacognition.
In addition to Dayan’s measures, Meyen et al. (submitted) suggested anadditional measure that normalizes meta-I by the range of possiblevalues it can take. Normalizing meta-I by the range of possible valuesrequires deriving lower and upper bounds of the transmitted informationgiven a participant’s accuracy.
As these measures are prone to estimation bias, the package offers asimple bias reduction mechanism in which the observed frequencies ofstimulus-response combinations are taken as the underlying probabilitydistribution. From this, Monte-Carlo simulations are conducted toestimate and subtract the bias from these measures. Note that the biasis only reduced but not removed completely.
The latest released version of the package is available on CRAN via
install.packages("statConfR")
The easiest way to install the development version is usingdevtools
and install from GitHub:
devtools::install_github("ManuelRausch/StatConfR")
The package includes a demo data set from a masked orientationdiscrimination task with confidence judgments (Hellmann et al., 2023,Exp. 1).
library(statConfR)data("MaskOri")head(MaskOri)
## participant stimulus correct rating diffCond trialNo## 1 1 0 1 0 8.3 1## 2 1 90 0 4 133.3 2## 3 1 0 1 0 33.3 3## 4 1 90 0 0 16.7 4## 5 1 0 1 3 133.3 5## 6 1 0 1 0 16.7 6
The functionfitConfModels
allows the user to fit several confidencemodels separately to the data of each participant using maximumlikelihood estimation. The data should be provided via the argument.data
in the form of a data.frame object with the following variablesin separate columns:
- stimulus (factor with 2 levels): The property of the stimulus whichdefines which response is correct
- diffCond (factor): The experimental manipulation that is expected toaffect discrimination sensitivity
- correct (0-1): Indicating whether the choice was correct (1) orincorrect(0).
- rating (factor): A discrete variable encoding the decision confidence(high: very confident; low: less confident)
- participant (integer): giving the subject ID. The argument
model
isused to specify which model should be fitted, with ‘WEV’, ‘SDT’, ‘GN’,‘PDA’, ‘IG’, ‘ITGc’, ‘ITGcm’, ‘logN’, and ‘logWEV’ as availableoptions. If model=“all” (default), all implemented models will be fit,although this may take a while.
Setting the optional argument.parallel=TRUE
parallizes model fittingover all but 1 available core.Note that the fitting procedure takesmay take a considerable amount of time, especially when there aremultiple models, several difficulty conditions, and/or multipleconfidence categories. For example, if there are five difficultyconditions and five confidence levels, fitting the WEV model to onesingle participant may take 20-30 minutes on a 2.8GHz CPU. We recommendparallelization to keep the required time tolerable.
The fitting routine first performs a coarse grid search to findpromising starting values for the maximum likelihood optimizationprocedure. Then the bestnInits
parameter sets found by the gridsearch are used as the initial values for separate runs of theNelder-Mead algorithm implemented in optim (default: 5). Each run isrestartednRestart
times (default: 4).
fitted_pars<- fitConfModels(MaskOri,models=c("ITGcm","WEV"),.parallel=TRUE)
The output is then a data frame with one row for each combination ofparticipant and model and separate columns for each estimated parameter(d_1, d_2, d_3, d_4, c, theta_minus.4 theta_minus.3, theta_minus.2,theta_minus.1, theta_plus.1, theta_plus.2, theta_plus.3, theta_plus.4for both models, w and sigma for WEV, and m only for ITGcm) as well asfor different measures for goodness-of-fit (negative log-likelihood,BIC, AIC and AICc).
head(fitted_pars)
## model participant negLogLik N k BIC AICc AIC d_1## 1 ITGcm 1 2719.492 1620 15 5549.837 5469.247 5468.985 0.02791587## 2 WEV 1 2621.110 1620 16 5360.464 5274.520 5274.221 0.20268438## 3 ITGcm 2 1926.296 1620 15 3963.445 3882.854 3882.592 0.01889636## 4 WEV 2 1827.221 1620 16 3772.684 3686.741 3686.441 0.05119639## 5 ITGcm 3 1695.957 1620 15 3502.766 3422.176 3421.914 0.32340627## 6 WEV 3 1661.617 1620 16 3441.476 3355.533 3355.233 0.41460563## d_2 d_3 d_4 d_5 c theta_minus.4 theta_minus.3## 1 0.43212223 1.0210704 3.472310 4.395496 -0.2499098 -1.584000 -1.055322## 2 0.61422596 1.0796567 3.474608 4.079890 -0.2957338 -2.066516 -1.248524## 3 0.06496444 0.6926183 4.209053 5.463259 -0.1068211 -2.109575 -2.009674## 4 0.19195858 1.0412267 4.142295 5.288622 -0.1474590 -2.044069 -1.950015## 5 0.60550967 2.3776478 7.924170 9.428593 -1.2804566 -1.793311 -1.448681## 6 0.85608686 2.7115290 6.916448 7.986348 -1.3742943 -2.762529 -1.919228## theta_minus.2 theta_minus.1 theta_plus.1 theta_plus.2 theta_plus.3## 1 -0.6463512 -0.4645142 -0.09770594 0.2168548 1.0019751## 2 -0.4151617 0.1296425 -0.61959026 0.1544368 1.3976350## 3 -1.4620933 -0.9950160 0.78839560 1.4081014 2.1950659## 4 -1.3982493 -0.9030114 0.82007352 1.4484447 2.2446957## 5 -1.0652684 -0.9656961 -0.92027462 -0.6053266 0.3337906## 6 -0.3723945 0.9327974 -2.76951959 -1.1312635 0.7714093## theta_plus.4 m sigma w## 1 1.6044716 1.1177354 NA NA## 2 2.1879187 NA 1.0104584 0.5361153## 3 2.3601086 1.5701944 NA NA## 4 2.4029896 NA 0.6390763 0.5019978## 5 0.9382662 0.7404757 NA NA## 6 1.7520050 NA 1.3288815 0.3817864
After obtaining the model fit, it is strongly recommended to visualisethe predictions implied by the best-fitting set of parameters andcompare these predictions with the actual data (Palminteri et al.,2017). ThestatConfR
package provides the functionplotConfModelFit
,which creates aggplot
object with empirically observed distributionof responses and confidence ratings as bars on the x-axis as a functionof discriminability (in the rows) and stimulus (in the columns).Superimposed on the empirical data, the plot also shows the predictionof one selected model as dots. The parameters of the model are passed toplotConfModelFit
by the argumentfitted_pars
.
PlotFitWEV<- plotConfModelFit(MaskOri,fitted_pars,model="WEV")PlotFitITGcm<- plotConfModelFit(MaskOri,fitted_pars,model="ITGcm")
PlotFitWEV
PlotFitITGcm
Assuming that the independent truncated Gaussian model provides a decentaccount of the data (notably, this is not the case in the demo dataset), the functionfitMetaDprime
can be used to estimatemeta-d.data
and.parallel=TRUE
work just in the same way thearguments offitConfModels
. The argumentmodel
offers the user thechoice between two model specifications, either “ML” to use the originalmodel specification used by Maniscalco and Lau (2012, 2014) or “F” touse the model specification by Fleming (2017)’s Hmetad method. ThefunctionfitMetaDprime
produces a dataframe with one row for eachparticipant and the following columns:
- participant: the participant id,
- model: indicating which model specification has been used,
- dprime: the sensitivity index d′ from signal detection theory, ameasure of discrimination performance,
- c: the bias index c from signal detection theory, a measure ofdiscrimination bias,
- Ratio: The meta-d′/d′ index, the most common measure of metacognitiveefficiency.
MetaDs<- fitMetaDprime(data=MaskOri,model="ML",.parallel=TRUE)head(MetaDs)
## model participant dprime c metaD Ratio## 1 ML 1 1.441199 -0.2597310 1.423263 0.9875551## 2 ML 2 1.253587 -0.1175263 2.074045 1.6544885## 3 ML 3 2.253395 -1.0013475 1.508996 0.6696544## 4 ML 4 1.515356 0.1231483 3.192407 2.1067045## 5 ML 5 1.314925 -0.1047285 2.740354 2.0840380## 6 ML 6 1.260150 -0.1400093 1.872001 1.4855389
Information-theoretic measures of metacognition can be obtained by thefunctionestimateMetaI
. It expects the same kind of data.frame asfitMetaDprime
andfitConfModels
, returning a dataframe with one rowfor each participant and the following columns:
participant
: the participant id,meta_I
is the estimated meta-I value (expressed in bits, i.e. logbase is 2),meta_Ir1
is meta-$I_{1}^{r}$ ,meta_Ir1_acc
is meta-$I_{1}^{r\prime}$ ,meta_Ir2
is meta-$I_{2}^{r}$ , andRMI
is RMI.
metaIMeasures<- estimateMetaI(data=MaskOri,bias_reduction=FALSE)head(metaIMeasures)
## participant meta_I meta_Ir1 meta_Ir1_acc meta_Ir2 RMI## 1 1 0.1154252 1.300914 1.384554 0.1434999 0.3687714## 2 2 0.2034822 2.781828 2.815966 0.2432133 0.6708776## 3 3 0.1921722 1.549884 2.038785 0.2529526 0.6001439## 4 4 0.2223333 2.403126 2.429517 0.2884294 0.6969924## 5 5 0.2277498 2.922673 2.945799 0.2774337 0.7380805## 6 6 0.1648054 2.232405 2.276843 0.1969847 0.5433609
All information-theoretic measures can be calculated with a bias-reducedvariant for which the observed frequencies are taken as underlyingprobability distribution to estimate the sampling bias. The estimatedbias is then subtracted from the initial measures. This approach usesMonte-Carlo simulations and is therefore not deterministic. This is thepreferred way to estimate the information-theoretic measures, but it maytake ~ 6 s for each subject. To invoke bias reduction, the argumentbias_reduction
needs to be set to TRUE:
metaIMeasures <- estimateMetaI(data = MaskOri, bias_reduction = TRUE)
After installation, the documentation of each function ofstatConfR
can be accessed by typing?functionname into the console.
The package is under active development. We are planning to implementnew models of decision confidence when they are published. Please feelfree tocontact us tosuggest new models to implement in the package, or to volunteer addingadditional models.
Implementing custom models of decision confidence is only recommendedfor users with experience in cognitive modelling! For readers who wantto use our open code to implement models of confidence themselves, thefollowing steps need to be taken:
- Derive the likelihood of a binary response (
$R=-1, 1$ ) and aspecific level of confidence ($C=1,...K$ ) according to the custommodel and a set of parameters, given the binary stimulus($S=-1, 1$ ), i.e.$P(R, C | S)$ . - Use one of the files named ‘int_llmodel.R’ from the package sourcesand adapt the likelihood function according to your model. Accordingto our convention, name the new file a ‘int_llyourmodelname.R’. Notethat all parameters are fitted on the reals, i.e. positive parametersshould be transformed outside the log-likelihood function (e.g. usingthe logarithm) and back-transformed within the log-likelihood function(e.g. using the exponential).
- Use one of the files ‘int_fitmodel.R’ from the package sources andadapt the fitting function to reflect the new model.
- The initial grid used during the grid search should include aplausible range of all parameters of your model.
- If applicable, the parameters of the initial grid needs betransformed so the parameter vector for optimization isreal-valued).
- The optimization routine should call the new log-likelihoodfunction.
- If applicable, the parameter vector i obtained during optimizationneeds to back-transformation for the the output object
res
. - Name the new file according to the convention‘int_fityourmodelname.R’.
- Add your model and fitting-functions to the high-level functions
fitConf
andfitConfModels
. - Add a simulation function in the file ‘int_simulateConf.R’ which usesthe same structure as the other functions but adapt the likelihood ofthe responses.
For comments, bug reports, and feature suggestions please feel free towrite to eithermanuel.rausch@hochschule-rhein-waal.de orsebastian.hellmann@tum.de orsubmit anissue.
- Cover, T. M., & Thomas, J. A. (2006). Elements of information theory.2nd edition. Wiley.
- Dayan, P. (2023). Metacognitive Information Theory. Open Mind, 7,392–411. doi:10.1162/opmi_a_00091
- Fleming, S. M. (2017). HMeta-d: Hierarchical Bayesian estimation ofmetacognitive efficiency from confidence ratings. Neuroscience ofConsciousness, 1, 1–14. doi:10.1093/nc/nix007
- Green, D. M., & Swets, J. A. (1966). Signal detection theory andpsychophysics. Wiley.
- Hellmann, S., Zehetleitner, M., & Rausch, M. (2023). Simultaneousmodeling of choice, confidence, and response time in visualperception. Psychological Review, 130(6), 1521–1543.doi:10.1037/rev0000411
- Maniscalco, B., & Lau, H. (2012). A signal detection theoretic methodfor estimating metacognitive sensitivity from confidence ratings.Consciousness and Cognition, 21(1), 422–430.doi:10.1016/j.concog.2011.09.021
- MacKay, D. J. (2003). Information theory, inference and learningalgorithms. Cambridge University Press.
- Maniscalco, B., & Lau, H. (2016). The signal processing architectureunderlying subjective reports of sensory awareness. Neuroscience ofConsciousness, 1, 1–17. doi:10.1093/nc/niw002
- Maniscalco, B., & Lau, H. C. (2014). Signal Detection Theory Analysisof Type 1 and Type 2 Data: Meta-d, Response- Specific Meta-d, and theUnequal Variance SDT Model. In S. M. Fleming & C. D. Frith (Eds.), TheCognitive Neuroscience of Metacognition (pp. 25–66). Springer.doi:10.1007/978-3-642-45190-4_3
- Palminteri, S., Wyart, V., & Koechlin, E. (2017). The importance offalsification in computational cognitive modeling. Trends in CognitiveSciences, 21(6), 425–433. doi:10.1016/j.tics.2017.03.011
- Rausch, M., Hellmann, S., & Zehetleitner, M. (2018). Confidence inmasked orientation judgments is informed by both evidence andvisibility. Attention, Perception, and Psychophysics, 80(1), 134–154.doi:10.3758/s13414-017-1431-5
- Rausch, M., & Zehetleitner, M. (2017). Should metacognition bemeasured by logistic regression? Consciousness and Cognition, 49,291–312. doi:10.1016/j.concog.2017.02.007
- Rausch, M., Meyen, S. & Hellmann, S. (2025). statConfR: An R Packagefor Static Models of Decision Confidence and Metacognition. Journal ofOpen Source Software, 10(106), 6966.https://doi.org/10.21105/joss.06966
- Shekhar, M., & Rahnev, D. (2021). The Nature of MetacognitiveInefficiency in Perceptual Decision Making. Psychological Review,128(1), 45–70. doi:10.1037/rev0000249
- Shekhar, M., & Rahnev, D. (2024). How Do Humans Give Confidence? AComprehensive Comparison of Process Models of PerceptualMetacognition. Journal of Experimental Psychology: General, 153(3),656–688. doi:10.1037/xge0001524