imageslices

Plots matrix data using imagesc, with subplots showing horizontal slices through the data.

This function lets you quickly create a publication-quality figure of matrix data with subplots showing horizontal slices through the data. The slices are evenly spaced rows of the matrix, and can be plotted in separate subplots or together in one subplot.

There are many optional inputs that allow the user to specify the number of slices, locations of the slices, axis labels, line colors, subplot margins, and more. The outputs of this function are the new MATLAB figure, a vector of axis handles, and the y coordinates of the slices.

Syntax:
imageslices(z)
imageslices(x, y, z)
imageslices(z, Nslices)
imageslices(z, Nslices, ylimits)
imageslices(z, ylimits)
imageslices(___, Name, Value)
imageslices(___, Property)

Inputs:
z: 2D matrix of data values, size M-by-N (required)
x: Vector of x values, must have length N (optional)
y: Vector of y values, must have length M (optional)
Nslices: Number of slices to take (optional, default = 10)
ylimits: 2-element vector with coordinates of the lowest & highest slices. If a y vector is provided, these coordinates will be rounded to the nearest values present in y. If a y vector is not provided, these coordinates represent row indexes in z. (optional, default = [min(y),max(y)]).
Name, Value: Specifies additional plotting properties using one or more name-value pair arguments. These are described below.
Property: Specifies additional plotting properties that are not in name-value pair arguments.

Outputs:
1) The newly created figure
2) axis_handles: a vector of handles for the various axes in the new figure, starting with the imagesc axis.
3) yslices: vector of row indexes at which the slices of z were taken

Name-Value Property Pairs:
'labels': Cell array of labels for the X,Y,Z axes. Default = {'x','y','z'}
'colors': Colors to use for the slices. Must be a matrix of size Nslices-by-3. Default = lines(Nslices)
'ticklength': Length of the colored ticks that are added on top of the imagesc axis, in axis-normalized units. Default = 0.02
'tickstyle': Style of the colored ticks that are added on top of the imagesc axis; any valid MATLAB line style is allowed. Default = '-'
'topmargin': Margin above the top-most subplot of data slices, in figure-normalized units. Default = 0.05
'bottommargin': Margin below the bottom-most subplot of data slices, in figure-normalized units. Default = 0.1
'subplotgap': Vertical gap between the subplots of data slices, in figure-normalized units. Default = 0.005
'deltaz': Including this property causes all slices to be plotted in a single subplot. The numeric Value following this property Name will be used as a vertical spacing between data slices.

Additional Plotting Properties:
'subtractmean': This property will only take effect if 'deltaz' is also in use. Before each data slice is plotted, its mean will be subtracted.

Notes:
If slices are to be plotted in separate subplots, each subplot will have the same vertical axis limits; these will by default be min(min(z)) and max(max(z)).
If more than 3 subplots are created for the data slices, yticklabels will only be shown for every other subplot.


Examples:
imageslices(peaks(100));
imageslices(peaks(100), 5, [20,80]);
imageslices(peaks(100), [20,80], 'deltaz', 5);
imageslices(peaks(100), [20,80], 'deltaz', 5, 'subtractmean');
imageslices(peaks(100), 5, [20,80], 'ticklength', 1, 'tickstyle', '--');
x = (1:100);
y = (1:100);
z = peaks(100);
hax = imageslices(x, y, z, 'labels', {'x label','y label','z label'});
colormap(hax(1), 'jet');