EnsemblePlot

Manage multiple members of an ensemble as a single line object.

EnsemblePlot Manage multiple members of an ensemble as a single line object.

Usage:

OBJ = EnsemblePlot(NAMES, T, X) plots the columns of matrix X versus

the columns of matrix T as individual members of an ensemble, i.e.

NaN separated line segments of a single line object. The NAMES vector

provides a means to access, interact with, and identify each member of

the ensemble through the provided class methods and custom data tip.

OBJ = EnsemblePlot(NAMES, T, X, Y) plots the columns of matrix Y versus

the columns of matrix X as individual members of an ensemble. Note,

the T matrix, intended to represent time, must still be provided to

support interpolation and statistics calculation across the ensemble.

OBJ = EnsemblePlot(NAMES, T, X, Y, Z) plots the columns of matrices

X, Y, and Z as individual 3-dimensional line members of an ensemble.

Note, any of the T, X, Y, or Z arguments in the syntax above can be a

vector which will be expanded to match the number of columns of a

matrix input, given its length matches the matrix number of rows.

OBJ = EnsemblePlot(___, Name, Value) specifies EnsemblePlot properties

and/or constructor arguments, using one or more name-value arguments.

- 'ScaleFactor' is a vector that scales the X, Y, and/or Z data for plotting only

- 'ScaleFactorAxis' is any combination of 'x', 'y', and 'z' which specifies the axis/axes to scale

- 'XOffset' is a matrix that offsets the X data for plotting only

- 'YOffset' is a matrix that offsets the Y data for plotting only

- 'ZOffset' is a matrix that offsets the Z data for plotting only

- 'InterpolationMethod' is any valid interpolation method argument for interp1 function

- 'ExtrapolationMethod' is any valid extrapolation strategy argument for interp1 function

One or more name-value arguments can also be used to specify Line

properties to control the appearance of the line object created.

OBJ = EnsemblePlot(Name, Value) constructs an empty EnsemblePlot object

to which data can be added later. This syntax can be useful to specify

Line properties prior to any data being plotted.

Inputs:

NAMES <1xN or Nx1 text vector>

- Character vector, cell array of character vectors, or string array

- Names are used to identify each member of the ensemble and will be

displayed in the custom data tip

T <1xM or Mx1 float vector, or MxN float matrix>

- When a Y argument is not provided, T represents the data plotted

along the x-axis of a 2-D plot

- Intended to represent time vector(s) that will be used to

interpolate the data matrices X, Y, Z when calculating statistics

across the ensemble

- An MxN float matrix can be padded with NaNs, if necessary

X <1xM or Mx1 float vector, or MxN float matrix>

- When a Y argument is not provided, X represents the data plotted

along the y-axis of a 2-D plot

- When a Y argument is provided, X represents the data plotted along

the x-axis of a 2-D or 3-D plot

- An MxN float matrix can be padded with NaNs, if necessary

Y (=[]) <1xM or Mx1 float vector, or MxN float matrix>

- Represents the data plotted along the y-axis of a 2-D or 3-D plot

- An MxN float matrix can be padded with NaNs, if necessary

Z (=[]) <1xM or Mx1 float vector, or MxN float matrix>

- Represents the data plotted along the z-axis of a 3-D plot

- An MxN float matrix can be padded with NaNs, if necessary

Name-Value Arguments:

'ScaleFactor' (=1) <float vector>

- Specifies the scale factor(s) to use for scaling the X, Y, and/or Z

data for plotting purposes

- Can contain positive, negative, or both positive and negative values

'ScaleFactorAxis' (='xyz') <text scalar>

- Non-empty character vector or string scalar

- Can only be some combination of the letters 'x', 'y', and 'z'

- Specifies which axis, or axes, the scale factor argument is applied to

'XOffset', 'YOffset', 'ZOffset' (=[]) <1xM or Mx1 float vector, or MxN float matrix>

- Specifies the offset for the corresponding X, Y, or Z data for each

member of the ensemble for plotting purposes

- Data is scaled prior to being offset

- Provided so a time-varying offset can be used for plotting without

affecting the data scaling or statistics calculation

Outputs:

OBJ <1x1 EnsemblePlot object handle>

- The EnsemblePlot object provides access to the primitive line

object handles, through the following properties, so their

appearance can be changed after creation, if desired.

* 'Line' is the scalar line object handle that plots the shown data

* 'HighlightLine' is the scalar line object handle that plots the

subset of data that is desired to be highlighted

* 'StatisticLines' is the array of line object handles that plot

the desired statistics calculated from the shown data

Methods:

- Add Add members to the ensemble.

- Remove Remove members from the ensemble.

- Show Show members of the ensemble.

- Hide Hide members of the ensemble.

- Highlight Add line to highlight members of the ensemble.

- Unhighlight Unhighlight members of the ensemble.

- GetMemberNames Return ensemble member names.

- ExportData Return ensemble data.

- AddStatistic Add line for statistic computed from ensemble data.

- RemoveStatistic Remove statistic lines.

- GetStatisticNames Return statistic line names.

Examples:

% Construct an empty EnsemblePlot object that establishes the properties of

% the line object that will be created

f = figure;

a = axes(f, 'NextPlot', 'add');

h1 = EnsemblePlot('Parent', a, 'Color', 'b', 'DisplayName', 'Sinusoids');

for i = 1:20

% Create example data to plot

t = linspace(0, 2*pi, randi([80,120]));

x = sin(t - 0.2*i);

% Add a member to the ensemble

h1.Add(sprintf('Case %d',i), t, x);

end

legend(a, 'show');

% Custom data tip identifies the member of the ensemble by name

datatip(h1.Line, 2, 0);

% Data for the entire ensemble can be exported

exportdata1 = h1.ExportData('cell');

% If matrices of ensemble data are available, then they can be directly

% provided to the constructor (or Add method)

f = figure;

a = axes(f, 'NextPlot', 'add');

h2 = EnsemblePlot(exportdata1{:}, 'Parent', a, 'Color', 'b', 'DisplayName', 'Sinusoids');

legend(a, 'show');

See also: plot, matlab.graphics.chart.primitive.Line, DataTipTemplate, dataTipTextRow