Matlab Utilities


utils-v1.1.1-2008-02-22.zip (194KB) Readme License

This archive contains Matlab, software supporting the day-to-day work of a cognitive modeler with an interest in psychophysics and statistics. This is version 1.1.1, released 2008-02-22. The particular subfolders, or "toolboxes" included in this release are:

Most of these contain just a few one-line functions, but they can enhance one's productivity considerably. There are also some non-trivial algorithms, such as locally weighted regression. Each toolbox has its own Contents.m file -- go there for details.

All functions are simple .m files that should work on any version of Matlab under any operating system. Some utilities depend on the Matlab's Statistics, Image, and Optimization Toolboxes. The MovieStruct functions in the image-processing toolbox above are designed to work with the rush utility in PsychToolbox-2 for Mac OS9.

To install, simply unzip the archive in a directory of your choice and execute the install_utils script to add the subdirectories to Matlab's path.

The software is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License and the Free Software Foundation for more details.

The software is freely available and freely redistributable, according to the conditions of the GNU General Public License. You may not distribute the software, in whole or in part, in conjunction with proprietary code. That means you only have my permission to distribute a program that uses my code if you also make freely available (under the terms of the GNU GPL) the source code for your whole project. You may not pass on the software to another party in its current form or any altered, embellished or reduced form, without acknowledging the author and including a copy of the GNU GPL.

Please notify me of any bugs, notes, comments or suggested changes, particularly of any useful changes you may have made to your own copy of the software.

Thank you for your interest in this software. I hope you find it useful.

ANOVA Toolbox -- Contents

% ANOVA Toolbox
% Version 1.0  20-Dec-2002
%
% The analysis of variance functions included in Matlab's Statistics Toolbox
% tend to do a canned analysis in a streamlined manner.  It doesn't support
% complications such as between- vs. within-subject factors and the like.
% The functions below are by no means a full-fledged ANOVA machine on a
% par with the GLIM command in SPSS, for example. Rather, they can do the
% routine calculations, but the user is still responsible for figuring out
% what the relevant error terms are, how to form the F ratios, etc.
%
% Functions:
%   anova     - SS's, df's, and MS's. You must do the F ratios yourself.
%   sumsq     - sums of squares and degrees of freedom (depends on utils/SPLIT)
%   partition - partition the SS and df in full-factorial ANOVAs
%
% Reference: Howell, D. C. (1992). Statistical Methods for Psychology.
% Type 'edit anova' and look at the example there.
%
% ANOVA1, ANOVA2, and FCDF are defined in the STATS toolbox.
% SUMSQ depends on SPLIT and AGGREG defined in the GENERAL utils toolbox.
%
%

% Original coding by Alex Petrov, Ohio State University
% $Revision: 1.0 $  $Date: 2002/12/20 $
%
% Part of the utils toolbox version 1.1 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2006, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m

ACT-R Base-Level Activation

% ACT-R Base-Level Activation Toolbox
% Version 2.0  12-Feb-2006
%
% This toolbox implements an efficient approximation to the base-level
% learning equation in the ACT-R cognitive architecture.
%
% Reference:
%  Petrov, A. (2006). Computationally Efficient Approximation of the
%  Base-Level Learning Equation in ACT-R. In D. Fum, F. Del Misser, & 
%  Stocco (Eds.), Proceedings of the Seventh International Conference on
%  Cognitive Modeling (pp. 391--392). Trieste, Italy: Edizioni Goliardiche.
%  Available on-line at http://alexpetrov.com/pub/iccm06/
%
% Main tools:
%  base_act - Exact equation, as defined by the ACT-R theory
%  B_approx - Efficient approximation, parametric depth K
%
% Miscellaneous:
%  plot_act - Plot BLA curves at different approximation depths
%  B_approx.notes.txt - Script generating the figures in Petrov (2006)
%

% Original coding by Alex Petrov, Ohio State University
% $Revision: 2.0 $  $Date: 2006/02/12 $
%
% Part of the utils toolbox version 1.1 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2006, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m

Relevant publication: Petrov (2006)

General Utilities -- Contents

% General Utilities Toolbox
% Version 1.3  2006/06/06
%
% This toolbox defines some one-liners that I find myself using over and over
% again. DESCR, SPLIT, and AGGREG in particular have become indispensable.
%
% Extensions to the Matlab programming language:
%   keyargin    - Utility for passing keyword arguments to M-functions.
%   pack_fields - struct array w/simple fields --> 1 struct w/complex f's
%
% Some useful mathematical functions and transforms
%   dB    - Decibel transform: dB(x) = 20*log10(x)
%   dBinv - Inverse decibel transform: dBinv(y) = 10.^(y/20)
%
% Group-based analysis:
%   split  - splits an array of data into groups
%   aggreg - apply a user-specified aggregation function to split groups
%   scatter1 - scatterplot of several color-coded groups
%
% Simple descriptive statistics:
%   descr    - Descriptive statistics (short version)
%   describe - Descriptive statistics (long version)
%   dprime   - Signal-detection theory sensitivity measure
%   acf      - Autocorrelation function.
%   argmin   - Index of the minimal element
%   argmax   - Index of the maximal element
%   harmmean - Harmonic mean
%   combine_measurements - Weighted average, unequal standard dev's
%   truncGauss - Mean and std.dev. of a truncated Gaussian variable
%
% Modeling tools:
%   prior_repetition - Time (and lag) of the most recent repeated stimulus
%   softmax  - Probabilistic temperature-dependent maximum
%   softmax1 - Specialized variant of SOFTMAX for one-dimensional data
%
% Miscellaneous:
%   fprintN  - Call FPRINTF for several files in parallel
%   work_pathstr - path string to the root of the WORK directory-tree
%   file_exists - 1 if a file with FNAME exists and 0 otherwise
%   is_col_vector - True for numeric column vectors, including scalars
%   is_row_vector - True for numeric row vectors, including scalars
%   jitter - add noise to (discrete) data to prevent overlap in plots
%   make_grid - Make a linear grid with N elements, centered on 0
%   subplotrc - put subplot in row r, column c of figure
%   wrap_around - Wrap around a circle with an arbitrary leftmost point
%

% Original coding by Alex Petrov, Ohio State University
% $Revision: 1.3 $  $Date: 2006/06/06 $
%
% Part of the utils toolbox version 1.1 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2006, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m

Image-Processing Utilities Toolbox -- Contents

% Image-Processing Utilities Toolbox
% Version 1.4  2007-12-06
%
% Some of the utilities below add a layer of abstraction around Matlab's
% FFT2 routine. Others are designed to work with PsychToolbox's RUSH
% utility (http://psychtoolbox.org/). There are also some one-liners.
%
% Gabor patches and other psychophysical displays:
%   gabor        - Sinusoidal grating under a Gaussian envelope.
%   grating      - Sinusoidal grating (grayscale image).
%   slant        - Sloping plane through the origin.
%   gabor_params - Specification of a Gabor patch or sinusoidal grating.
%
% Filtering in the frequency domain:
%   filter_img   - Filter a grayscale image in the frequency domain.
%   fftmesh      - Fx and Fy domains arranged to dovetail with FFT2.
%   filtnoise    - Gaussian noise filtered through a user-supplied filter.
%   butterworth1 - One-dimensional Butterworth lowpass filter of order 1.
%   butterworth2 - Wedge-like Butterworth lowpass filter in two dimensions.
%
% Elliptical confidence regions:
%   ellipse_points - A set of points satisfying AX^2+BXY+CY^2=1.
%   ellipse_descr  - Describe an ellipse in three equivalent ways
%   covar2ellipse  - Covariance matrix --> ellipse coefficients.
%   elliptic_CI  - Elliptic confidence region for bivariate Gaussian data.
%   chfun        - Evaluates a supplied characteristic function.
%
% Miscellaneous:
%   cart2pol2    - Transform an image from Cartesian to polar coordinates.
%   pol2cart2    - Transform an image from polar to Cartesian coordinates.
%   imagesc1     - Scale data and display as a gray image with colorbar.
%   coldhot      - Default Leabra color map  [lblue dblue grey red yellow]
%   reppix       - Replicates pixels in an image.
%   mosaic       - An image of random black and white tiles.
%
% MovieStruct movies:
%   MovieStructDemo - Demo of PsychToolbox movies and "movieStructs".
%   MakeMovieStruct - Make a movieStruct -- the skeleton of a movie.
%   LoadMovieStruct - Load images into movieStruct's off-screen buffers.
%   PlayMovieStruct - RUSHes the movie loaded in a movieStruct.
%   CloneMovieStruct - Clone a movieStruct to another location or sequence.
%   UnrollMovieLoop - Make a RUSHable string of SCREEN calls.
%
% Random-dot cinematograms (v. 2.0):
%   RDC_params      - Default params for random-dot cinematograms
%   make_RDC_spec   - Frame-by-frame specification of dot locations
%   render_RDC      - Render a RDC_spec as a 3D grayscale bitmap
%   render_RDC_deluxe - High-precision render_RDC, ~4 times slower
%   RDC_movie       - Animation of a RDC as a Matlab movie
%
% Lookup table manipulation:
%   make_linear_LUT - Calibrated LUT with equal-luminance intervals.
%   make_split_LUT  - LUT with two parts with different resolution.
%   LUT_params      - Default parameters for MAKE_xxx_LUT.
%   NewCalibrator   - Psychophysical estimation of the monitor's GAMMA.

% Original coding by Alex Petrov, Ohio State University
% $Revision: 1.4 $  $Date: 2007-12-06 $
%
% Part of the utils toolbox version 1.2 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2008, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m

Nominal Statistics Toolbox -- Contents

% Nominal Statistics Toolbox
% Version 1.2  21-Oct-2005
%
% Statistics over nominal variables -- cross-tabulations, chi-square, etc.
%
% Crosstabulations:
%   xtab1    - one-way contingency table
%   xtab2    - two-way contingency table
%   xtab     - K-way contingency table
%   print_xtab - prints one- and two-way contingency tables
%   xtab2dprime - calculate d-prime from a joint S-R distribution
%
% Measures of association:
%   chi2     - chi-square statistic for a contingency table
%   entropy  - entropy of a distribution
%   infogain - information gain
%   binomial_logL - binomial log-likelihood goodness-of-fit measure
%
% Miscellaneous:
%   recode        - arbitrary many-to-one mapping
%   factor_design - full-factorial design with optional randomization

% Original coding by Alex Petrov, Ohio State University
% $Revision: 1.2 $  $Date: 2005/10/21 $
%
% Part of the utils toolbox version 1.1 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2006, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m

Parameter Search Toolbox -- Contents

% Parameter Search Toolbox
% Version 1.2 2007-08-16
%
% This toolbox defines an interface to Matlab's Optimization Toolbox.
% The functions defined here harness the power of Matlab's optimization
% routines for the purposes of parameter search.
%
% Functions:
%   paramsearch   - Arrange a call to FMINCON over a single data set
%   big_psearch   - Call PARAMSEARCH over multiple data sets. Save the results
%   MCarlo_psearch- Monte Carlo PARAMSEARCH over many synthetic data sets
%   logL          - Negative log likelihood (the objective for minimization)
%   curvediff     - Vector of differences b/n user-supplied model and data
%   sumsqerr      - Summed squared error b/n user-supplied model and data.
%   vector2params - Convert vector to PARAMS structure via v2p_template
%   params2vector - Convert PARAMS structure to vector via p2v_template
%   sample_template - Sample implementation of MAKE_TEMPLATE
%
% The canonical problem is the following: there is some model defined
% by the user. This model converts stimuli to responses and is
% formulated in probabilistic terms. The model depends on multiple
% parameters that are passed to the model function bundled in a structure
% with arbitrary fields. The problem is, given a  pair,
% to find the parameters maximize the probability that the model will 
% produce the responses when presented with the stimuli.
%
% The functions of the Parameter Search Toolbox facilitate this process
% in two ways. First, they support easy translation of the PARAMS structure
% into a vector and vice versa. The struct notation is more readable while
% the vector notation is the one required by the optimization toolbox.
% Second, the function LOGL (log likelihood) can be used as objective
% function in FMINBND, FMINUNC, and the other optimization routines.
% Third, CURVEDIFF can be used with the LSQNONLIN routine.
%
% To use this toolbox, you must have a function that implements your model:
%   prob = your_model(stim,resp,params)
% You must also supply two "templates" -- specifications of how your custom
% PARAMS structure must be converted to vector notation and back.
% Finally, you must supply a DATA structure that bundles together all
% the data: stimuli, responses, initial PARAMS, conversion templates, etc.
% These data are passed as a second argument to the objective function LOGL.
%
% Example of a full optimization sequence for a given  data set.
% ANCHOR_MT, ANCHOR_TEMPLATE, and ANCHOR_PARAMS are the custom-made parts.
%   flags = [0 1 1 1 1 0 0] ; [p2v_templ,v2p_templ,bnd] = anchor_template ;
%   p2v_templ' , v2p_templ', bnd'
%   params0 = anchor_params ;          % default parameters for the model
%   x0 = params2vector(params0,p2v_templ) ;      % initial approximation
%   model_data = struct('stim',stim,'resp',resp,'params',params0) ;
%   data = struct('model_name','anchor2mt','model_data',model_data) ;
%   data.params = params0 ;
%   data.v2p_templ = v2p_templ ;
%   data.clip_prob = exp(-4) ;
%   optns = optimset('fmincon') ;      % stepsize, tolerances, etc.
%   opt_x = fmincon('logL',x0,[],[],[],[],bnd(1,:),bnd(2,:),[],optns,data)
%   opt_params = vector2params(opt_x,params0,v2p_templ) ;
%
% Version 1.2 also supports nonlinear least-square fitting. 
% See CURVEDIFF and LSQNONLIN. Also SUMSQERR.
%
% See also PARAMSEARCH, LOGL, PARAMS2VECTOR, SAMPLE_TEMPLATE, FMINCON.

% Original coding by Alex Petrov, Ohio State University
% $Revision: 1.2 $  $Date: 2007-08-16 $
%
% Part of the utils toolbox version 1.1 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2007, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m

Polar Graphics Utilities Toolbox -- Contents

% PolarGraph Utilities Toolbox
% Version 1.0  02-Dec-2004
%
% Image transformations:
%   cart2pol2    - Transform an image from Cartesian to polar coordinates.
%   pol2cart2    - Transform an image from polar to Cartesian coordinates.
%   cobweb       - Create a matrix depicting a polar coordinate grid.
%
% Spectral diagrams:
%   spectral_diag        - Diagram of a Fourier power spectrum.
%   spectral_diag_params - Spectral diagram parameters.
%

% Original coding by Alex Petrov, Ohio State University
% $Revision: 1.0 $  $Date: 2004/12/02 16:30 $
%
% Part of the utils toolbox version 1.1 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2006, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m

Regression Utilities Toolbox -- Contents

% Regression Utilities Toolbox
% Version 1.0  21-Oct-2005
%
% Linear regression:
%   regcoefs - Linear regression coefficients (after studentizing outliers)
%   R2signif - Significance test for hierarchical multiple regression
%
% Locally weighted regression:
%   lwreg1     -  Locally weighted regression in one dimension
%   cverr_lwr1 -  Cross-validation error for locally weighted regression
%   localreg   - Smooth data via local regression in a sliding window
%
% Miscellaneous:
%   shiftmat - Matrix of shifting indices. Useful for moving averages.
%   ridgemat - A "ridge" matrix. Used with cross-tabulation tables.
%

% Original coding by Alex Petrov, Ohio State University
% $Revision: 1.0 $  $Date: 2005/10/21 11:57 $
%
% Part of the utils toolbox version 1.1 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2006, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m

Subject-Database Toolbox -- Contents

% Subject-Database Toolbox
% Version 1.1  11-Mar-2005
%
% The functions below support a simple database for keeping track of
% which subject belongs to which group in a psychological experiment, 
% how many sessions each has had so far, what conditions to run next, etc.
%
% The 'database' is simply a structure array, with one entry per subject:
%   new_sbj_descr  - Makes a brand new subject-descriptor structure.
%   find_sbj_descr - Look for a particular participant in the database.
%
% File operations:
%   open_sbj_database   - Reads 'subject descriptor' structures from file.
%   save_sbj_database   - Writes 'subject descriptor' structures to file.
%   update_sbj_database - Updates 'subject descriptor' structures.

% Original coding by Alex Petrov, Ohio State University
% $Revision: 1.1 $  $Date: 2005/03/11 12:40 $
%
% Part of the utils toolbox version 1.1 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2006, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m
http://alexpetrov.com/softw/utils/ Check the validity of this page's XHTML Check the validity of this site's Cascading Style Sheet Page maintained by Alex Petrov
Created 2005-10-23, last updated 2008-02-22.