Matlab function to plot histograms comparing several data sets.
Usage: [hFig] = ComparisonHist3({vfA, vfB, vfC, ...}, vfBins, ...
<{fPipA, fPipB, fPipC, ...}, ...>
<vfP> or <fhTest> or <{fhTest, nOutputInd}>
<{vfColorA, vfColorB, vfColorC, ...}, ...>
<strMeasureName, vbFillBars>)

'vfA', 'vfB', ... are vectors of data, which will be plotted as proportional histograms on a single set of axes. 'vfBins' is the list of bin *EDGES*, as used in histc.

The optional arguments 'fPipA', 'fPipB', ... are scalar values corresponding to each vector of data, and will be plotted as "pips" above the histograms. If they are not supplied, pips will be plotted as medians of each vector. If an empty matrix is supplied, that pip will not be displayed.

The optional argument 'vfP' is a vector of P values indicating the result of a statistical test of some pairwise difference between two of the data vectors. It has the format ['fP_AB' 'fP_AC' 'fP_BC' ...]. Significant differences will be indicated by asterisks and bars joining the pips of the appropriate distributions. If 'vfP' is not provided, then the Wilcoxon rank-sum test of differences in medians will be used.

Alternatively, a function handle can be provided in 'fhTest'. This function must return the P value indicating the significance of a difference between two distributions: fP = @(vfX, vfY). This function will be applied pair-wise between each data vector. NOTE: ttest2 does NOT return the P value as the first argument, and so cannot be used directly in this way. In this case, pass the function and which output to take as a cell array: {@ttest2, 2}. This form will take the second output of ttest2 as the P value to use.

The optional arguments 'vfColorA', 'vfColorB', ... set the colours for the corresponding histogram. If not supplied, a set of colours will be chosen for you. The first data set will be plotted in black.

The optional argument 'strMeasureName' is used as the x label of the figure.

The optional argument 'vbFillBars' is a boolean vector, with each element corresponding to a data set 'vfA', 'vfB', ... A value of 'true' indicates that the corresponding data set should be plotted using filled histogram bars. A value of 'false' indicates that the corresponding data set should be plotted using a stair plot. By default, a stair plot is used for all data sets except the first.

'hFig' will be the figure handle of the comparison figure. The title of the figure will contain useful statistical information about the histograms.