legendflex-pkg - GitLite

KO | EN

gitlite — search

#command-line #api #awesome-list #linux #terminal #containers #openai #android #nlp #ios

legendflex-pkg

(★ 33)

A more flexible legend for Matlab

File Explorer

ZIP Download

- .gitignore
- legendflex.m
- README_01.png
- README_02.png
- README_03.png
- README_04.png
- README_05.png
- .gitignore
- getpos.m
- setgetposexamples.m
- setpos.m
.gitignore
LICENSE.txt
README.html
README.m
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`box`

View Details ▼

A PHP application for building and managing Phars.

box compile

Compile a new Phar file:

box compile {{[-c|--config]}} {{path/to/config}}

Compile a new Phar file using a specific configuration file:

box info

Display information about the PHAR PHP extension:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Author: Kelly Kearney
[![View legendflex.m: a more flexible, customizable legend on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://www.mathworks.com/matlabcentral/fileexchange/31092-legendflex-m-a-more-flexible-customizable-legend)

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

```matlab
(..., '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
```

## Contents

- Getting started        
- Syntax        
- Examples        
- A note on legendflex with LateX        
- Contributions

## Getting started

**Prerequisites**

This function requires Matlab R14 or later.

**Downloading and installation**

This code can be downloaded from [Github](https://github.com/kakearney/legendflex-pkg/) or the [MatlabCentral File Exchange](http://www.mathworks.com/matlabcentral/fileexchange/31092).  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.):

```matlab
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:

```matlab
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);
```

![](https://raw.githubusercontent.com/kakearney/legendflex-pkg/master/readmeExtras/README_01.png)

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:

```matlab
[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');
```

![](https://raw.githubusercontent.com/kakearney/legendflex-pkg/master/readmeExtras/README_02.png)

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:

```matlab
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');
```

![](https://raw.githubusercontent.com/kakearney/legendflex-pkg/master/readmeExtras/README_03.png)

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.*

```matlab
[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');
```

![](https://raw.githubusercontent.com/kakearney/legendflex-pkg/master/readmeExtras/README_04.png)

## 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.

```matlab
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
```

![](https://raw.githubusercontent.com/kakearney/legendflex-pkg/master/readmeExtras/README_05.png)

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 [an issue](https://github.com/kakearney/legendflex-pkg/issues) 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.

<sub>[Published with MATLAB R2016a]("http://www.mathworks.com/products/matlab/")</sub>