Concluding my three-part mini-series on hidden and undocumented plot/axes properties, I would like to present a set of properties that I find very useful in dynamic plots: **XLimInclude, YLimInclude, ZLimInclude, ALimInclude** and **CLimInclude**. These properties, which are relevant for plot/axes objects, have an ‘on’ value by default. When set to ‘off’, they exclude their object from the automatic computation of the corresponding axes limits (**XLim/YLim/ZLim/ALim/CLim**).

For example, here’s a simple sine wave with a wavefront line marker. Note how the too-tall wavefront line affects the entire axes Y-limits:

cla; t=0:.01:7.5; plot(t,sin(t)); line('xdata',[7.5,7.5], 'ydata',[-5,5], 'color','r'); box off

This situation is quickly fixed using the **YLimInclude** property:

cla; t=0:.01:7.5; plot(t,sin(t)); line('xdata',[7.5,7.5], 'ydata',[-5,5], 'color','r', ... 'YLimInclude','off'); box off

Beside the functional importance of this feature, it also has a large potential for improved application performance: I recently designed a monitor-like GUI for a medical application, where the data is constantly updated from an external sensor connected to the computer. The GUI presents the latest 10 seconds of monitored data, which bounce up and down the chart. A red wave-front line is presented and constantly updated, to indicate the current data position. Since the monitored data jumps up and down, the Y-limits of the monitor chart often changes, and with it I would need to modify the wavefront’s **YData** based on the updated axes **YLim**. This turned out to steal precious CPU time from the actual monitoring application. Came **YLimInclude** to the rescue, by letting me specify the wavefront line as:

hWavefront = line(..., 'YData',[-99,99], 'YLimInclude','off');

Now the wavefront line never needed to update its **YData** (only **XData**, which is much less CPU-intensive) – it always spanned the entire axes height, since [-99,99] were assured (in my particular case) to exceed the actual monitored data. This looked better (no flicker effects) and performed faster than the regular (documented) approach.

Note that although all these properties exist, to the best of my knowledge, for all Handle-Graphic plot objects, they are sometimes meaningless. For example, **ZLimInclude** is irrelevant for a 2D patchless plot; **CLimInclude** relates to the axes color limits which are irrelevant if you’re not using a ** colormap** or something similar;

**ALimInclude**relates to patch transparency (alpha-channel) and is irrelevant elsewhere. In these and similar cases, setting these properties, while allowed and harmless, will simply have no effect.

This concludes my mini-series of undocumented plot/axes properties. To recap, the other articles dealt with the **LooseInset** and **LineSmoothing** properties.

Have you found other similar properties or use-cases that you find useful? I will be most interested to read about them in the comments section below.

Related posts:

- Borderless button used for plot properties A borderless button can be used to add unobtrusive functionality to plot axes...
- Plot performance Undocumented inner plot mechanisms can significantly improve plotting performance ...
- Controlling plot data-tips Data-tips are an extremely useful plotting tool that can easily be controlled programmatically....
- Bar plot customizations Matlab bar charts can be customized in various nifty ways. ...
- Undocumented scatter plot jitter Matlab's scatter plot can automatically jitter data to enable better visualization of distribution density. ...
- Customizing axes part 4 – additional properties Matlab HG2 axes can be customized in many different ways. This article explains some of the undocumented aspects. ...

Hi Yair,

Thanks, I think this will be very useful when you have a lot of graphics objects on the axes but you know what the overall dimensions will be. I’ll be trying this tip out right away.

Perhaps you could expand on why you would use this in place of setting the YLImMode as in:

@Matt – that’s exactly the point: I want the limits to remain

automaticand be updated with the plot data – I just don’t want some particular elements, like the wavefront line, to influence the limits. In your solution, if I now modify the plot data, the axes limits will remain fixed at they previous state.Ok got it now.

So if I run the code below it illustrates the point:

exactly – thanks for the clarification example

Hi Yair,

Glad I remembered this tip. Had a plot with 50+ draggable lines on it that updated other plots. Much smoother when I remembered this tip and turned off the XLimInclude , YLimInclude for the draggable lines and the line plot they were updating.

Thanks

Matt

For anyone interested, there appears to be an anomaly when using the

LimIncludeproperties with: http://www.mathworks.com/matlabcentral/newsreader/view_thread/295878#812396hgtransform- Yair

Pingback: datestr performance | Undocumented Matlab

Pingback: HG2 update | Undocumented Matlab

Pingback: Customizing axes part 2 | Undocumented Matlab