psignifit API

Data Types

This module contains data objects to store psychophysical data and perform inference on them. Two general approaches have been suggested to fit psychometric functions

1. Constrained maximum likelihood (Wichmann & Hill, 2001a,b) This procedure starts by fitting a psychometric function to the data and then performs parametric bootstrap to obtain confidence intervals for parameters, associated thresholds,... This approach is implemented by the :BootstrapInference: class.
2. Baysian Inference (Kuss et al., 2005) This procedure starts with a number of prior distributions for each of the models parameters and then uses Bayes rule to derive the posterior distribution from the data. As the posterior distribution can only be determined up to a normalization constant, inference on the posterior distribution has to be based on samples. These samples are typically obtained using Markoc Chain Monte Carlo (MCMC). This approach is implemented in the :BayesInference: class.

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

class pypsignifit.psignidata.BootstrapInference(data, sample=False, cuts=(0.25, 0.5, 0.75), conf=(0.025, 0.975), plotprm=None, **kwargs)

Set up an object of bootstrapped data

Parameters:

data :

an array or a list of lists containing stimulus intensities in the first column, number of correct responses (nAFC) or number of YES- responses in the second column, and number of trials in the third column. Each row should correspond to one experimental block. In addition, the sequence of the rows is taken as the sequence of data aquisition. Alternatively, the relative frequencies of correct responses resp YES responses can be given.

sample :

if sample is True, bootstrap samples are drawn. If sample is an integer, it gives the number of samples that are drawn

sigmoid :

shape of the sigmoid function. Valid choices are

• ‘logistic’ [Default]
• ‘gauss’
• ‘gumbel_l’
• ‘gumbel_r’
• ‘exp’

core :

term inside the sigmoid function. Valid choices are

• ‘ab’ (x-a)/b [Default]
• ‘mw%g’ midpoint and width
• ‘linear’ a+b*x
• ‘log’ a+b*log(x)
• ‘weibull’ 2*s*m*(log(x)-log(m))/log(2) + log(log(2)) This will give you a weibull if combined with the gumbel_l sigmoid and a reverse weibull if combined with the gumbel_r sigmoid.
• ‘poly’ (x/a)**b Will give you a weibull if combined with an exp sigmoid

priors :

a list of prior names. Valid choices are

• ‘Uniform(%g,%g)’ Uniform distribution on an interval
• ‘Gauss(%g,%g)’ Gaussian distribution with mean and standard deviation
• ‘Beta(%g,%g)’ Beta distribution
• ‘Gamma(%g,%g)’ Gamma distribution
• ‘nGamma(%g,%g)’ Gamma distribution on the negative axis

If no valid prior is selected, the parameter remains unconstrained. Alternatively, priors can be given as a dictionary that only specifies priors for those parameters you want to set in that case you can use ‘a’,’b’,’m’,’w’,’guess’,’gamma’,’lapse’,’lambda’ as keys.

nafc :

number of response alternatives. If nafc==1, this indicates a Yes/No task

cuts :

performance values that should be considered ‘thresholds’. This means that a ‘cut’ of 0.5 corresponds to an expected performance of roughly 75%% correct in a 2AFC task.

conf :

limits of confidence intervals. The default gives 95%% confidence intervals. Any other sequence can be used alternatively. In addition, conf can be ‘v1.0’ to give the default values of the classical psignifit version (i.e. .023,.159,.841,.977, corresponding to -2,-1,1,2 standard deviations for a gaussian).

parametric :

a boolean indicating wether or not parametric bootstrap should be used

plotprm :

a dictionary to take parameters for plotting data. Currently supported are the arguments ‘label’, ‘color’, ‘linestyle’, ‘linewidth’ and ‘marker’. These can all be set after creating an Inference instance, too. By using the respective properties.

gammaislambda :

constrain guessing and lapsing rate to have the same values

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])

getCI(cut, conf=None, thres_or_slope='thres')

Determine the confidence interval of a cut

Parameters:

cut :

index(!) of the cut of interest

conf :

levels of confidence (default, levels taken from the object)

thres_or_slope :

determine confidence intervals for threshold or for slope

inference

Type of inference performed by the object

infl

A boolean vector indicating whether a block should be considered an influential observation

mcRkd

A vector of correlations between block index and deviance residuals in all bootstrap samples

mcRpd

A vector of correlations between model prections and deviance residuals in all bootstrap samples

mcdensity

A gaussian kernel density estimate of the joint density of the first two parameters of the model

mcdeviance

A vector of bootstrapped deviances

mcestimates

An array of bootstrap estimates of the fitted paramters

mcslope

Slopes of the bootstrap replications

mcthres

Thresholds of the bootstrap replications

nsamples

number of bootstrap samples (setting this attribute results in resampling!!!)

outl

A boolean vector indicating whether a block should be considered an outlier

sample(Nsamples=2000)

Draw bootstrap samples

Parameters:

Nsamples :

number of bootstrapsamples to be drawn

sample_nonparametric(Nsamples=2000)

Draw nonparametric bootstrap samples

Parameters:

Nsamples :

number of bootstrapsamples to be drawn

sensitivity_analysis(conf=0.95, Nsamples=2000, Npoints=8, verbose=True)

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:

conf :

desired confidence. Note that this is the “width” of the confidence interval, not the edges. This is necessary because sensitivity_analysis is used to expand the widths of the confidence intervals. It is ambiguous how percentiles of the bootstrap distribution would be modified by sensitivity_analysis.

Nsamples :

number of bootstrap samples per data point

Npoints :

number of points on the contour at which to perform a new bootstrap run

Output:

expandedCI:

an array of expanded confidence intervals

expansionPoints:

an array of coordinates of the points at which additional bootstrap samples were drawn

class pypsignifit.psignidata.BayesInference(data, sample=True, cuts=(0.25, 0.5, 0.75), conf=(0.025, 0.975), automatic=True, resample=False, plotprm=None, sampler='metropolis', **kwargs)

Bayesian Inference for psychometric functions using MCMC

Parameters:

data :

an array or a list of lists containing stimulus intensities in the first column, number of correct responses (nAFC) or number of YES- responses in the second column, and number of trials in the third column. Each row should correspond to one experimental block. In addition, the sequence of the rows is taken as the sequence of data aquisition.

sample :

if sample is True, bootstrap samples are drawn. If sample is an integer, it gives the number of samples that are drawn

sigmoid :

shape of the sigmoid function. Valid choices are

• ‘logistic’ [Default]
• ‘gauss’
• ‘gumbel_l’
• ‘gumbel_r’
• ‘exp’

core :

term inside the sigmoid function. Valid choices are

• ‘ab’ (x-a)/b [Default]
• ‘mw%g’ midpoint and width
• ‘linear’ a+b*x
• ‘log’ a+b*log(x)
• ‘weibull’ 2*s*m*(log(x)-log(m))/log(2) + log(log(2)) This will give you a weibull if combined with the gumbel_l sigmoid and a reverse weibull if combined with the gumbel_r sigmoid.
• ‘poly’ (x/a)**b Will give you a weibull if combined with an exp sigmoid

priors :

a list of prior names. Valid choices are

• ‘Uniform(%g,%g)’ Uniform distribution on an interval
• ‘Gauss(%g,%g)’ Gaussian distribution with mean and standard deviation
• ‘Beta(%g,%g)’ Beta distribution
• ‘Gamma(%g,%g)’ Gamma distribution
• ‘nGamma(%g,%g)’ Gamma distribution on the negative axis

If no valid prior is selected, the parameter remains unconstrained. Alternatively, priors can be given as a dictionary that only specifies priors for those parameters you want to set in that case you can use ‘a’,’b’,’m’,’w’,’guess’,’gamma’,’lapse’,’lambda’ as keys. Alternatively, this may be the keyword ‘Jeffreys’ to indicate that Jeffrey’s noninformative prior should be used. Note that evaluation of Jeffrey’s prior is computationally more expensive than the other priors.

nafc :

number of response alternatives. If nafc==1, this indicates a Yes/No task

cuts :

performance values that should be considered ‘thresholds’. This means that a ‘cut’ of 0.5 corresponds to an expected performance of roughly 75%% correct in a 2AFC task.

conf :

limits of confidence intervals. The default gives 95%% confidence intervals. Any other sequence can be used alternatively. In addition, conf can be ‘v1.0’ to give the default values of the classical psignifit version (i.e. .023,.159,.841,.977, corresponding to -2,-1,1,2 standard deviations for a gaussian).

automatic :

do everything automatically

resample :

if a chain is considered “bad” in terms of convergence should it automatically be resampled?

plotprm :

a dictionary to take parameters for plotting data. Currently supported are the arguments ‘label’, ‘color’, ‘linestyle’, ‘linewidth’ and ‘marker’. These can all be set after creating an Inference instance, too. By using the respective properties.

gammaislambda :

constrain guessing and lapsing rate to have the same values

verbose :

print status messages

sampler :

sampler to be used. This could be either ‘generic’ for the generic MetropolisGibbs sampler proposed by Raftery & Lewis, or ‘metropolis’ for standard metropolis sampling, or ‘independence’ for independence sampling based on the prior (or suggested prior).

stepwidths :

stepwidths for the sampler, a pilot sample, or the proposal distributions for independence sampling

maxnsamples :

limit the number of samples to this value

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])

DIC

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.

Rhat(parameter=0)

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(quantity='deviance')

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:

quantity :

This is the quantity do be derived. By default only deviance, Rpd and Rkd are available. If quantity is a function, this will be called on every data set and the respective p value will be calculated. The call on every data set takes two arguments: 1. a nblocksX3 array of data and 2. a parameter vector. This way any other transformation of the data can be realized.

Output:

the bayesian p-value

burnin

Burnin: Number of samples to be discarded at the beginning of each chain

deviance

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.

drawposteriorexamples(ax=None, Nsamples=20)

plots the mean estimate of the psychometric function and a number of samples from the posterior

Parameters:

ax :

axes object in which to draw the plot. If this is None, a new axes object is created.

Nsamples :

number of psychometric functions that should be drawn from the posterior

estimate

Estimate of the parameters.

If sampling has already occurred, this will be the mean estimate, otherwise it will be the mapestimate.

evidence

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(D|theta)

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”.

farstart

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.

getCI(cut=None, conf=(0.025, 0.5, 0.975), param='thres')

Get a posterior credibility interval for a particular parameter

Parameters:

conf :

percentiles that should be returned

param :

parameter of interest. Currently, only thres/threshold and Rkd,Rpd,deviance are defined.

getmcdeviance(chain=None, raw=False)

Get samples from the posterior distribution of deviances

Parameters:

chain :

if chain is None, the samples are combined across all chains sampled so far. If chain is an integer, it is interpreted as the index of the chain to be returned

raw :

is true if deviances for all samples are to be returned (not respecting burnin and thinning). This only has an effect for single chains.

Output:

an array of samples from the posterior distribution of deviances. This array respects the burnin and thin settings.

getppRkd(chain=None, raw=False)

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:

chain :

chain index to be returned. If this is None (the default) all chains are combined.

raw :

if only a single chain is returned, it might be interesting to see the whole chain and ignore burnin and thinning. If raw==True, the chain is requested in this “raw” format.

Output:

an array of nsamples deviances

getppRpd(chain=None, raw=False)

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:

chain :

chain index to be returned. If this is None (the default) all chains are combined.

raw :

if only a single chain is returned, it might be interesting to see the whole chain and ignore burnin and thinning. If raw==True, the chain is requested in this “raw” format.

Output:

an array of nsamples deviances

getppdata(chain=None, raw=False)

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:

chain :

chain for which posterior predictive data should be returned

raw :

is true if all data (not respecting burnin and thinning) are to be returned (this only has an effect for single chains!)

Output:

a array of nsamplesXncorrect predicted data

getppdeviance(chain=None, raw=False)

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:

chain :

chain index to be returned. If this is None (the default) all chains are combined.

raw :

if only a single chain is returned, it might be interesting to see the whole chain and ignore burnin and thinning. If raw==True, the chain is requested in this “raw” format.

Output:

an array of nsamples deviances

getsamples(chain=None, raw=False)

Get sampes from the posterior

Parameters:

chain :

if chain is None, samples are aggregated over all chains sampled so far. If chain is an integer only data from the chain indexed by this number are returned

raw :

if True return all samples, including burnin

Output:

an array of nsamplesXnparams samples from the posterior

geweke(parameter=0, nsegments=10)

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:

parameter :

parameter of interest

nsegments :

number of subaverages to be calculated

Output:

a boolean value indicating whether the chain is “good” or “bad”

inference

Type of inference performed by the object

mcRkd

Monte Carlo samples of posterior correlation between bock index and data

mcRpd

Monte Carlo samples of posterior correlation between model predictions and data

mcdeviance

Deviances of monte carlo samples from the posterior

mcestimates

Monte Carlo samples from the posterior distribution of parameters

mcslope

Monte Carlo Samples from the posterior distribution of slopes

mcthres

Monte Carlo Samples from the posterior distribution of thresholds

nchains

Number of chains that have been sampled

nullevidence

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.

pD

effective number of parameters

posterior_median

Median for the posterior, for all sampled chains.

posterior_predictive

Posterior predictive data associated with the MCMC samples

ppRkd

Correlations between block index and deviance residuals associated with posterior predictive data

ppRpd

Correlations between psychometric function and deviance residuals associated with posterior predictive data

ppdeviance

Deviances associated with the posterior predictive data

resample(chain, Nsamples=None, start=None)

Replace a chain

Parameters:

chain :

index of the chain to be replaced

Nsamples :

number of posterior samples to be drawn. Default is to take the same number of samples

start :

starting value for the chain. Default is to take the same starting value as for the previous chain. If an integer is given as the starting value, this will be interpreted as the position of the old chain at which the new starting value can be found.

sample(Nsamples=None, start=None)

Draw samples from the posterior distribution using MCMC

Parameters:

Nsamples :

number of samples that should be drawn from the posterior. If Nsamples is None, an optimal number of samples is tried to obtain.

start :

starting value of the chain. If this is None, the chain starts at the MAP estimate. However, if you sample multiple chains, you might want to start from different (overdispersed) starting values to diagnose convergence

thin

Thinning: Subsample chains to reduce autocorrelation

Diagnostic Plots

Default functions

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

pypsignifit.psigniplot.GoodnessOfFit(InferenceObject, warn=True)

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.

2. A histogram to approximate the posterior resp. bootstrap distribution of deviances. For BootstrapInference objects this histogram provides important information. It estimates the distribution of deviance that would be expected if the fitted model were perfectly valid. If the deviance of the fitted model is far in the tails of the deviance histogram, this typically indicates a bad fit. In that case, a warning is displayed if warn==True.
3. A plot of model predictions against deviance residuals. If there is no obvious interrelation between model prediction and deviance residuals, this indicates that the model describes the data reasonably well. To get an idea of the interrelation between model prediction and deviance residuals, the best fitting line is plotted as a dotted line.
4. A histogram of samples from the posterior resp. bootstrap distribution of correlations between model prediction and deviance residuals. The interpretation of this histogram differs for BootstrapInference and for BayesInference. For BayesInference the distibution should include 0. If the distribution is clearly shifted away from 0, this is strong evidence, that something is wrong with your model or your data. For BootstrapInference, The distribution shown corresponds to the distribution that would be expected if your fitted psychometric function would perfectly describe the data. Thus, if the maximum likelihood estimate (the vertical bold red line) is in the extremes of the distribution, this is strong evidence, that something is wrong with your model or your data.

5,6 Similar to 3 and 4 but form correlations between block index and deviance residuals.

Correlations between block index and deviance residuals indicate nonstationary data as should be found during e.g. perceptual learning.

Parameters:

warn :

if warn is set to True, red warning messages are displayed whenever the fit does not seem to describe the data well.

pypsignifit.psigniplot.ConvergenceMCMC(BayesInferenceObject, parameter=0, warn=True)

Diagram to check convergence of MCMC chains for a single parameter

Parameters:

BayesInferenceObject :

a BayesInference object containing all information about the model and the posterior distribution

parameter :

model parameter of interest. So far, no model derived parameters such as thresholds are supported

warn :

should warnings be displayed if the samples look suspicious?

pypsignifit.psigniplot.ParameterPlot(InferenceObject)

Show distributions and estimates for all parameters in the model

Parameters:

InferenceObject :

a BootstrapInference or BayesInference object containing the desired data

pypsignifit.psigniplot.ThresholdPlot(InferenceObject)

Show distributions and estimates for all thresholds

Parameters:

InferenceObject

a BootstrapInference or BayesInference object containing the desired data

pypsignifit.psigniplot.plotSensitivity(BootstrapInferenceObject, ax=None)

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:

BootstrapInferenceObject :

Inference object to be analyzed

ax :

pylab axes that should be used for plotting

pypsignifit.psigniplot.plotInfluential(InferenceObject)

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 Kullbach-Leibler divergence of the posterior for the full data set from the posterior for the reduced data set.

Parameters:

InferenceObject :

Data set for which the influential observations are to be plotted

pypsignifit.psigniplot.plotMultiplePMFs(*InferenceObjects, **kwargs)

Plot multiple psychometric functions

Parameters:

InferenceObjects :

The Inference Objects that should be plotted. If the inference objects contain information about themselves, this information is used.

ax :

the axis object where the plot should go

xlabel :

text to be written on the y axis

ylabel :

text to be written on the x axis

ci :

boolean indicating whether credibility intervals should be drawn by default, this is False

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 )

pypsignifit.psigniplot.plotJoint(InferenceObject)

Plot joint distribution of parameters

For ASIRInference objects, also the fitted marginals are shown

Subfunctions

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

pypsignifit.psigniplot.drawaxes(ax, xtics=None, xfmt=None, ytics=None, yfmt=None, xname=None, yname=None)

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:

ax :

the axes object in which the graphics should stay

xtics :

an array of x-ticks

xfmt :

format string for the x-ticks

ytics :

an array of y-ticks

yfmt :

format string for the y-ticks

xname :

label for the x-axis

yname :

label for the y-axis

pypsignifit.psigniplot.plotRd(InferenceObject, ax=None, regressor='p')

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:

InferenceObject :

a BootstrapInference or BayesInference object containing the actual inference data

ax :

an axes object where the plot should go

regressor :

plot deviance residuals against model prediction (p) or against block index (k)

pypsignifit.psigniplot.plotHistogram(simdata, observed, xname, shortname=None, ax=None, hideobserved=False, reference='bootstrap')

plot a histogram and compare observed data to it

Parameters:

simdata :

an array of monte-carlo samples of the parameter of interest

observed :

observed value of the parameter of interest (for MCMC samples, it is often reasonable to use this as the value of ‘no effect’ or something)

xname :

name of the paramter of interest

shortname :

short name of the parameter of interest

ax :

axes object defining the area where the plot should go

hideobserved :

if this is True, the observed value is not plotted

reference :

reference of the data. Could be either a string ‘bootstrap’/’bayes’ or a number against which the histogram is tested

Output:

returns a boolean value indicating whether or not the Null-Hypothesis that

observed was drawn from the same distribution as simdata is true

pypsignifit.psigniplot.plotppScatter(simdata, observed, quantity, shortname=None, ax=None)

plot a scatter diagram to compare observed and predicted data

Parameters:

simdata :

data simulated from the model (typically data from posterior predictives)

obseved :

observed data (transformed in the same way as the posterior predictives)

quantity :

name of the quantity that is checked

shortname :

abbreviation of the plotted quantity

ax :

pylab axes object where the plot should go.

pypsignifit.psigniplot.plotPMF(InferenceObject, xlabel_text='Stimulus intensity', ylabel_text=None, ax=None, showaxes=True, showdesc=False, **kwargs)

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 y-axis.

Parameters:

ax :

axes object in which the plot should go (default: current)

xlabel_text :

label for the x-axis

ylabel_text :

label for the y-axis, if this is None, the functions determines the correct label from its internal knowledge about the task

showaxes :

if this is set to False, no axes will be drawn

showdesc :

if this is set to False, no convergence description is drawn

Return:

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

the matplotlib.lines.Line2D object representing the fitted curve

points :

the matplotlib.collections.CircleCollection object representing the fitted data points

lims :

limits of the drawn x axis.

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.

pypsignifit.psigniplot.plotThres(InferenceObject, ax=None, color='b')

Plot thresholds and confidence intervals

Parameters:

InferenceObject :

either a BootstrapInference object or a BayesInference object

ax :

a pylab.axes object to be used for the plot.

color :

a pylab color marker

pypsignifit.psigniplot.plotGeweke(BayesInferenceObject, parameter=0, ax=None, warn=True)

Geweke plot of moving average of samples

Parameters:

BayesInferenceObject :

a BayesInference object that contains all the infromation about the sampling process

parameter :

index of the model parameter of interest

ax :

the pylab.axes object where the plot should go

warn :

should a warning message be displayed if non stationarity of the samples is observed?

pypsignifit.psigniplot.plotChains(BayesInferenceObject, parameter=0, ax=None, raw=False, warn=True)

Simply plot all chains for a single parameter

Parameters:

parameter :

index of the model parameter to plot

raw :

plot raw samples instead of thinned samples after burnin

ax :

axes in which to print

warn :

if True, warnings are written into the plot

pypsignifit.psigniplot.plotParameterDist(InferenceObject, parameter=0, ax=None)

Plot the distribution of parameters

Parameters:

InferenceObject :

either a BootstrapInference object or a BayesInference object containing the samples of the parameter distribtution

parameter :

index of the model parameter of interest

ax :

pylab.axes object where the plot should go

Simulated Observers

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

class pypsignifit.psigobservers.Observer(*params, **model)

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:

params :

a list of parameters in the model. For nAFC tasks the parameters are a,b,lapse for a Yes/No task the parameters are a,b,lapse,guess

model :

a list of keyword arguments specifying the model. These are the same as in the psignidata module

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)

DoABlock(stimulus_intensity=1, ntrials=50)

Simulate a block of trials

Parameters:

stimulus_intensity :

stimulus intensity to be presented

ntrials :

number of trials in the block

Output:

The number of Yes-responses (in Yes/No) or the number of correct responses (nAFC)

DoATrial(stimulus_intensity=1)

Simulate a single trial

Parameters:

stimulus_intensity :

stimulus intensity to be presented

Output:

The response in the trail (1/0 coding for Yes/No in Yes/No-Tasks or for Correct/Incorrect in nAFC tasks)

DoAnExperiment(stimulus_intensities, ntrials=50)

Simulate a whole experiment

Parameters:

stimulus_intensities :

a sequence of stimulus intensities in the order they should be presented

ntrials :

Either an integer or a sequence. If this is an integer, it is interpreted as a constant number of trials that is presented in each trial, otherwise, the sequence is expected to contain a number of trials for each trials.

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(stimulus_intensities)

Evaluate the psychometric function

Parameters:

stimulus_intensities :

stimulus intensities at which the psychometric function should be evaluated.

getlevels(cuts)

Determine stimulus levels that correspond to predefinde levels of performance

params

parameters of the model

seed(seed)

Seed the underlying random number generator to a defined value

thres

determine 50%% of the model

class pypsignifit.psigobservers.LinearSystemLearner(*params, **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 -= (a-3)/4

Parameters:

params :

parameters of the model a, b, lapse and in Yes/No tasks also guess. In addition, a dictionary is required to describe the changes of the parameters (see above)

model :

a list of keyword arguments to describe the model. These are the same as in the psignidata module.

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

DoABlock(stimulus_intensity=1, ntrials=50)

Simulate a block of trials with learning

Parameters:

stimulus_intenstiy :

intensity of the presented stimulus

ntrials :

number of repetitions of the stimulus

Output:

the number of Yes-responses in a Yes/No-task or the number of correct responses in nAFC

DoATrial(stimulus_intensity=1)

Simulate a single trial with learning

Parameters:

stimulus_intensity :

intensity of the presented stimulus

Output:

either 1 or 0 indicating Yes/No in Yes/No-Tasks or Correct/Incorrect in nAFC

class pypsignifit.psigobservers.CriterionSettingObserver(*params, **model)

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:

1. stabilization : The criterion is moved into the direction of new incoming stimuli. This

   results in the criterion being placed roughly in the middle of the stimulus stream. Thus, stabilization can be said to maximize information transmission.

2. tracking : The criterion is placed in a direction that increases repetitions of the same

   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:

params :

a,b,lapse parameters of the psychometric function describing the interrelation between

stimulus intensity and sensitivity (where sensitivity is given in fraction of correct responses in 2AFC).

E0 the reference criterion, i.e. Ec(0) := E0 Ds,ds parameters of the stabilization mechanism Dr,dr parameters of the tracking mechanism

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)

DoABlock(stimulus_intensity=1, ntrials=50, nAFC=2)

Simulate a whole block of trials with criterion setting

Parameters:

stimulus_intensity :

intensity of the stimulus presented

ntrials :

number of trials in the block

nAFC :

number of alternatives presented / task to be performed. - nAFC in {0,1,-1} Yes/No task, stimulus presence is random. - nAFC>1 nAFC task, number of alternatives

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)

DoATrial(stimulus_intensity=1, nAFC=2)

Simulate a single trial with criterion setting

Parameters:

stimulus_intensity :

intensity of the stimulus the is presented

nAFC :

number of alternatives presented / task to be performed. - nAFC=-1 Yes/No task, stimulus presence is random. - nAFC=0 Yes/No task, noise only trial - nAFC=1 Yes/No task, signal+noise trial - nAFC>1 nAFC task, number of alternatives

Output:

A number 1 or 0, depending on the task, this means correct/incorrect (nAFC) or signal present, signal absent (Yes/No)

class pypsignifit.psigobservers.BetaBinomialObserver(*params, **model)

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 p-value is then used to generate the responses of that block.

Parameters:

params :

a,b,lapse(,guess) are parameters for the classical psychometric function, m gives the dispersion of the Beta distribution. For a Beta distribution with parameters alpha and beta, m=alpha+beta

model :

a list of keywords to further specify the model

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]]

DoABlock(stimulus_intensity=1, ntrials=50)

Perform a block of trials

Parameters:

stimulus_intensity :

intensity of the presented stimulus

ntrials :

number of trials in the block

Output:

number of correct responses (nAFC) or number of yes responses (Yes/No-Task)

Errors

exception pypsignifit.psignierrors.NosamplesError(msg)

An exception that is raised whenever we try to use samples but there are none

exception pypsignifit.psignierrors.SamplingError(msg)

An exception that is raised if some thing is wrong with the sampling