% Iain Murray's "Toolbox" of mostly simple utility functions for Matlab/Octave
% http://www.cs.toronto.edu/~murray/
%
% Nov 2007 - Started collection
% Jul 2008 - Minor tweaks and documentation cleanup for release
%
% Many of these functions I use a lot. Others just seemed fairly generic, so
% were worth maintaining separately from any particular project.
%
% First and foremost, use this command:
%   addgenpath       - like addpath(genpath(.)), but strips out some
%                      subdirectories used for version control, testing and so
%                      on. I use this function to include this "toolbox", which
%                      may not work properly if you don't!
%
% I have loosely classified the remainder of the commands, but they are a real
% mix of stuff:
%
% Black-box routine helper:
%   arg_wrappers     - returns functions to transform an argument list into a
%                      single column vector and back again. Useful for glueing
%                      together application-specific code and black-box
%                      optimizers. Used in minimize_args below.
%
%
% Gradient-based optimization helpers:
%   minimize_args    - use Carl Rasmussen's minimize on multiple array variables
%   penalize_square  - regularize a cost function for use in minimize_args
%   utility_to_cost  - reverse sign on a function to maximize using minimize_args
%   var_checkgrad    - Checks partial derivatives wrt a whole argument list
%
%   Example usage: maximize utility_fn(arg1, arg2, data) wrt arg1 and arg2, with
%   different penalties on the square length of scalar arg1 and length-2 column
%   vector arg2. Initial conditions are given by init1 and init2:
%       % curry in fixed params
%       u_fn = @(arg1, arg2) utility_fn(arg1, arg2, data);
%       % Always check gradients (after every code change), or hair loss results!
%       err = var_checkgrad(u_fn, 1e-6, init1, init2);
%       assert(max(err) < 1e-5);
%       % Create a function that should be minimized rather than maximized
%       cost_fn = utility_to_cost(u_fn);
%       % Create regularized version:
%       regularized_cost_fn = penalize_square(cost_fn, {1, [10;100]});
%       % And optimize it
%       [opt_arg1, opt_arg2, opt_value] = minimize_args(regularized_cost_fn, ...
%               -100, init1, init2);
%
%   Note that Carl Rasmussen's minimize.m is available from:
%       http://www.kyb.tuebingen.mpg.de/bs/people/carl/code/minimize/
%       http://www.gaussianprocess.org/gpml/code/matlab/doc/
%
%
% Random number generation:
%   discreternd      - draw samples from a discrete probability distribution
%
%
% Indexing:
%   ind2subv         - return vector position of a linear index into an ND-array
%                      like ind2sub but returns subscripts in a single vector
%   subv2ind         - return linear index into an ND-array given by a vector position
%                      like sub2ind but takes subscripts in a single vector
%
%
% Vectorized versions of standard processing tasks:
%   unique_totals    - Given (pos, value) pairs, return unique positions with
%                      the sum of the values at those positions.
%
% Standard functions:
%   h2bits           - Entropy of a Bernoulli distribution in bits
%   h2nats           - The same Binary entropy function, but in nats
%   log1pexp         - log(1+exp(x)) avoiding under and overflow (CARE)
%   logistic         - 1./(1+exp(-x))
%   logit            - log(p./(1-p)), this is the inverse of the logistic
%   plus_diag        - add a scalar or vector onto the diagonal of a matrix
%
%
% Functional-style programming utility functions:
%   celldeal         - returns elements of a cell array as output arguments
%   cellmap          - maps function over a cell array returning a cell array
%   colfun           - maps function over cols of an array returning an array
%   colmap           - maps function over cols of an array returning a cell array
%   rowfun           - maps function over rows of an array returning an array
%   rowmap           - maps function over rows of an array returning a cell array
%
% Octave only:
%
%   Reimplementations of missing Matlab routines (in ./octave directory)
%
%   histc            - histogram counts of data falling in bins defined by edges
%   log1p            - log(1+x) without underflow
%   reallog          - log(x) which raises an error if complex numbers result
%   realsqrt         - sqrt which raises an error if complex numbers result
%
% Binary operations readability:
%
%   These are a series of functions bsxOP.m that do bsxfun(@OP, x, y)
%
%   Having these wrappers makes common operations less cumbersome to read and
%   write. They were generated by the python program genbsx.py. They live in a
%   sub-directory, as there's lots of them, and they're not very interesting.
%   Both R and Python's numpy just define their standard operations to behave
%   like these bsx versions. It's unclear why Matlab makes it so cumbersome.
%   Still it's better than the old repmat way of doing things.
%
%   bsxand
%   bsxatan2
%   bsxeq
%   bsxge
%   bsxgt
%   bsxhypot
%   bsxldivide
%   bsxle
%   bsxlt
%   bsxmax
%   bsxmin
%   bsxminus
%   bsxmod
%   bsxne
%   bsxor
%   bsxplus
%   bsxpower
%   bsxrdivide
%   bsxrem
%   bsxtimes
%   bsxxor
%
%   bsxdiv          - This is equivalent to bsxrdivide: z = x./y