% 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 <stimuli,responses> 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 <stim,resp> 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

