Psignifit FAQs

To submit a question, mail this address.

General

  • What is psignifit?
  • How do I pronounce "psignifit"?
  • Who wrote psignifit?
  • If I have used psignifit in my analysis, how should I cite it in my report?

Problems

  • How do I expand these .zip/.sit/.tar.gz archives?
  • The engine won't compile, or the compiled engine fails its self-test
  • There's this error message...
  • I'm not going to send you enough information to reproduce the error, but something somewhere is not working. Can you guess why?

Application

  • What is the best way of testing the differences between two psychometric functions?

Extending and Customizing

  • How do I change the default options in the Matlab function PFIT?
  • Is it possible to implement the <insert name> psychometric function instead of the logistic, Weibull, etc?

General

  • What is psignifit?
    psignifit is a free software package for fitting psychometric functions to psychophysical data. See the introduction page for more details.

  • How do I pronounce "psignifit"?
    Any way you like. Personally, I say "SIG-ni-fit": silent p as in psychophyics, stressed sig to emphasize significance testing, and fit like a glove.

  • Who wrote psignifit?
    I did.

  • If I have used psignifit in my analysis, how should I cite it in my report?

    This is, of course, up to you. If you just use psignifit for fitting, I suggest something similar to the following:
     

    Psychometric functions were fitted using psignifit version 2.5.6, a software package which implements the maximum-likelihood method described by Wichmann and Hill (2001a).
     

    ...or:

    Psychometric functions were fitted using the psignifit toolbox version 2.5.6 for Matlab which implements the maximum-likelihood method described by Wichmann and Hill (2001a).
     

    ...depending on whether or not you used psignifit under Matlab. In addition, if confidence intervals are reported, it would be as well to say something like:
     

    Confidence intervals were found by the <xxx> bootstrap method implemented by psignifit, based on <nnn> simulations (see Wichmann and Hill, 2001b).
     

    ...where <xxx> is "BCa", "expanded BCa" or "percentile", depending on the type of bootstrap confidence interval reported, and <nnn> is the number of bootstrap replications used.
     

    See the publications page for full citations of Wichmann and Hill 2001a and 2001b.

Problems

  • How do I expand these .zip/.sit/.tar.gz archives?

    For simplicity, where a binary release is specifically intended for Windows, I have packed it as a .zip archive. They should expand under most decompression programs, including WinZip whose code is now, I believe, integrated into the WindowsXP system.
     

    Other archives have been packed as .tar.gz archives, for maximum portability between platforms.

     
    Note that, if it's the source code archive you're after, the easiest way to compile the source is going to be with Cygwin in any case. Since Cygwin provides a UNIX-like shell, it naturally comes with all the usual tools such as tar and gzip. So, to expand a .tar.gz archive from the Cygwin prompt, type (for example):
     

    	tar xfz psignifit-2-5-6-src.tar.gz

    Finally, .sit files are a proprietary standard from Aladdin Systems, which I only use because it is the easiest way of compressing a Mac file while simultaneously retaining the annoying "resource-fork" information that MacOS Classic applications need. The decompressor is called Stuffit Expander - it is available for free and should also come with the MacOS system installation these days. It is, incidentally, also available for Windows, Linux and Solaris, and handles almost every other conceivable format (.zip, .gz, etc...) It's good in that it expands archives without any fuss (i.e. without pestering you with "wizards" that make the expansion process look more complicated than it need be). Its expansion of .tar files, at least under Windows, seems to require one slight bit of fiddling, however.
     

  • The engine won't compile, or the compiled engine fails its self-test
    Check for a ready-made binary for your platform on the download page. See the notes on compiling for help with compiling the engine yourself - not all compilers will yield the desired results.

  • There's this error message...

    You're using the compiled psignifit engine either as a Matlab "mex" file or as a standalone executable, and it has given you an error message. There are two types of event that cause the engine to issue an error message:

    • Internal bugs in the engine itself: due to faulty source code a non-sensical condition has arisen, and one of the engine's internal checks has trapped it. These errors are nearly always heralded by a big notice asking you to report the bug. Please do so - this will enable me to improve the software as time goes by. Other (hopefully even rarer) internal errors might not be trapped at all, and might cause a "Segmentation fault" message from Matlab or from the bash prompt, or an "illegal operation" message from Windows. Please report these errors too.
    • Messages to the user. If there is no message asking you to report a bug, then it is unlikely (though, of course, still possible) that the engine is at fault: read the error message that came from psignifit carefully (it may be stacked up on top of a bunch of Matlab "backtrace" messages) and consult the documentation that came either in the help comments of the Matlab toolbox, or in text files that came packaged with the standalone. If the message is still unclear, I may be able to offer some (limited) support.

    When reporting errors or problems of any sort, bear in mind that if I cannot reproduce the error, I will not be able to explain or fix it. So, make sure you send:
    • a copy of the complete text of the error message;
    • details of which platform you are using, (and whether you are using Cygwin or not, in the case of Windows), and which version of Matlab you have, if appropriate;
    • the complete input conditions (data set and options) that led to the error.
       
    Always check that your mex-file/standalone has compiled correctly by calling psignifit with the -t switch on the command line (or at the beginning of the prefs file, for MacOS Classic users.) If the self-test procedure does not end with ***success*** then read the message through to see what has happened. Either check the download pages for ready-compiled versions for your platform, or consult the notes on compiling for advice.
     
  • I'm not going to send you enough information to reproduce the error, but something somewhere is not working. Can you guess why?
    No.

Application

  • What is the best way of testing the differences between two psychometric functions?

    One way is to use a bootstrap method, as implemented in psignifit, to get error bars on the threshold and slope for each of the two conditions, and then to make an informal judgment based on whether the error-bars overlap. Perhaps a more satisfying way would be to do Monte Carlo simulation of the distribution of threshold and slope differences, and to test simultaneously the observed differences in threshold and in slope, based on a null-hypothesis that the two data sets in fact came from the same underlying psychometric function.
     

    I have put together, in a provisional sort of way, the Matlab m-files that I use for this process, an released it under the name pfcmp. The pfcmp release runs (in theory) on Matlab 5.2 and up, and requires the psignifit toolbox to be installed already. It can be downloaded from the download page.
     

    This approach circumvents many of the problems associated with bootstrap methods (it is not actually a bootstrap, but rather a direct Monte Carlo test of a given null-hypothesis). However, it is not without complications of its own. For more details, read the documentation in pfcmp.m by typing help pfcmp.
     

    Test it out by just typing pfcmp and watching the demo (simulations may take a few seconds).

Extending and Customizing

  • How do I change the default options in the Matlab function PFIT?

    Depending on the application, people will use the psignifit software in different ways, but each user will probably stick to a similar set of options (for instance, always using the Weibull function, always with a certain prior on lambda, always computing slopes with respect to log10 x, etc).
     

    It is strongly recommended that you do not edit the m-files of the psignifit toolbox to install your default options, or for any other reason: this is simply because it is a non-modular form of development, and it will only require you to do the work over again if you ever download a future version of the toolbox. For the same reason, do not add files to the psignifit toolbox directory (or for that matter any other toolbox directory). Instead, keep your own code in your own directory and add that directory to the Matlab path (for experienced Matlab users this may seem an obvious thing to say - for others perhaps less so).
     

    Instead, you can add your own defaults by creating a "wrapper" function (in a separate directory), such as the following example:
     

    function [s, sFull, str] = myfit(dat, varargin)

    MYFIT: example of personalized wrapper around PFIT
    (N.B. change the name MYFIT to something more informative!)
     
    Personalized default options (listed in the m-file), are used with syntax:
    s = myfit(dat);
     
    Options can be added/overridden by specifying further arguments, e.g:
    s = myfit(dat, 'shape', 'logistic', 'sens', '0', 'plot_opt', 'plot');
     
    defaultOpts = { % list your preferred defaults here, for example:
    'shape' 'weibull'
    'n_intervals' '2'
    'slope_opt' 'log'
    'runs' '1999'
    'verbose' 'false'
    'lambda_prior' '-g [0, 0.02]'
    }'; % note the tick to transpose the cell array - this is vital

    [s sFull str] = pfit(dat, defaultOpts{:}, varargin{:});

  • Is it possible to implement the <insert name> psychometric function instead of the logistic, Weibull, etc?
    If you want to add a new psychometric function shape to the psignifit engine, it needs to be written in C and added to Psychometric.c before the engine (mex-file) is compiled. The function should follow the conventions laid down in the other functions from that file: if you look at, for example, JLogistic, you'll note that the function can operate in several different modes and has to be able to return derivatives, inverses and slopes, among other information. Once you've written it, you have to add your function to the list of recognized function names in PsychoPrefs.c:
     
    In the function MatchShape, there are two definitions that need to be changed:

    #define kNumberOfShapes 5
    PsychDistribFuncPtr matched = NULL, possible[kNumberOfShapes] =
    {JCumulativeGaussian, JGumbel, JLogistic, JWeibull, JLinear};

     
    Add your new function name to the list, and increment kNumberOfShapes accordingly. Then you need to re-compile the engine (lucky you).
     

    That would allow you to use the engine to fit and bootstrap with your new function. You would also have to make (similar, but somewhat simpler) additions to psychf.m in order for the Matlab toolbox to plot your function in the normal way.