buffer: Buffer signal vector into matrix of data segments

In gjmvanboxtel/gsignal: Signal Processing

Buffer signal vector into matrix of data segments

Description

Partition a signal vector into nonoverlapping, overlapping, or underlapping data segments.

Usage

buffer(x, n, p = 0, opt, zopt = FALSE)

Arguments

x	The data to be buffered.
n	The number of rows in the produced data buffer. This is an positive integer value and must be supplied.
p	An integer less than n that specifies the under- or overlap between column in the data frame. Default 0.
opt	In the case of an overlap, opt can be either a vector of length p or the string 'nodelay'. If opt is a vector, then the first p entries in y will be filled with these values. If opt is the string 'nodelay', then the first value of y corresponds to the first value of x. In the case of an underlap, opt must be an integer between 0 and -p. The represents the initial underlap of the first y. The default value for opt the vector matrix (0L, 1, p) in the case of an overlap, or 0 otherwise.
zopt	Logical. If TRUE, return values for z and opt in addition to y. Default is FALSE (return only y).

Details

y <- buffer(x, n) partitions a signal vector x of length L into nonoverlapping data segments of length n. Each data segment occupies one column of matrix output 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.

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

• For 0 < p < n (overlap), buffer repeats the final p samples of each segment at the beginning of the following segment. See the example where x = 1:30, n = 7, and an overlap of p = 3. In this case, the first segment 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 segments. See the example where x = 1:30, n = 7, and p = -3. The number of columns in y is ceil(L / (n - p)).

In y <- buffer(x, n, p, opt), 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.

• For 0 < p < n (overlap), opt specifies a vector of length p 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 segment overlap from one buffer to the next, opt should contain the final p samples of the previous buffer in the sequence. 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. See the example where x = 1:30, n = 7, p = 3, and opt = "nodelay".

• 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].

The opt 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.

buf <- buffer(..., zopt = TRUE) returns the last p samples of a overlapping buffer in output buf$opt. In an underlapping buffer, buf$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:

• For 0 < p < n (overlap), buf$opt 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. See Continuous Buffering below.

• For p < 0 (underlap), buf$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: buf$opt = m*(n-p) + opt - L where opt on the right is the input argument to buffer, and buf$opt on the left is the output argument. Note that for an underlapping buffer output buf$opt is always zero when output buf$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 buf$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.

In a sequence of buffering operations, the buf$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 below for an example of how this works in practice.

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.
As an 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 zopt parameter set to TRUE. This simply captures any buffer overflow in buf$z, and prepends the data to the subsequent input in the next call to buffer.
Note that continuous buffering cannot be done without the zopt parameter being set to TRUE, because the last frame of y (buf$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 (opt and output (buf$opt) to buffer. The two examples on this page demonstrate how the opt parameter should be used.

Value

If zopt equals FALSE (the default), this function returns a single numerical array containing the buffered data (y). If zopt equals TRUE, then a list containing 3 variables is returned: y: the buffered data, z: the over or underlap (if any), opt: the over- or underlap that might be used for a future call to buffer to allow continuous buffering.

Author(s)

David Bateman, [e-mail].
Conversion to R by Geert van Boxtel, [e-mail]

Examples

## Examples without continuous buffering
y <- buffer(1:10, 5)
y <- buffer(1:10, 4)
y <- buffer(1:30, 7, 3)
y <- buffer(1:30, 7, -3)
y <- buffer(1:30, 7, 3, 'nodelay')

## Continuous buffering examples
# with overlap:
data <- buffer(1:1100, 11)
n <- 4
p <- 1
buf <- list(y = NULL, z = NULL, opt = -5)
for (i in 1:ncol(data)) {
  x <- data[,i]
  buf <- buffer(x = c(buf$z,x), n, p, opt=buf$opt, zopt = TRUE)
}
# with underlap:
data <- buffer(1:1100, 11)
n <- 4
p <- -2
buf <- list(y = NULL, z = NULL, opt = 1)
for (i in 1:ncol(data)) {
  x <- data[,i]
  buf <- buffer(x = c(buf$z,x), n, p, opt=buf$opt, zopt = TRUE)
}

gjmvanboxtel/gsignal documentation built on Nov. 22, 2023, 8:19 p.m.