Main Content

buffer

Buffer signal vector into matrix of data frames

collapse all in page

Syntax

y = buffer(x,n)
y = buffer(x,n,p)
y = buffer(x,n,p,opt)
[y,z] = buffer(___)
[y,z,opt] = buffer(___)

Description

y = buffer(x,n) partitions a length-L signal x into nonoverlapping data segments (frames) of length n.

y = buffer(x,n,p) overlaps or underlaps successive frames in the output matrix by p samples.

y = buffer(x,n,p,opt) specifies a vector of samples to precede x(1) in an overlapping buffer, or the number of initial samples to skip in an underlapping buffer.

example

[y,z] = buffer(___) partitions a length-L signal x into frames of length n, and outputs only the full frames in y. The vector z contains the remaining samples. This syntax can include any combination of input arguments from the previous syntaxes.

example

[y,z,opt] = buffer(___) returns the last p samples of an overlapping buffer in output opt.

Examples

collapse all

Open Live Script

Create a buffer containing 100 frames, each with 10 samples.

data = buffer(1:1000,10);

Take the frames (columns) in the matrix data to be the sequential outputs of a data acquisition board sampling a physical signal: data(:,1) is the first A/D output, containing the first 11 signal samples, data(:,2) is the second output, containing the next 11 signal samples, and so on.

You want to rebuffer this signal from the acquired frame size of 11 to a frame size of 4 with an overlap of 1. Call buffer to operate on each successive input frame, using the opt parameter to maintain consistency in the overlap from one buffer to the next.

Set the buffer parameters. Specify a value of –5 for y(1). The carryover vector is empty initially.

n = 4;
p = 1;
opt = -5;
z = [];

Now repeatedly call buffer, each time passing in a new signal frame (column) from data. Overflow samples (returned in z) are carried over and prepended to the input in the subsequent call to buffer.

For the first four iterations, show the input frame [z;x]', the input and output values of opt, the output buffer y, and the overflow z. The size of the output matrix, y, can vary by a single column from one iteration to the next. This is typical for buffering operations with overlap or underlap.

for i = 1:size(data,2)
    x = data(:,i);
    [y,z,oppt] = buffer([z;x],n,p,opt);
    if i <= 4
        disp("Iteration " + i)
        ifrm = [z;x]'
        opts = [opt oppt]
        y
        z
        disp("-----------")
    end
    opt = oppt;
end
Iteration 1

ifrm = 1×11

    10     1     2     3     4     5     6     7     8     9    10


opts = 1×2

    -5     9


y = 4×3

    -5     3     6
     1     4     7
     2     5     8
     3     6     9


z = 
10

-----------

Iteration 2

ifrm = 1×12

    19    20    11    12    13    14    15    16    17    18    19    20


opts = 1×2

     9    18


y = 4×3

     9    12    15
    10    13    16
    11    14    17
    12    15    18


z = 2×1

    19
    20


-----------

Iteration 3

ifrm = 1×10

    21    22    23    24    25    26    27    28    29    30


opts = 1×2

    18    30


y = 4×4

    18    21    24    27
    19    22    25    28
    20    23    26    29
    21    24    27    30


z =

  0x1 empty double column vector

-----------

Iteration 4

ifrm = 1×11

    40    31    32    33    34    35    36    37    38    39    40


opts = 1×2

    30    39


y = 4×3

    30    33    36
    31    34    37
    32    35    38
    33    36    39


z = 
40

-----------
Open Live Script

Create a buffer containing 100 frames, each with 9 samples.

data = buffer(1:900,9);

Take data(:,1) as the first A/D output, containing the first 11 signal samples, data(:,2) as the second output, containing the next 11 signal samples, and so on.

You want to rebuffer this signal from the acquired frame size of 11 to a frame size of 4 with an underlap of 2. To do this, you will repeatedly call buffer to operate on each successive input frame, using the opt parameter to maintain consistency in the underlap from one buffer to the next.

Set the buffer parameters. Specify a new frame size of 4 and an underlap of –2. Skip the first input element, x(1), by setting opt to 1. The carryover vector is empty initially.

n = 4;
p = -2;
opt = 1;
z = [];

Now repeatedly call buffer, each time passing in a new signal frame (column) from data. Overflow samples (returned in z) are carried over and prepended to the input in the subsequent call to buffer.

For the first three iterations, show the input frame [z';x]', the input and output values of opt, the output buffer y, and the overflow z. The size of the output matrix, y, can vary by a single column from one iteration to the next. This is typical for buffering operations with overlap or underlap.

for i = 1:size(data,2)
   x = data(:,i);
   [y,z,oppt] = buffer([z';x],n,p,opt);
   if i <= 3
       disp("Iteration "+ i)
       ifrm = [z';x]'
       opts = [opt oppt]
       y
       z
       disp("-----------")
   end
   opt = oppt;
end
Iteration 1

ifrm = 1×11

     8     9     1     2     3     4     5     6     7     8     9


opts = 1×2

     1     0


y = 4×1

     2
     3
     4
     5


z = 1×2

     8     9


-----------

Iteration 2

ifrm = 1×9

    10    11    12    13    14    15    16    17    18


opts = 1×2

     0     1


y = 4×2

     8    14
     9    15
    10    16
    11    17


z =

  1x0 empty double row vector

-----------

Iteration 3

ifrm = 1×11

    26    27    19    20    21    22    23    24    25    26    27


opts = 1×2

     1     0


y = 4×1

    20
    21
    22
    23


z = 1×2

    26    27


-----------

Input Arguments

collapse all

Input signal, specified as a vector.

Frame length, specified as a positive integer scalar.

Number of overlapping or underlapping samples, specified as an integer scalar.

  • For 0 < p < n (overlap), buffer repeats the final p samples of each frame at the beginning of the following frame. For example, if x = 1:30 and n = 7, an overlap of p = 3 looks like this.

    Framed signal with p overlapping samples between consecutive frames.

    The first frame starts with p zeros (the default initial condition), and the number of columns in y is ceil(L/(n-p)).

  • For p < 0 (underlap), buffer skips p samples between consecutive frames. For example, if x = 1:30 and n = 7, a buffer with underlap of p = -3 looks like this.

    Framed signal with p skipping (underlapping) samples between consecutive frames.

    The number of columns in y is ceil(L/(n-p)).

Option, specified as a vector or integer.

  • For 0 < p < n (overlap), opt specifies a length-p vector to insert before x(1) in the buffer. This vector can be considered an initial condition, which is needed when the current buffering operation is one in a sequence of consecutive buffering operations. To maintain the desired frame overlap from one buffer to the next, opt should contain the final p samples of the previous buffer in the sequence. See Continuous Buffering below.

    By default, opt is zeros(p,1) for an overlapping buffer. Set opt to "nodelay" to skip the initial condition and begin filling the buffer immediately with x(1). In this case, L must be length(p) or longer. For example, if x = 1:30 and n = 7, a buffer with overlap of p = 3 looks like this.

    Framed signal with p overlapping samples between consecutive frames. When opt is "nodelay".no trailing zeros show at the beginning of the first frame.

  • For p < 0 (underlap), opt is an integer value in the range [0,-p] specifying the number of initial input samples, x(1:opt), to skip before adding samples to the buffer. The first value in the buffer is therefore x(opt+1). By default, opt is zero for an underlapping buffer.

    This option is especially useful when the current buffering operation is one in a sequence of consecutive buffering operations. To maintain the desired frame underlap from one buffer to the next, opt should equal the difference between the total number of points to skip between frames (p) and the number of points that were available to be skipped in the previous input to buffer. If the previous input had fewer than p points that could be skipped after filling the final frame of that buffer, the remaining opt points need to be removed from the first frame of the current buffer. See Continuous Buffering for an example of how this works in practice.

Output Arguments

collapse all

Data frame, returned as a matrix. Each data frame occupies one column of y, which has n rows and ceil(L/n) columns. If L is not evenly divisible by n, the last column is zero-padded to length n.

  • If y is an overlapping buffer, it has n rows and m columns, where m = floor(L/(n-p)) when length(opt) = p or m = ceil((L-p)/(n-p)) when opt = "nodelay".

  • If y is an underlapping buffer, it has n rows and m columns, where m = floor((L-opt)/(n-p)) + (rem((L-opt),(n-p)) >= n).

Remaining samples, returned as a vector. If the number of samples in the input vector (after the appropriate overlapping or underlapping operations) exceeds the number of places available in the n-by-m buffer, the remaining samples in x are output in vector z, which for an overlapping buffer has length L - m*(n-p) when length(opt) = p or L - ((m-1)*(n-p)+n) when opt = "nodelay", and for an underlapping buffer has length (L-opt) - m*(n-p).

  • If y is an overlapping buffer or a nonoverlapping buffer, then z has the same orientation (row or column) as x.

  • If y is an underlapping buffer, then z is returned as a row vector.

If there are no remaining samples in the input after the buffer with the specified overlap or underlap is filled, z is an empty vector.

Last p samples, returned as a vector. In an underlapping buffer, opt is the difference between the total number of points to skip between frames (-p) and the number of points in x that were available to be skipped after filling the last frame. In a sequence of buffering operations, the opt output from each operation should be used as the opt input to the subsequent buffering operation. This ensures that the desired frame overlap or underlap is maintained from buffer to buffer, as well as from frame to frame within the same buffer. See Continuous Buffering for an example of how this works in practice.

  • For 0 < p < n (overlap), opt (as an output) contains the final p samples in the last frame of the buffer. This vector can be used as the initial condition for a subsequent buffering operation in a sequence of consecutive buffering operations. This allows the desired frame overlap to be maintained from one buffer to the next.

  • For p < 0 (underlap), opt (as an output) is the difference between the total number of points to skip between frames (p) and the number of points in x that were available to be skipped after filling the last frame: opt = m*(n-p) + opt - L, where opt on the right is the input argument to buffer, and opt on the left is the output argument. z is the empty vector. Here m is the number of columns in the buffer, with m = floor((L-opt)/(n-p)) + (rem((L-opt),(n-p))>=n).

    Note that for an underlapping buffer output, opt is always zero when output z contains data.

    The opt output for an underlapping buffer is especially useful when the current buffering operation is one in a sequence of consecutive buffering operations. The opt output from each buffering operation specifies the number of samples that need to be skipped at the start of the next buffering operation to maintain the desired frame underlap from one buffer to the next. If fewer than p points were available to be skipped after filling the final frame of the current buffer, the remaining opt points need to be removed from the first frame of the next buffer.

Diagnostics

Error messages are displayed when p ≥n or length(opt)≠length(p) in an overlapping buffer case:

Frame overlap P must be less than the buffer size N.
Initial conditions must be specified as a length-P vector.

More About

collapse all

Continuous Buffering

In a continuous buffering operation, the vector input to the buffer function represents one frame in a sequence of frames that make up a discrete signal. These signal frames can originate in a frame-based data acquisition process, or within a frame-based algorithm like the FFT.

For example, you might acquire data from an A/D card in frames of 64 samples. In the simplest case, you could rebuffer the data into frames of 16 samples; buffer with n = 16 creates a buffer of four frames from each 64-element input frame. The result is that the signal of frame size 64 has been converted to a signal of frame size 16; no samples were added or removed.

In the general case where the original signal frame size, L, is not equally divisible by the new frame size, n, the overflow from the last frame needs to be captured and recycled into the following buffer. You can do this by iteratively calling buffer on input x with the two-output-argument syntax:

[y,z] = buffer([z;x],n)     % x is a column vector.
[y,z] = buffer([z,x],n)     % x is a row vector.

This simply captures any buffer overflow in z, and prepends the data to the subsequent input in the next call to buffer. Again, the input signal, x, of frame size L, has been converted to a signal of frame size n without any insertion or deletion of samples.

Note that continuous buffering cannot be done with the single-output syntax y = buffer(...), because the last frame of y in this case is zero padded, which adds new samples to the signal.

Continuous buffering in the presence of overlap and underlap is handled with the opt parameter, which is used as both an input and output to buffer. The two examples on this page demonstrate how the opt parameter should be used.

Extended Capabilities

Version History

Introduced before R2006a

expand all

See Also