API Reference: FastPlot

API Reference: FastPlot

The core plotting class. Supports data lines, thresholds, bands, shadings, fills, and markers with automatic downsampling via MinMax or LTTB algorithms. A multi-level pyramid cache provides O(1) re-downsample on zoom/pan without touching raw data.

---

Constructor

fp = FastPlot();
fp = FastPlot('Parent', axHandle);
fp = FastPlot('LinkGroup', 'groupID');
fp = FastPlot('Theme', 'dark');
fp = FastPlot('XScale', 'log', 'YScale', 'log');

All options are name-value pairs. Defaults are loaded from FastPlotDefaults (via getDefaults) and can be overridden per-instance.

Constructor Parameters

Parameter	Type	Default	Description
Parent	axes handle	[]	Target axes. When empty, a new figure and axes are created automatically.
LinkGroup	string	''	Sync group ID for linked zoom/pan. All FastPlot instances sharing the same LinkGroup string will synchronize their X-axis limits on zoom and pan.
Theme	string or struct	'default'	Theme preset name (e.g. 'dark', 'light', 'industrial', 'scientific'), a custom struct, or a FastPlotTheme object.
XScale	string	'linear'	'linear' or 'log'. Sets the X-axis scale.
YScale	string	'linear'	'linear' or 'log'. Sets the Y-axis scale.
DefaultDownsampleMethod	string	'minmax'	'minmax' or 'lttb'. Default downsampling algorithm for all lines.
DownsampleFactor	number	2	Points per pixel. Controls the ratio of downsampled points to screen pixels.
LiveInterval	number	2.0	Polling interval in seconds for live mode file watching.
Verbose	logical	false	When true, prints diagnostic messages to the console (downsample stats, timing, warnings).
MinPointsForDownsample	number	5000	Below this point count, raw data is plotted without downsampling.
PyramidReduction	number	100	Compression factor per pyramid level. Controls the coarseness of each successive cache tier.

---

Properties

Configurable Properties

These properties can be set before or after construction. Some take effect immediately; others require render() or reapplyTheme() to update the display.

Property	Type	Default	Description
ParentAxes	axes handle	[]	Target axes handle. Empty creates a new figure on render().
LinkGroup	string	''	String ID for linked zoom/pan across plots.
Theme	struct	(from FastPlotTheme)	Theme struct controlling colors, fonts, grid, and line styling. Use reapplyTheme() to refresh after changing on a rendered plot.
Verbose	logical	false	Print diagnostics to the console.
LiveViewMode	string	''	Controls X-axis behavior on live data arrival. 'preserve' keeps current zoom, 'follow' scrolls to track latest data, 'reset' fits the full X range. Empty means no view mode is applied.
LiveFile	string	''	Path to the .mat file watched in live mode.
LiveUpdateFcn	function handle	[]	Callback @(fp, data) invoked when the live file changes.
LiveIsActive	logical	false	Whether live polling is currently running.
LiveInterval	number	2.0	Poll interval in seconds for live mode.
MetadataFile	string	''	Path to a separate .mat file for metadata (loaded alongside live data).
MetadataVars	cell array	{}	Variable names to extract from the metadata file.
MetadataLineIndex	number	1	Which line index receives metadata from the metadata file.
DeferDraw	logical	false	When true, skips drawnow during batch render. Used internally by openLoupe() and FastPlotFigure.
ShowProgress	logical	true	Show a console progress bar during render().
XScale	string	'linear'	'linear' or 'log' for the X axis.
YScale	string	'linear'	'linear' or 'log' for the Y axis.
ViolationsVisible	logical	true	Global toggle for violation marker visibility.
MinPointsForDownsample	number	5000	Point count below which raw data is plotted directly.
DownsampleFactor	number	2	Points per pixel (min + max).
PyramidReduction	number	100	Reduction factor per pyramid level.
DefaultDownsampleMethod	string	'minmax'	Default algorithm: 'minmax' or 'lttb'.

Read-Only Properties

These properties are managed internally. They are readable but cannot be set from outside the class.

Property	Type	Description
Lines	struct array	Data lines. Each element has fields: X, Y, Options, DownsampleMethod, hLine, Pyramid, HasNaN, Metadata, IsStatic.
Thresholds	struct array	Threshold lines. Fields: Value, X, Y, Direction, ShowViolations, Color, LineStyle, Label, hLine, hMarkers.
Bands	struct array	Horizontal band fills. Fields: YLow, YHigh, FaceColor, FaceAlpha, EdgeColor, Label, hPatch.
Markers	struct array	Custom event markers. Fields: X, Y, Marker, MarkerSize, Color, Label, hLine.
Shadings	struct array	Shaded regions between two curves. Fields: X, Y1, Y2, FaceColor, FaceAlpha, EdgeColor, DisplayName, hPatch, CacheX, CacheY1, CacheY2.
IsRendered	logical	true after render() has been called.
hFigure	handle	Handle to the MATLAB figure.
hAxes	handle	Handle to the axes object.
XType	string	'numeric' or 'datenum'. Auto-set to 'datenum' when datetime X data is added.
IsDatetime	logical	true if X data was originally datetime (internally stored as datenum).

---

Methods

addLine(x, y, ...)

Add a data line for downsampled rendering. Must be called before render().

fp.addLine(x, y);
fp.addLine(x, y, 'DisplayName', 'Sensor1', 'Color', 'b', 'LineWidth', 1.5);
fp.addLine(x, y, 'DownsampleMethod', 'lttb');
fp.addLine(dt, y);  % datetime X values auto-detected and converted to datenum

Parameters:

Parameter	Type	Default	Description
x	numeric or datetime	(required)	Monotonically increasing X data. Datetime values are automatically converted to datenum.
y	numeric	(required)	Y data array, same length as x. NaN gaps are allowed.
DisplayName	string	''	Legend label for this line.
Color	RGB triplet or char	(auto-cycled)	Line color. If omitted, the next color from the theme palette is assigned automatically.
LineWidth	number	0.5	Line width in points. Overridden by theme LineWidth on reapplyTheme().
LineStyle	string	'-'	Line style ('-', '--', ':', '-.').
DownsampleMethod	string	'minmax'	Override per-line: 'minmax' or 'lttb'.
XType	string	'numeric'	'numeric' or 'datenum'. Set to 'datenum' to force datenum mode without passing datetime objects.
Metadata	struct	[]	Struct with a .datenum field for forward-fill lookup via lookupMetadata().
AssumeSorted	logical	false	Skip the monotonicity check on X (use when data is guaranteed sorted).
HasNaN	logical	(auto)	Override NaN detection. When empty, any(isnan(y)) is computed automatically.

Notes:

• X must be monotonically increasing (checked in chunks of 1M elements unless AssumeSorted is true).
• Both X and Y are forced to row vectors internally.
• Errors if called after render().

---

addThreshold(value, ...) or addThreshold(thX, thY, ...)

Add a constant or time-varying threshold line. Must be called before render().

Scalar (constant) threshold:

fp.addThreshold(4.5, 'Direction', 'upper', 'ShowViolations', true, 'Color', 'r');

Time-varying threshold:

fp.addThreshold(thX, thY, 'Direction', 'upper', 'ShowViolations', true);

The calling convention is auto-detected: if the first two arguments are both numeric and the first has more than one element, the call is treated as time-varying.

Parameters:

Parameter	Type	Default	Description
value	scalar	(required for constant)	Constant threshold Y value.
thX, thY	numeric vectors	(required for time-varying)	X and Y vectors defining a piecewise threshold function.
Direction	string	'upper'	'upper' (violations above threshold) or 'lower' (violations below).
ShowViolations	logical	false	When true, violation markers are drawn at threshold crossings.
Color	RGB triplet or string	(theme ThresholdColor)	Threshold line color.
LineStyle	string	(theme ThresholdStyle)	Line style, typically '--'.
Label	string	''	Text label for the threshold.

---

addBand(yLow, yHigh, ...)

Add a horizontal band fill (constant Y bounds spanning the full X range). Must be called before render().

fp.addBand(85, 95, 'FaceColor', [1 0.3 0.3], 'FaceAlpha', 0.15, 'Label', 'High Alarm');

Bands are rendered as patches behind data lines. They span the full X range and are not re-downsampled on zoom.

Parameters:

Parameter	Type	Default	Description
yLow	scalar	(required)	Lower Y bound of the band.
yHigh	scalar	(required)	Upper Y bound of the band.
FaceColor	RGB triplet	(theme ThresholdColor)	Fill color.
FaceAlpha	scalar (0--1)	(theme BandAlpha)	Fill transparency.
EdgeColor	color	'none'	Edge color of the patch.
Label	string	''	Text label for the band.

---

addShaded(x, y1, y2, ...)

Add a shaded region between two curves. The shaded area is dynamically re-downsampled on zoom/pan. Must be called before render().

fp.addShaded(x, y_upper, y_lower, 'FaceColor', [0.3 0.7 1], 'FaceAlpha', 0.2);

For large datasets (>20k points), a pre-downsampled cache is built at render time to speed up subsequent zoom updates.

Parameters:

Parameter	Type	Default	Description
x	numeric	(required)	Monotonically increasing X positions.
y1	numeric	(required)	Upper boundary Y values.
y2	numeric	(required)	Lower boundary Y values.
FaceColor	RGB triplet	[0 0.45 0.74]	Fill color.
FaceAlpha	scalar (0--1)	0.15	Fill transparency.
EdgeColor	color	'none'	Edge color.
DisplayName	string	''	Legend entry text.

Notes:

• All three arrays (x, y1, y2) must have the same number of elements.
• X must be monotonically increasing.

---

addFill(x, y, ...)

Area fill from a data curve to a constant baseline. This is a convenience wrapper around addShaded(x, y, baseline_vector). Must be called before render().

fp.addFill(x, y, 'FaceColor', [0 0.5 1], 'Baseline', 0);

Parameters:

Parameter	Type	Default	Description
x	numeric or datetime	(required)	X positions. Datetime values are auto-converted to datenum.
y	numeric	(required)	Y values for the curve.
Baseline	scalar	0	Constant Y value for the fill baseline.
FaceColor	RGB triplet	[0 0.45 0.74]	Fill color.
FaceAlpha	scalar (0--1)	0.15	Fill transparency.
EdgeColor	color	'none'	Edge color.
DisplayName	string	''	Legend entry text.

---

addMarker(x, y, ...)

Add custom event markers at specific positions. Markers are drawn as a line object with LineStyle='none' and are not downsampled. Must be called before render().

fp.addMarker(x_events, y_events, 'Marker', 'v', 'MarkerSize', 8, 'Color', [1 0 0]);

Parameters:

Parameter	Type	Default	Description
x	numeric	(required)	X positions of the markers.
y	numeric	(required)	Y positions of the markers.
Marker	char	'o'	Marker symbol: 'o', 'v', '^', 's', 'd', '+', 'x', '*', 'p', 'h', etc.
MarkerSize	number	6	Marker size in points.
Color	RGB triplet	(theme ThresholdColor)	Marker color.
Label	string	''	Label for the marker group.

---

addSensor(sensor, ...)

Add a Sensor object's data, thresholds, and violations in one call. The sensor's Name (or Key as fallback) is used as the DisplayName for the legend. Each threshold in sensor.ResolvedThresholds is added via addThreshold() with its resolved color, line style, direction, and label. Must be called before render().

fp.addSensor(sensor);
fp.addSensor(sensor, 'ShowThresholds', true);
fp.addSensor(sensor, 'ShowThresholds', false);  % data line only

Parameters:

Parameter	Type	Default	Description
sensor	Sensor object	(required)	A resolved Sensor with fields X, Y, Name, Key, and ResolvedThresholds.
ShowThresholds	logical	true	When false, only the data line is added (thresholds are suppressed).

---

render()

Render the plot, create the figure (if needed), and install zoom/pan listeners. Can only be called once per FastPlot instance.

fp.render();

What render() does:

1. Creates a figure and axes (or uses ParentAxes)
2. Applies the theme (background, grid, font)
3. Renders bands and shaded regions (back layer)
4. Downsamples all lines to screen pixel resolution
5. Draws threshold lines and violation markers
6. Draws custom markers (front layer)
7. Sets axis limits with 5% padding
8. Installs XLim/resize listeners for dynamic re-downsample
9. Schedules async refinement for large datasets
10. Registers in LinkGroup for synchronized zoom/pan

Parameters:

Parameter	Type	Default	Description
progressBar	ConsoleProgressBar	[]	Optional external progress bar (used by FastPlotFigure for batch rendering).

Notes:

• At least one line must be added before calling render().
• After render(), addLine(), addThreshold(), addBand(), addShaded(), addFill(), and addMarker() will error. Use updateData() for post-render data updates.

---

setScale(...)

Change axis scales before or after render(). After render, this applies the new scale to the axes, invalidates affected pyramid caches, and re-downsamples all lines, shadings, and violation markers.

fp.setScale('YScale', 'log');
fp.setScale('XScale', 'log', 'YScale', 'log');

Parameters:

Parameter	Type	Default	Description
XScale	string	(current value)	'linear' or 'log'.
YScale	string	(current value)	'linear' or 'log'.

Notes:

• When XScale changes, all pyramid caches are invalidated (log-space bucketing differs from linear).
• When only YScale changes, only LTTB pyramids are invalidated (MinMax is order-invariant along Y).

---

updateData(lineIdx, newX, newY, ...)

Replace data for a line and re-downsample. This is the primary method for live data updates. Must be called after render().

fp.updateData(1, newX, newY);
fp.updateData(1, newX, newY, 'Metadata', newMeta);
fp.updateData(1, newX, newY, 'SkipViewMode', true);

What updateData() does:

1. Replaces raw X/Y and resets the pyramid cache
2. Updates HasNaN and IsStatic flags
3. Applies LiveViewMode (follow/preserve/reset)
4. Re-downsamples all lines, shadings, and violations
5. Flushes the display via drawnow limitrate

Parameters:

Parameter	Type	Default	Description
lineIdx	integer	(required)	1-based index of the data line to update.
newX	numeric	(required)	New X data (monotonically increasing).
newY	numeric	(required)	New Y data (same length as newX).
Metadata	struct	[]	Replacement metadata struct for the line.
SkipViewMode	logical	false	When true, skips LiveViewMode adjustments.

---

lookupMetadata(lineIdx, xValue)

Get active metadata at a given X value using forward-fill (last-observation-carried-forward) logic.

info = fp.lookupMetadata(1, 7);

Parameters:

Parameter	Type	Description
lineIdx	integer	1-based index of the data line.
xValue	scalar	X position (datenum or numeric) to look up.

Returns: A struct with one value per metadata field (excluding .datenum), or [] if no metadata is available or xValue precedes all timestamps.

Example:

meta = struct('datenum', [1 5 10], 'operator', {{'A','B','C'}});
fp.addLine(1:20, randn(1,20), 'Metadata', meta);
fp.render();
info = fp.lookupMetadata(1, 7);  % returns struct with operator='B'

---

setLineMetadata(lineIdx, meta)

Attach or replace metadata on a line after construction. The metadata struct should contain a .datenum field with sorted timestamps.

meta = struct('datenum', [1 5], 'batch', {{'A','B'}});
fp.setLineMetadata(1, meta);

Parameters:

Parameter	Type	Description
lineIdx	integer	1-based index of the data line.
meta	struct	Metadata struct (must include .datenum field).

---

setViolationsVisible(on)

Show or hide all violation markers globally. Individual thresholds still control whether they participate via their own ShowViolations property.

fp.setViolationsVisible(false);  % hide all markers
fp.setViolationsVisible(true);   % show and recompute

Parameters:

Parameter	Type	Description
on	logical	true to show (forces recomputation), false to hide.

---

resetColorIndex()

Reset the auto color cycling counter to zero. The next addLine() call without an explicit Color will use the first color from the theme palette.

fp.resetColorIndex();

---

reapplyTheme()

Re-apply the current Theme to axes and figure. Call this after changing fp.Theme on an already-rendered plot to update the display without re-rendering. Has no effect before render().

fp.Theme = FastPlotTheme('dark');
fp.reapplyTheme();

---

openLoupe()

Open a standalone enlarged copy of this plot in a new figure. Creates a deep copy of all lines, thresholds, bands, shadings, and markers. The new figure preserves the current zoom state and receives its own FastPlotToolbar.

fp.openLoupe();  % or double-click on the axes

---

Live Mode Methods

startLive(filepath, updateFcn, ...)

Start live mode -- poll a .mat file for changes. Uses a MATLAB timer for non-blocking polling. On Octave (where timer is unavailable), call runLive() after this method for a blocking poll loop. Must be called after render().

fp.startLive('data.mat', @(fp, d) fp.updateData(1, d.x, d.y));
fp.startLive('data.mat', @updateFcn, 'Interval', 1, 'ViewMode', 'follow');
fp.startLive('data.mat', @updateFcn, ...
    'MetadataFile', 'meta.mat', ...
    'MetadataVars', {'batch', 'operator'}, ...
    'MetadataLineIndex', 1);

Parameters:

Parameter	Type	Default	Description
filepath	string	(required)	Path to a .mat file to watch for changes.
updateFcn	function handle	(required)	Callback @(fp, data) called when the file changes. data is the loaded .mat struct.
Interval	number	2.0	Poll period in seconds.
ViewMode	string	'preserve'	'preserve' (keep current zoom), 'follow' (scroll to track latest data), or 'reset' (fit full X range).
MetadataFile	string	''	Path to a separate metadata .mat file.
MetadataVars	cell array	{}	Variable names to extract from the metadata file.
MetadataLineIndex	number	1	Which line receives the loaded metadata.

---

stopLive()

Stop live mode polling. Stops the timer, cleans up deferred timers, and sets LiveIsActive to false. Safe to call even if live mode is not active.

fp.stopLive();

---

runLive()

Blocking poll loop for live mode (Octave compatibility). On MATLAB this is a no-op because startLive() already installed a non-blocking timer. On Octave it blocks until the figure is closed or the user presses Ctrl+C.

fp.startLive('data.mat', @updateFcn);
fp.runLive();  % blocks on Octave, no-op on MATLAB

---

refresh()

Manual one-shot reload from LiveFile. Loads the file, calls LiveUpdateFcn, and updates timestamps. Also reloads MetadataFile if configured. Errors if LiveFile or LiveUpdateFcn have not been set.

fp.refresh();

---

setViewMode(mode)

Change the live view mode at runtime.

fp.setViewMode('follow');

Parameters:

Parameter	Type	Description
mode	string	'preserve', 'follow', or 'reset'.

---

Static Methods

FastPlot.distFig(...)

Auto-arrange all open figure windows in a grid that fills the screen. Figures are sorted by number and tiled left-to-right, top-to-bottom.

FastPlot.distFig();
FastPlot.distFig('Rows', 2, 'Cols', 3);

Parameters:

Parameter	Type	Default	Description
Rows	number	(auto)	Number of grid rows.
Cols	number	(auto)	Number of grid columns.

---

FastPlot.resetDefaults()

Force reload of FastPlotDefaults on next use. Clears the cached defaults struct so the next FastPlot constructor will re-read FastPlotDefaults.m. Useful after editing the defaults file in a running session.

FastPlot.resetDefaults();
fp = FastPlot();  % picks up new defaults

---

See Also

• FastPlotFigure -- Multi-tile dashboard layout
• FastPlotToolbar -- Interactive toolbar
• FastPlotTheme -- Theme configuration
• Sensor -- Sensor objects with state-dependent thresholds