This module contains data objects to store psychophysical data and perform inference on them. Two general approaches have been suggested to fit psychometric functions
The module also defines a :PsiInference: base class.
BootstrapInference(data[, sample, cuts, ...])  Set up an object of bootstrapped data 
BayesInference(data[, sample, cuts, conf, ...])  Bayesian Inference for psychometric functions using MCMC 
Set up an object of bootstrapped data
Parameters: 


Example: 
Estimate a psychometric function from some example data and derive bootstrap confidence intervals for a threshold
>>> x = [0,2,4,6,8,10]
>>> k = [26,30,38,46,50,49]
>>> n = [50]*len(k)
>>> B = BootstrapInference ( zip(x,k,n), priors=("flat","flat","Uniform(0,0.1)"), sample=True )
>>> B.estimate
array([ 3.80593409, 1.09308994, 0.00935698])
>>> B.deviance
2.5160989036891754
>>> B.getThres()
3.805934094097025
>>> B.getCI(1)
array([ 2.79484448, 4.73796576])
Determine the confidence interval of a cut
Parameters: 


Type of inference performed by the object
A boolean vector indicating whether a block should be considered an influential observation
A vector of correlations between block index and deviance residuals in all bootstrap samples
A vector of correlations between model prections and deviance residuals in all bootstrap samples
A gaussian kernel density estimate of the joint density of the first two parameters of the model
A vector of bootstrapped deviances
An array of bootstrap estimates of the fitted paramters
Slopes of the bootstrap replications
Thresholds of the bootstrap replications
number of bootstrap samples (setting this attribute results in resampling!!!)
A boolean vector indicating whether a block should be considered an outlier
Draw bootstrap samples
Parameters: 


Draw nonparametric bootstrap samples
Parameters: 


Perform sensitivity_analysis to obtain expanded bootstrap intervals
Sensitivity analysis is a strategy to expand bootstrap confidence intervals. Typically, the expanded bootstrap confidence intervals are more realistic than the unexpanded confidence intervals. The function fits a gaussian kernel density estimator to the joint distribution of the first two parameters (those that determine the shape of the psychometric function) and determines a number of points on the 68% contour of this estimated density. For each of these points bootstrap confidence intervals are estimated. The final bootstrap confidence intervals are then defined as the widest of these confidence intervals. After calling sensitivity_analysis() the getCI() method will give the expanded BCa confidence intervals.
Parameters: 


Output: 

Bayesian Inference for psychometric functions using MCMC
Parameters: 


Example: 
Use MCMC to estimate a psychometric function from some example data and derive posterior intervals for a threshold
>>> x = [0,2,4,6,8,10]
>>> k = [26,30,38,46,50,49]
>>> n = [50]*len(k)
>>> mcmc = BayesInference ( zip(x,k,n), priors=("Gauss(0,5)","Gamma(1,4)","Beta(2,50)") )
>>> mcmc.sample ( start=3*mcmc.estimate )
>>> mcmc.sample ( start=0.1*mcmc.estimate )
>>> mcmc.estimate
array([ 3.64159245, 5.13138577, 0.02117899])
>>> mcmc.deviance
3.2953368439616186
>>> mcmc.getThres()
3.6522408270087667
>>> mcmc.getCI()[1]
array([ 2.65917603, 3.68535429, 4.56688308])
Deviance information criterion
This is an information criterion based on the posterior distribution of deviance. In contrast, to other information criteria, the deviance information criterion determines the effective number of free parameters from the posterior distribution.
Gelman Rhat statistic for convergence using multiple chains
This is also called the ‘estimated potential scale reduction’. A value Rhat > 1.1 is indicative of poor convergence.
Bayesian p value associated with a given quantity
The Bayesian p value of a model compares posterior predictives with the observed data. If the observed data are very unequal to the posterior predictives, this indicates that the model does not describe the data well. To compare observed data and simulated data (posterior predictives), it is common to derive a quantity of interest from the posterior predictives. The Bayesian p value is between 0 and 1 and values close to 0 and close to 1 indicate bad model fit. This p value can be interpreted like a two sided test.
Parameters: 


Output:  the bayesian pvalue 
Burnin: Number of samples to be discarded at the beginning of each chain
Deviance of the estimate.
If sampling has already occurred, this will be the deviance of the mean estimate. Otherwise it will be the deviance of the mapestimate.
plots the mean estimate of the psychometric function and a number of samples from the posterior
Parameters: 


Estimate of the parameters.
If sampling has already occurred, this will be the mean estimate, otherwise it will be the mapestimate.
model evidence or marginal likelihood
Model evidence is typically given as the integral of the likelihood over the parameter space. We replace the integral by a discrete sum over samples, such that we have
E = 1/N sum P(Dtheta)
Model evidence is typically used in Bayesian model selection: If E1 is the evidence for model 1 and E2 is the evidence for model 2, then the ratio E1/E2 can be interpreted as “how much more evidence is there for model 2 than for model 1”.
A proper starting value for the Rhat statistic
This is a starting value for the mcmc process, that is relatively far away from the posterior density. In order to have a reasonably interpretable Rhat statistic. There should be multiple chains and these chains should have overdispersed starting values. farstart will always correspond to an overdispersed starting value.
Get a posterior credibility interval for a particular parameter
Parameters: 


Get samples from the posterior distribution of deviances
Parameters: 


Output:  an array of samples from the posterior distribution of deviances. This array respects the burnin and thin settings. 
Get correlations between block index and deviance residuals associated with posterior predictive data
Posterior predictive data are data samples from the joint posterior over data and parameters. Correlation between the block index and the deviance residuals of these samples is one possible transformation on which a comparison of these data with the observed data could be based.
Parameters: 


Output:  an array of nsamples deviances 
Get correlations between psychometric function and deviance residuals associated with posterior predictive data
Posterior predictive data are data samples from the joint posterior over data and parameters. Correlation between the psychometric function and the deviance residuals of these samples is one possible transformation on which a comparison of these data with the observed data could be based.
Parameters: 


Output:  an array of nsamples deviances 
Get posterior predictive data
Posterior predictive data are data samples from the joint posterior over data and parameters. These represent data that could be generated by the model. Comparison of posterior predictive data and the observed data forms the basis of bayesian model checking: If posterior predictive data differ systematically from the observed data, the fitted model does not capture all the structure in the data.
Parameters: 


Output:  a array of nsamplesXncorrect predicted data 
Get deviances associated with posterior predictive data
Posterior predictive data are data samples from the joint posterior over data and parameters. Deviance of these samples is one possible transformation on which a comparison of these data with the observed data could be based.
Parameters: 


Output:  an array of nsamples deviances 
Get sampes from the posterior
Parameters: 


Output:  an array of nsamplesXnparams samples from the posterior 
Geweke test for stationarity of a chain.
The Geweke test first transforms all samples to mean 0 and standard deviation 1. In a second step, it calculates the sample average in a number of segments and checks whether these subaverages differ significantly from 0.
Parameters: 


Output:  a boolean value indicating whether the chain is “good” or “bad” 
Type of inference performed by the object
Monte Carlo samples of posterior correlation between bock index and data
Monte Carlo samples of posterior correlation between model predictions and data
Deviances of monte carlo samples from the posterior
Monte Carlo samples from the posterior distribution of parameters
Monte Carlo Samples from the posterior distribution of slopes
Monte Carlo Samples from the posterior distribution of thresholds
Number of chains that have been sampled
model evidence for the corresponding null model
This can be used for model selection: model evidence devided by null evidence gives the Bayes Factor for the comparison of the model agains the null model. This can be interpreted as “how much more probable is the given psychometric function than the null model for the present data. Also see the documentation for the evidence property.
effective number of parameters
Median for the posterior, for all sampled chains.
Posterior predictive data associated with the MCMC samples
Correlations between block index and deviance residuals associated with posterior predictive data
Correlations between psychometric function and deviance residuals associated with posterior predictive data
Deviances associated with the posterior predictive data
Replace a chain
Parameters: 


Draw samples from the posterior distribution using MCMC
Parameters: 


Thinning: Subsample chains to reduce autocorrelation
The following functions will be imported by default:
GoodnessOfFit(InferenceObject[, warn])  Draw a diagnostic figure to help assessing goodness of fit 
ConvergenceMCMC(BayesInferenceObject[, ...])  Diagram to check convergence of MCMC chains for a single parameter 
ParameterPlot(InferenceObject)  Show distributions and estimates for all parameters in the model 
ThresholdPlot(InferenceObject)  Show distributions and estimates for all thresholds 
plotSensitivity(BootstrapInferenceObject[, ax])  Visualize a sensitivity analysis to determine expanded bootstrap confidence intervals 
plotInfluential(InferenceObject)  Diagnostic plot for detecting influential observations 
plotMultiplePMFs(*InferenceObjects, **kwargs)  Plot multiple psychometric functions 
Draw a diagnostic figure to help assessing goodness of fit
This graphic is intended to help the user determine how well the fitted function describes the data. The plot has 6 fields:
1  3  5 
2  4  6 
The fields provide the following information: 1. The data and the fitted psychometric function. “fitted” here means the parameters are
the mean of the posterior for BayesInference objects and the (constrained) maximum likelihood fit for BootstrapInference objects. To get an idea of the posterior resp. bootstrap distribution, credibility intervals are plotted at some positions (the location and width of the credibility intervals is given in the constructor). To make the posterior distribution for BayesInference objects really “plastic”, a number of samples from the posterior distribution over psychometric functions are also drawn in light blue. The saturation of blue also codes the deviance of the respective function: the more saturated, the better the fit. For BootstrapInference objects, outliers and influential observations are marked as red triangles and red squares.
Parameters: 


Diagram to check convergence of MCMC chains for a single parameter
Parameters: 


Show distributions and estimates for all parameters in the model
Parameters: 


Show distributions and estimates for all thresholds
Parameters: 


Visualize a sensitivity analysis to determine expanded bootstrap confidence intervals
Sensitivity analysis is used for BootstrapInference objects to expand the confidence intervals in order to obtain more realistic coverage. This function calls the sensitivity_analysis() method of the BootstrapInferenceObject with default parameters. If other parameters are requested, the sensitivity_analysis() method should be called manually
Parameters: 


Diagnostic plot for detecting influential observations
Determining influential observations follows a different logic for bootstrap and for bayes inference. A block is labelled an influential observation if the fit for a dataset without that point is significantly different from the fit including that point. For BootstrapInference objects, this is quantified using a normed distance of the maximum likelihood fit including the block and withouth that block. This distance is normed in the following way: If the maximum likelihood fit for the reduced dataset remains inside the 95% confidence limits of the maximum likelihood fit for the full dataset, the influence value is below 1. Thus, influence values large than 1 indicate a problem with the data set. For BayesInference objects, the influence of a block is simply quantified as the KullbachLeibler divergence of the posterior for the full data set from the posterior for the reduced data set.
Parameters: 


Plot multiple psychometric functions
Parameters: 


Example: 
This example shows how to plot multiple psychometric functions
>>> d0 = [[0, 28, 50], [2, 33, 50], [4, 38, 50], [6, 45, 50], [8, 45, 50], [10, 49, 50]]
>>> d1 = [[0, 22, 50], [2, 34, 50], [4, 31, 50], [6, 42, 50], [8, 42, 50], [10, 46, 50]]
>>> d2 = [[0, 26, 50], [2, 31, 50], [4, 38, 50], [6, 47, 50], [8, 49, 50], [10, 49, 50]]
>>> constraints = ("","","Uniform(0,.1)")
>>> B0 = BootstrapInference ( d0, priors=constraints,plotprm={"color": "r", "label": "Condition 0"} )
>>> B1 = BootstrapInference ( d1, priors=constraints, plotprm={"color": "b","label": "Condition 1"} )
>>> B2 = BootstrapInference ( d2, priors=constraints, plotprm={"color": "b","label": "Condition 2"} )
>>> plotMultiplePMFs ( B0, B1, B2 )
Plot joint distribution of parameters
For ASIRInference objects, also the fitted marginals are shown
To get access to all plot functions in isolation, they can also be imported separately. Here is the documentation
drawaxes(ax[, xtics, xfmt, ytics, yfmt, ...])  Draw x and y axes that look nicer than standard matplotlib 
plotRd(InferenceObject[, ax, regressor])  plot deviance residuals against a regressor 
plotHistogram(simdata, observed, xname[, ...])  plot a histogram and compare observed data to it 
plotPMF(InferenceObject[, xlabel_text, ...])  Show the psychometric function and data in an axes system 
plotThres(InferenceObject[, ax, color])  Plot thresholds and confidence intervals 
plotGeweke(BayesInferenceObject[, ...])  Geweke plot of moving average of samples 
plotChains(BayesInferenceObject[, ...])  Simply plot all chains for a single parameter 
plotParameterDist(InferenceObject[, ...])  Plot the distribution of parameters 
Draw x and y axes that look nicer than standard matplotlib
This function deletes the pylab default axes and draws visually more pleasing axes. In addition it takes care that all graphics remain within the area covered by the axes.
Parameters: 


plot deviance residuals against a regressor
Deviance residuals are used plotted agains either predicted performance or block index to check for systematic deviations of the data from the fitted function.
Parameters: 


plot a histogram and compare observed data to it
Parameters: 


Output: 

plot a scatter diagram to compare observed and predicted data
Parameters: 


Show the psychometric function and data in an axes system
This function plots the best fitting psychometric function and with the corresponding data points. If data points are labelled influential, they are plotted as red squares, if data points are labelled as outliers, they are plotted as red triangles. The function uses its internal knowledge about the task (nAFC or Yes/No) to put the correct labels to the yaxis.
Parameters: 


Return:  returns a tuple (line,points,lims) line :

Example: 
You can use this function to plot multiple psychometric functions. However, keep in mind that the function plotMultiplePMFs does the same job more conveniently for you. However, plotPMF will typically allow for more control over the plotting process. this is demonstrated below:
>>> d0 = [[0, 28, 50], [2, 33, 50], [4, 38, 50], [6, 45, 50], [8, 45, 50], [10, 49, 50]]
>>> d1 = [[0, 22, 50], [2, 34, 50], [4, 31, 50], [6, 42, 50], [8, 42, 50], [10, 46, 50]]
>>> d2 = [[0, 26, 50], [2, 31, 50], [4, 38, 50], [6, 47, 50], [8, 49, 50], [10, 49, 50]]
>>> constraints = ("","","Uniform(0,.1)")
>>> B0 = BootstrapInference ( d0, priors=constraints, plotting={'color': 'r'} )
>>> B1 = BootstrapInference ( d1, priors=constraints, plotting={'color': 'b'} )
>>> B2 = BootstrapInference ( d2, priors=constraints, plotting={'color': 'k'} )
>>> plotPMF ( B0, showaxes=False )
>>> plotPMF ( B1, showaxes=False )
>>> plotPMF ( B2, showaxes=True )
Note that the last call to plotPMF sets showaxes to True and thus draws the axes.
Plot thresholds and confidence intervals
Parameters: 


Geweke plot of moving average of samples
Parameters: 


Simply plot all chains for a single parameter
Parameters: 


Plot the distribution of parameters
Parameters: 


psignifit allows to simulate a number of observers to access stability of psychometric functions.
Observer(*params, **model)  A stationary binomial observer 
LinearSystemLearner(*params, **model)  A nonstationary observer that learns like a linear system in one or more parameters 
CriterionSettingObserver(*params, **model)  A nonstationary observer that recalibrates its decision process according to CST 
BetaBinomialObserver(*params, **model)  An overdispersed observer that otherwise follows binomial assumptions 
A stationary binomial observer
This is the observer, we all want: No interdependencies between trials, no learning, no fluctuations in attention or motivation. Perfectly binomial responses in accordance with the psychometric function shape you supply.
Parameters: 


Example: 
>>> O = Observer ( 4, 1, .02 )
>>> O.seed ( 0 )
>>> O.DoATrial ( 3 )
1
>>> O.DoABlock ( 4, 40 )
28
>>> O.DoABlock ( 6, 40 )
37
>>> O.DoAnExperiment ( [2,4,6], 50 )
[[2, 27, 50], [4, 38, 50], [6, 46, 50]]
>>> O.data
[[3, 1, 1], [4, 28, 40], [6, 37, 40], [2, 27, 50], [4, 38, 50], [6, 46, 50]]
Example: 

>>> model ={"sigmoid" : "gumbel_r", "core" : "mw01", "nafc" : 2}
>>> correct = [0.1, 0.3, 0.5, 0.7, 0.9, 0.99]
>>> ob = Observer(4, 4, 0.05, **model)
>>> levels = ob.getlevels(correct)
>>> data = ob.DoAnExperiment(levels, ntrials=50)
Simulate a block of trials
Parameters: 


Output:  The number of Yesresponses (in Yes/No) or the number of correct responses (nAFC) 
Simulate a single trial
Parameters: 


Output:  The response in the trail (1/0 coding for Yes/No in Yes/NoTasks or for Correct/Incorrect in nAFC tasks) 
Simulate a whole experiment
Parameters: 


Output:  A list of lists. Each element of the list has the structure [stimulus_intensity, number_of_correct_or_yes_responses,number_of_trials] 
Evaluate the psychometric function
Parameters: 


Determine stimulus levels that correspond to predefinde levels of performance
parameters of the model
Seed the underlying random number generator to a defined value
determine 50%% of the model
A nonstationary observer that learns like a linear system in one or more parameters
For this observer, the parameters of the psychometric function change: The parameters given to the constructor are initial values. In addition, a dictionary is given containing the learning parameters.
The constructor requires a dictionary that describes the changes of the parameters. The dictionary has keys ‘a’, ‘b’, and/or ‘lapse’. For each key, there are two parameters: the rate of decay and the asymptote where the parameter converges. Thus {‘a’ : ( 40, 3)} means that after every trial, the a parameter is modified according to a = (a3)/4
Parameters: 


Example: 
>>> O = LinearSystemLearner ( 7, 2, .02, {'a': (40,3)} )
>>> O.seed ( 0 )
>>> O.a
7.0
>>> O.DoATrial ( 3 )
1
>>> O.DoABlock ( 4, 50 )
34
>>> O.DoAnExperiment ( [4,2,8,10,6], 50 )
[[4, 43, 50], [2, 32, 50], [8, 48, 50], [10, 49, 50], [6, 38, 50]]
>>> O.data
[[3, 1, 1], [4, 34, 50], [4, 43, 50], [2, 32, 50], [8, 48, 50], [10, 49, 50], [6, 38, 50]]
>>> O.a
3.0019608723226945
Simulate a block of trials with learning
Parameters: 


Output:  the number of Yesresponses in a Yes/Notask or the number of correct responses in nAFC 
Simulate a single trial with learning
Parameters: 


Output:  either 1 or 0 indicating Yes/No in Yes/NoTasks or Correct/Incorrect in nAFC 
A nonstationary observer that recalibrates its decision process according to CST
Criterion setting theory (CST) is an extension to signal detection theory that was originally proposed by Treisman & Williams (1984): each isolated psychophysical decision is described in terms of signal detection theory. In addition, the criterion used by the observer is updated from trial to trial. There are two processes describing the updating of the criterion:
results in the criterion being placed roughly in the middle of the stimulus stream. Thus, stabilization can be said to maximize information transmission.
response. This strategy can be considered as a prior for an unchanging outside world.
Both, stabilization and tracking are described in the form of linearly decreasing traces. If Ec(j) ist the effective criterion on trial j and E(j) is the sensory input on trial j, then this will result in a stabilization trace of the form Ds*( E(j)  Ec(j) ). After one trial, this trace will have decreased on the next trial j+1 to Ds*( E(j)  Ec(j) )  ds. Thus, Ec(j+1) = Ec(j) + Ds*( E(j)  Ec(j))ds. Similarly for tracking, there are two parameters Dr and dr describing the size of an indicator trace directly after a response has been made and describing the decrease of an indicator trace from one trial to another.
Parameters: 


Example: 
>>> O = CriterionSettingObserver ( 4., 1., 0.02, 0.5, 0.1, 0.005, 0.1, 0.01 )
>>> O.seed ( 0 )
>>> O.DoATrial ( 1 )
0
>>> O.DoABlock ( 3, 30 )
24
>>> O.DoABlock ( 3, 30, 0 )
(5, 11, 8, 19)
Simulate a whole block of trials with criterion setting
Parameters: 


Output:  Number of Correct responses (nAFC) or a tuple with (number of hits, number of signal trials, number of false alarms, number of noise trials) 
Simulate a single trial with criterion setting
Parameters: 


Output:  A number 1 or 0, depending on the task, this means correct/incorrect (nAFC) or signal present, signal absent (Yes/No) 
An overdispersed observer that otherwise follows binomial assumptions
For every block, this observer draws a p value from a Beta distribution with mean given by the psychometric function. This pvalue is then used to generate the responses of that block.
Parameters: 


Example: 
>>> O = BetaBinomialObserver ( 4., 1., .02, 30 )
>>> O.seed ( 0 )
>>> O.DoABlock ( 4, 30 )
24
>>> O.DoABlock ( 4, 30 )
18
>>> O.DoAnExperiment ( [4,2,8,10,6], 50 )
[[4, 37, 50], [2, 24, 50], [8, 47, 50], [10, 49, 50], [6, 49, 50]]
Perform a block of trials
Parameters: 


Output:  number of correct responses (nAFC) or number of yes responses (Yes/NoTask) 