Can someone explain this function?

I am currently trying to use the boundedline function to plots 95% confidence intervals (seen below). I have sucessfully managed to plot something but I use a random number for 'b'. Can someone explain what b means here? I don't understand what is written in the help manual.

boundedline Plot a line with shaded error/confidence bounds

[hl, hp] = boundedline(x, y, b)
[hl, hp] = boundedline(x, y, b, linespec)
[hl, hp] = boundedline(x1, y1, b1, linespec1,  x2, y2, b2, linespec2)
[hl, hp] = boundedline(..., 'alpha')
[hl, hp] = boundedline(..., ax)
[hl, hp] = boundedline(..., 'transparency', trans)
[hl, hp] = boundedline(..., 'orientation', orient)
[hl, hp] = boundedline(..., 'cmap', cmap)

Input variables:

    x, y:       x and y values, either vectors of the same length, matrices
                of the same size, or vector/matrix pair where the row or
                column size of the array matches the length of the vector
                (same requirements as for plot function).

    b:          npoint x nside x nline array.  Distance from line to
                boundary, for each point along the line (dimension 1), for
                each side of the line (lower/upper or left/right, depending
                on orientation) (dimension 2), and for each plotted line
                described by the preceding x-y values (dimension 3).  If
                size(b,1) == 1, the bounds will be the same for all points
                along the line.  If size(b,2) == 1, the bounds will be
                symmetrical on both sides of the lines.  If size(b,3) == 1,
                the same bounds will be applied to all lines described by
                the preceding x-y arrays (only applicable when either x or
                y is an array).  Bounds cannot include Inf, -Inf, or NaN,

    linespec:   line specification that determines line type, marker
                symbol, and color of the plotted lines for the preceding
                x-y values.

    'alpha':    if included, the bounded area will be rendered with a
                partially-transparent patch the same color as the
                corresponding line(s).  If not included, the bounded area
                will be an opaque patch with a lighter shade of the
                corresponding line color.

    ax:         handle of axis where lines will be plotted.  If not
                included, the current axis will be used.

    transp:     Scalar between 0 and 1 indicating with the transparency or
                intensity of color of the bounded area patch. Default is
                0.2.

    orient:     'vert': add bounds in vertical (y) direction (default)
                'horiz': add bounds in horizontal (x) direction 

    cmap:       n x 3 colormap array.  If included, lines will be colored
                (in order of plotting) according to this colormap,
                overriding any linespec or default colors.

I have 2 time series, time and data (1x663, 1x663) which I am using for x & y.

thanks, Michael

Answer 1

[Ishaan]

Hey @Michael,

I see that you intend to understand what the 3rd parameter (“b”) in “boundedline” function refers to.

As you know, the “boundedline” function is used to plot lines with shaded error or confidence bounds. The “b” parameter there specifies how far the shaded area (representing error or confidence bounds) extends from the main line you are plotting. It defines the "thickness" of the shaded region around the line.

Formally, the “b” parameter specifies the distance from the line to the boundary for each point along the line. It can account for the lower and upper bounds (or left and right, depending on orientation) and can vary for each line if multiple lines are plotted.

In essence, b controls how the shaded error/confidence region looks around your plotted line.

The “b” parameter is a multidimensional array with the following dimensions:

• Dimension 1 (npoint): Number of points along the line (should match the length of your x and y vectors).
• Dimension 2 (nside): Number of sides for the bounds (typically 2, for lower and upper bounds).
• Dimension 3 (nline): Number of lines being plotted (usually 1 for a single line)

Here are a few different scenarios showcasing the usage of “b”:

• Same Bounds for All Points: If size(b,1) == 1, the same bounds will apply to all points along the line. In this case, b could be a 1x2x1 array, where the two elements represent the symmetrical bounds.

% Setup 
n = 500; 
x = 1:n; 
y = cumsum(randn(1, n)); 
% Definition of b 
constant_bound = 3; 
b = repmat(constant_bound, 1, 2); 
% Plot 
boundedline(x, y, b, '-r', 'alpha'); 

• Symmetrical Bounds: If size(b,2) == 1, the bounds are symmetrical on both sides of the line. This means you can provide a single value for both lower and upper bounds for each point.

% Setup 
n = 500; 
x = 1:n; 
y = cumsum(randn(1, n)); 
% Definition of b 
varying_bound = 1 + 1.5 * (1:n) / n; 
b = varying_bound'; 
% Plot 
boundedline(x, y, b, '-g', 'alpha'); 

• Asymmetrical Bounds: If size(b,2) != 1, the bounds are asymmetrical around the line. This means you can provide 2 different values for lower and upper bounds respectively for each point.

% Setup 
n = 500; 
x = 1:n; 
y = cumsum(randn(1, n)); 
% Definition of b 
lower_bound = 2 + 1 * (1:n) / n; 
upper_bound = 1 + 2 * (n:-1:1) / n; 
b = [lower_bound; upper_bound]'; 
% Plot 
boundedline(x, y, b, '-b', 'alpha'); 

• Uniform Bounds Across Lines: If size(b,3) == 1, the same bounds apply to all lines described by the preceding x-y arrays.

% Setup 
n = 500; 
x = 1:n; 
y1 = randn(1, n); 
y2 = cumsum(y1); 
% Definition of b 
constant_bound = 3; 
b = repmat(constant_bound, n, 2, 1); 
% Plot 
boundedline(x, [y1; y2]', b, '-m', 'alpha'); 

The “b” parameter is crucial for defining how the shaded error or confidence bounds are displayed around your plotted line. By adjusting the dimensions of “b”, you can control whether the bounds are constant, symmetrical, asymmetrical, or uniform across multiple lines.

Hope this clarifies the use of “b” parameter in “boundedline” function.