You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
353 lines
15 KiB
353 lines
15 KiB
3 years ago
|
%% |legendflex.m|: a more flexible, customizable legend
|
||
|
|
% Author: Kelly Kearney
|
||
|
|
%
|
||
|
|
% This repository includes the code for the |legendflex.m| Matlab function,
|
||
|
|
% along with all dependent functions required to run it.
|
||
|
|
%
|
||
|
|
% This function offers a more flexible version of the legend command. It
|
||
|
|
% offers a different method of positioning the legend, as well as options
|
||
|
|
% to:
|
||
|
|
%
|
||
|
|
% * organize legend text and symbols in a grid with a specified number of
|
||
|
|
% rows and/or columns
|
||
|
|
% * rescale the horizontal space used by each legend symbol
|
||
|
|
% * create multiple legends for the same axis
|
||
|
|
% * add a title to the legend within the legend box
|
||
|
|
%
|
||
|
|
% This function should support all types of plot objects.
|
||
|
|
%
|
||
|
|
% *Legend positioning*
|
||
|
|
%
|
||
|
|
% Unlike in the default legend command, where the legend is positioned
|
||
|
|
% relative to the labeled objects' parent axis according to one of 16
|
||
|
|
% location strings, this function positions the legend based on two anchor
|
||
|
|
% points (one on either the figure or a child object of a figure, and one
|
||
|
|
% on the legend itself) and a buffer (or offset) between these two anchor
|
||
|
|
% points. The anchor points refer to the corners and centers of each
|
||
|
|
% side of the box surrounding the reference object and the legend itself;
|
||
|
|
% they can be refered to either as numbers (1-8, clockwise from northwest
|
||
|
|
% corner) or strings ('nw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w'). The
|
||
|
|
% position of the legend is determined by these two points and the distance
|
||
|
|
% between them, defined in the 'buffer' variable, which by default is
|
||
|
|
% measured in pixels. So the combination of
|
||
|
|
%
|
||
|
|
% (..., 'ref', gca, 'anchor', [3 3], 'buffer', [-10 -10])
|
||
|
|
%
|
||
|
|
% means that you want the northeast corner of the current axis to be
|
||
|
|
% aligned with the northeast corner of the legend, but with the legend
|
||
|
|
% shifted 10 pixels to the left and down.
|
||
|
|
%
|
||
|
|
% This method of positioning can be particularly useful when labeling a
|
||
|
|
% figure that includes many subplots that share a common color scheme,
|
||
|
|
% where the "best" location for a legend is not necessarily within the
|
||
|
|
% bounds of an axis. Unlike the legend command, the axes in the figure are
|
||
|
|
% never resized (and it is up to the user to check that the legend fits on
|
||
|
|
% the figure in the specified location). In addition to being easier than
|
||
|
|
% manually positioning a legend, this function updates the legend location
|
||
|
|
% when the figure is resized, preserving the desired alignment. The
|
||
|
|
% following anchor/buffer combinations, when used with the default
|
||
|
|
% reference and a buffer unit of pixels, approximately replicate the
|
||
|
|
% typical legend locations:
|
||
|
|
%
|
||
|
|
% Specifier Anchor Buffer
|
||
|
|
%
|
||
|
|
% north [2 2] [ 0 -10]
|
||
|
|
% south [6 6] [ 0 10]
|
||
|
|
% east [4 4] [-10 0]
|
||
|
|
% west [8 8] [ 10 0]
|
||
|
|
% northeast [3 3] [-10 -10]
|
||
|
|
% northwest [1 1] [ 10 -10]
|
||
|
|
% southeast [5 5] [-10 10]
|
||
|
|
% southwest [7 7] [ 10 10]
|
||
|
|
% northoutside* [2 6] [ 0 10]
|
||
|
|
% southoutside* [6 2] [ 0 -10]
|
||
|
|
% eastoutside* [3 8] [ 10 0]
|
||
|
|
% westoutside* [8 3] [-10 0]
|
||
|
|
% northeastoutside* [3 1] [ 10 0]
|
||
|
|
% northwestoutside* [1 3] [-10 0]
|
||
|
|
% southeastoutside* [5 7] [ 10 0]
|
||
|
|
% southwestoutside* [7 5] [-10 0]
|
||
|
|
%
|
||
|
|
% *placed outside axis rather than resizing plot box
|
||
|
|
%
|
||
|
|
%% Getting started
|
||
|
|
%
|
||
|
|
% *Prerequisites*
|
||
|
|
%
|
||
|
|
% This function requires Matlab R14 or later.
|
||
|
|
%
|
||
|
|
% *Downloading and installation*
|
||
|
|
%
|
||
|
|
% This code can be downloaded from <https://github.com/kakearney/legendflex-pkg/ Github>
|
||
|
|
% or the
|
||
|
|
% <http://www.mathworks.com/matlabcentral/fileexchange/31092
|
||
|
|
% MatlabCentral File Exchange>. The File Exchange entry is updated daily
|
||
|
|
% from the GitHub repository.
|
||
|
|
%
|
||
|
|
% *Matlab Search Path*
|
||
|
|
%
|
||
|
|
% The following folders need to be added to your Matlab Search path (via
|
||
|
|
% |addpath|, |pathtool|, etc.):
|
||
|
|
%
|
||
|
|
% legendflex-pkg/legendflex
|
||
|
|
% legendflex-pkg/setgetpos_V1.2
|
||
|
|
|
||
|
|
%% Syntax
|
||
|
|
%
|
||
|
|
% legendflex(M, param1, val1, ...)
|
||
|
|
% legendflex(h, M, param1, val1, ...)
|
||
|
|
% [legend_h,object_h,plot_h,text_str] = legendflex(...)
|
||
|
|
%
|
||
|
|
% Input variables:
|
||
|
|
%
|
||
|
|
% * |M|: cell array of strings, labels for legend
|
||
|
|
% * |h|: handle of axis or handle(s) of object(s) to be labeled. If
|
||
|
|
% this is an axis handle, all children of the axis will be
|
||
|
|
% included in the legend. If not included, current axis is
|
||
|
|
% used.
|
||
|
|
%
|
||
|
|
% Optional input variables (passed as parameter/value pairs): [default]
|
||
|
|
%
|
||
|
|
% * |ncol|: number of columns, or 0 to indicate as many as necessary
|
||
|
|
% given the # of labeled objects [1 if nrow is 0, 0
|
||
|
|
% otherwise]
|
||
|
|
% * |nrow|: number of rows, or 0 to indicate as many as necessary
|
||
|
|
% given the # of labeled objects [0]
|
||
|
|
% * |ref|: handle of object used to position the legend. This can be
|
||
|
|
% either a figure or a child object of a figure (and does not
|
||
|
|
% need to relate in any way to the objects being labeled).
|
||
|
|
% If not included, the reference will be to the axis that a
|
||
|
|
% normal legend would be associated with (usually the parent
|
||
|
|
% axis of the labeled objects, unless objects from multiple
|
||
|
|
% axes are passed, in which case it's the parent object of
|
||
|
|
% the first labeled object).
|
||
|
|
% * |anchor|: 1 x 2 array specifying which points of the reference object
|
||
|
|
% and new legend, respectively, to anchor to each other.
|
||
|
|
% Anchor points can be described using either numbers (in a 1
|
||
|
|
% x 2 double array) or directional strings (in a 1 x 2 cell
|
||
|
|
% array) as follows:
|
||
|
|
% 1 = 'nw' = upper left corner,
|
||
|
|
% 2 = 'n' = center of top edge,
|
||
|
|
% 3 = 'ne' = upper right corner,
|
||
|
|
% 4 = 'e' = center of right edge,
|
||
|
|
% 5 = 'se' = bottom right corner,
|
||
|
|
% 6 = 's' = center of bottom edge,
|
||
|
|
% 7 = 'sw' = bottom left corner,
|
||
|
|
% 8 = 'w' = center of left edge,
|
||
|
|
% [[3 3], i.e. {'ne' 'ne'}]
|
||
|
|
% * |buffer|: 1 x 2 array of horizontal and vertical distance,
|
||
|
|
% respectively, from the reference anchor point to the legend
|
||
|
|
% anchor point. Distance is measured in units specified by
|
||
|
|
% bufferunit. [[-10 -10]]
|
||
|
|
% * |bufferunit|: unit for buffer distance. Note that this property only
|
||
|
|
% affects the units used to position the legend, not the
|
||
|
|
% units for the legend itself (which is always a fixed size,
|
||
|
|
% based on the space needed to encapsulate the specified
|
||
|
|
% symbols and text). The 'normalized' units are normalized
|
||
|
|
% to size of the figure. ['pixels']
|
||
|
|
% * |box|: 'on' or 'off', specifies whether to enclose legend objects
|
||
|
|
% in a box ['on']
|
||
|
|
% * |xscale|: scalar value indicating scale factor to apply to the width
|
||
|
|
% required by each symbol, relative to the size used by
|
||
|
|
% legend. For example, 0.5 will shorten the lines/patches by
|
||
|
|
% half. [1]
|
||
|
|
% * |title|: A title string to be added inside the legend box, centered,
|
||
|
|
% above all legend entries. This can be either a string or a
|
||
|
|
% cell array of strings; the latter will produce a multi-line
|
||
|
|
% title. If empty, no title is added. ['']
|
||
|
|
% * |padding|: 1 x 3 array, pixel spacing added to beginning of each
|
||
|
|
% column (before symbol), between symbol and text, and after
|
||
|
|
% text, respectively. Usually, the default provides the
|
||
|
|
% spacing typical of a regular legend, but occassionally the
|
||
|
|
% extent properties wrap a little too close to text, making
|
||
|
|
% things look crowded; in these cases you can try unsquishing
|
||
|
|
% (or squishing, via use of negative values) things via this
|
||
|
|
% parameter. [2 1 1]
|
||
|
|
% * |nolisten|: logical scalar. If true, don't add the event listeners.
|
||
|
|
% The event listeners update the legend objects when you
|
||
|
|
% change a property of the labeled objects (such as line
|
||
|
|
% style, color, etc.). However, the updating requires the
|
||
|
|
% legend to be redrawn, which can really slow things down,
|
||
|
|
% especially if you're labelling lots of objects that get
|
||
|
|
% changed together (if you change the line width of 100
|
||
|
|
% labeled lines, the legend gets redrawn 100 times). In more
|
||
|
|
% recent releases, this also occurs when printing to file, so
|
||
|
|
% I recommend setting this to true if you plan to print a
|
||
|
|
% legend with a large number of labeled objects. The legend
|
||
|
|
% will still be redrawn on figure resize regardless of the
|
||
|
|
% value of this parameter. [false]
|
||
|
|
%
|
||
|
|
% In addition to these legendflex-specific parameters, this function will
|
||
|
|
% accept any parameter accepted by the original legend function (e.g.
|
||
|
|
% font properties) except 'location', 'boxon', 'boxoff', or 'hide'.
|
||
|
|
%
|
||
|
|
% Output variables:
|
||
|
|
%
|
||
|
|
% * |legend_h|: handle of the legend axis. It is not linked to an axis or
|
||
|
|
% graphics objects in the same way as a Matlab legend.
|
||
|
|
% However, on figure resize, all properties of the legend
|
||
|
|
% objects are checked for changes, so adjusting the figure
|
||
|
|
% size can re-link the legend to the labeled objects after
|
||
|
|
% you have made changes to those objects.
|
||
|
|
% * |object_h|: handles of the line, patch, and text graphics objects
|
||
|
|
% created in the legend
|
||
|
|
% * |plot_h|: handles of the lines and other objects labeled in this
|
||
|
|
% legend
|
||
|
|
% * |text_str|: cell array of the text strings used in the legend
|
||
|
|
|
||
|
|
%% Examples
|
||
|
|
%
|
||
|
|
% First, let's create a subplot with 10 lines, 5 solid and 5 dashed, which
|
||
|
|
% cycle through 5 colors:
|
||
|
|
|
||
|
|
figure('color','w');
|
||
|
|
for iax = 1:3
|
||
|
|
ax(iax) = subplot(2,2,iax);
|
||
|
|
end
|
||
|
|
|
||
|
|
linespec = [repmat({'r';'b';'g';'c';'m'},2,1), ...
|
||
|
|
[repmat({'-'}, 5, 1); repmat({'--'}, 5, 1)]];
|
||
|
|
|
||
|
|
|
||
|
|
x = [0 10];
|
||
|
|
y = (1:10)'*x;
|
||
|
|
lbl = cellstr(num2str((1:10)'));
|
||
|
|
|
||
|
|
hln(:,1) = plot(ax(1), x, y);
|
||
|
|
set(hln(:,1), {'color','linestyle'}, linespec);
|
||
|
|
|
||
|
|
%%
|
||
|
|
% Now add a legend in the upper left corner, with the entries arranged in a
|
||
|
|
% 4 x 3 grid so it doesn't interfere with the data. We've also decreased
|
||
|
|
% the horizontal space used by each legend line:
|
||
|
|
|
||
|
|
[hl(1).leg, hl(1).obj, hl(1).hout, hl(1).mout] = ...
|
||
|
|
legendflex(hln(:,1), lbl, 'anchor', {'nw','nw'}, ...
|
||
|
|
'buffer', [5 -5], ...
|
||
|
|
'ncol', 3, ...
|
||
|
|
'fontsize', 8, ...
|
||
|
|
'xscale', 0.8, ...
|
||
|
|
'box', 'off');
|
||
|
|
|
||
|
|
|
||
|
|
%%
|
||
|
|
% Plot the same lines in the second subplot. But this time, let's add two
|
||
|
|
% legends: one for color, and one for line style. Note that in this case,
|
||
|
|
% the second legend is positioned relative to the first, rather than
|
||
|
|
% relative to the axis itself:
|
||
|
|
|
||
|
|
hln(:,2) = plot(ax(2), x, y);
|
||
|
|
set(hln(:,2), {'color','linestyle'}, linespec);
|
||
|
|
|
||
|
|
[hl(2).leg, hl(2).obj, hl(2).hout, hl(2).mout] = ...
|
||
|
|
legendflex(hln(1:5,2), lbl(1:5), ...
|
||
|
|
'anchor', {'nw','nw'}, ...
|
||
|
|
'buffer', [5 -5], ...
|
||
|
|
'fontsize',8, ...
|
||
|
|
'xscale',0.5, ...
|
||
|
|
'title', 'Color');
|
||
|
|
[hl(3).leg, hl(3).obj, hl(3).hout, hl(3).mout] = ...
|
||
|
|
legendflex(hln([1 6],2), {'thing 1', 'thing 2'}, ...
|
||
|
|
'ref', hl(2).leg, ...
|
||
|
|
'anchor', {'ne','nw'}, ...
|
||
|
|
'buffer', [0 0], ...
|
||
|
|
'fontsize', 8', ...
|
||
|
|
'title', 'Line');
|
||
|
|
|
||
|
|
%%
|
||
|
|
% Our final subplot simply shows that this function will handle all object
|
||
|
|
% types. We plot a |contourf| plot overlaid with a |quiver| plot, and
|
||
|
|
% label both above the subplot axis.
|
||
|
|
%
|
||
|
|
% _Well, almost any graphics object. In 2014b, there are some rendering
|
||
|
|
% bugs when legend is called with multiple outputs that can cause weird
|
||
|
|
% stuff to happen when labeling contour objects; these sorts of issues may
|
||
|
|
% continue as the Mathworks updates their graphics further._
|
||
|
|
|
||
|
|
[X,Y] = meshgrid(-2:.2:2);
|
||
|
|
Z = X.*exp(-X.^2 - Y.^2);
|
||
|
|
[DX,DY] = gradient(Z,.2,.2);
|
||
|
|
axes(ax(3));
|
||
|
|
hold on;
|
||
|
|
[c,hcont] = contourf(X,Y,Z);
|
||
|
|
hquiv = quiver(X,Y,DX,DY);
|
||
|
|
|
||
|
|
[hl(4).leg, hl(4).obj, hl(4).hout, hl(4).mout] = ...
|
||
|
|
legendflex([hcont hquiv], {'contour', 'quiver'}, ...
|
||
|
|
'anchor',{'ne','se'}, ...
|
||
|
|
'buffer',[0, 0.01], ...
|
||
|
|
'bufferunit', 'normalized');
|
||
|
|
|
||
|
|
%% A note on legendflex with LateX
|
||
|
|
%
|
||
|
|
% Unfortunately, the Latex renderer doesn't play very nicely with
|
||
|
|
% legendflex. It's something that bugs me in my own work too, but I've
|
||
|
|
% never been able to come up with a good workaround that would position
|
||
|
|
% things properly. The legendflex function repositions everything using
|
||
|
|
% the 'Extent' property of all the text in the original legend. However,
|
||
|
|
% the extent property of latex-rendered text doesn't always match up with
|
||
|
|
% the actual space taken up by the text... not quite sure why this is, and
|
||
|
|
% therefore I don't have a reliable way to calculate what that real space
|
||
|
|
% is.
|
||
|
|
%
|
||
|
|
% Here's an example using plain text objects. Ideally, the red boxes would
|
||
|
|
% surround each text object, but in the Latex case, the Extent often leaves
|
||
|
|
% space above or below, or practically overlaps the text.
|
||
|
|
|
||
|
|
|
||
|
|
figure;
|
||
|
|
lax(1) = subplot(2,1,1);
|
||
|
|
lax(2) = subplot(2,1,2);
|
||
|
|
|
||
|
|
txt = {'Data 1', '$\frac{1}{2}$', '$var_{ij}^{k}$'};
|
||
|
|
nt = length(txt);
|
||
|
|
na = length(lax);
|
||
|
|
|
||
|
|
set(lax, 'xlim', [0 nt+1], 'ylim', [0 nt+1]);
|
||
|
|
|
||
|
|
for ii = 1:na
|
||
|
|
ht(ii,:) = text(1:nt,1:nt,txt, 'parent', lax(ii), ...
|
||
|
|
'interpreter', 'none', ...
|
||
|
|
'fontsize', 14);
|
||
|
|
end
|
||
|
|
|
||
|
|
set(ht(2,:), 'interpreter', 'latex');
|
||
|
|
|
||
|
|
for ii = 1:na
|
||
|
|
for it = 1:nt
|
||
|
|
ex = get(ht(ii,it), 'extent');
|
||
|
|
rectangle('position', ex, 'parent', lax(ii), 'edgecolor', 'r');
|
||
|
|
end
|
||
|
|
end
|
||
|
|
|
||
|
|
%%
|
||
|
|
% Becuase of this, you really need to play around with properties (like padding) in order
|
||
|
|
% to get a legendflex legend that uses latex and looks decent. Sometimes
|
||
|
|
% generating the legend first, then setting the latex rendering afterwards
|
||
|
|
% will help a bit. Other times I generate the legend using a larger font
|
||
|
|
% size, then shrink the text back down after it's been positioned. None of
|
||
|
|
% these hacks are ideal, but they're the best I've been able to come up
|
||
|
|
% with.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
%% Contributions
|
||
|
|
%
|
||
|
|
% Community contributions to this package are welcome!
|
||
|
|
%
|
||
|
|
% To report bugs, please submit
|
||
|
|
% <https://github.com/kakearney/legendflex-pkg/issues an issue> on GitHub and
|
||
|
|
% include:
|
||
|
|
%
|
||
|
|
% * your operating system
|
||
|
|
% * your version of Matlab and all relevant toolboxes (type |ver| at the Matlab command line to get this info)
|
||
|
|
% * code/data to reproduce the error or buggy behavior, and the full text of any error messages received
|
||
|
|
%
|
||
|
|
% Please also feel free to submit enhancement requests, or to send pull
|
||
|
|
% requests (via GitHub) for bug fixes or new features.
|
||
|
|
%
|
||
|
|
% I do monitor the MatlabCentral FileExchange entry for any issues raised
|
||
|
|
% in the comments, but would prefer to track issues on GitHub.
|
||
|
|
%
|
||
|
|
|