gsignal (version 0.3-1)

pulstran: Pulse train

Description

Generate a train of pulses based on samples of a continuous function.

Usage

pulstran(
  t,
  d,
  func,
  fs = 1,
  method = c("linear", "nearest", "cubic", "spline"),
  ...
)

Arguments

t

Time values at which func is evaluated, specified as a vector.

d

Offset removed from the values of the array t, specified as a real vector, matrix, or array. You can apply an optional gain factor to each delayed evaluation by specifying d as a two-column matrix, with offset defined in column 1 and associated gain in column 2. If you specify d as a vector, the values are interpreted as delays only.

func

Continuous function used to generate a pulse train based on its samples, specified as 'rectpuls', 'gauspuls', 'tripuls', or a function handle. If you use func as a function handle, you can pass the function parameters as follows: y <- pulstran(t, d, 'gauspuls', 10e3, bw = 0.5). This creates a pulse train using a 10 kHz Gaussian pulse with 50% bandwidth. Alternatively, func can be a prototype function, specified as a vector. The interval of the function 0 to (length(p) - 1) / fs, and its samples are identically zero outside this interval. By default, linear interpolation is used for generating delays.

fs

Sample rate in Hz, specified as a real scalar.

method

Interpolation method, specified as one of the following options:

"linear" (default)

Linear interpolation. The interpolated value at a query point is based on linear interpolation of the values at neighboring grid points in each respective dimension. This is the default interpolation method.

"nearest"

Nearest neighbor interpolation. The interpolated value at a query point is the value at the nearest sample grid point.

"cubic"

Shape-preserving piecewise cubic interpolation. The interpolated value at a query point is based on a shape-preserving piecewise cubic interpolation of the values at neighboring grid points.

"spline"

Spline interpolation using not-a-knot end conditions. The interpolated value at a query point is based on a cubic interpolation of the values at neighboring grid points in each respective dimension.

Interpolation is performed by the function 'interp1' function in the library 'pracma', and any interpolation method accepted by the function 'interp1' can be specified here.

...

Further arguments passed to func.

Value

Pulse train generated by the function, returned as a vector.

Details

Generate the signal y <- sum(func(t + d, ...)) for each d. If d is a matrix of two columns, the first column is the delay d and the second column is the amplitude a, and y <- sum(a * func(t + d)) for each d, a. Clearly, func must be a function which accepts a vector of times. Any extra arguments needed for the function must be tagged on the end.

If instead of a function name you supply a pulse shape sampled at frequency fs (default 1 Hz), an interpolated version of the pulse is added at each delay d. The interpolation stays within the the time range of the delayed pulse. The interpolation method defaults to linear, but it can be any interpolation method accepted by the function interp1

Examples

# NOT RUN {
## periodic rectangular pulse
t <- seq(0, 60, 1/1e3)
d <- cbind(seq(0, 60, 2), sin(2 * pi * 0.05 * seq(0, 60, 2)))
y <- pulstran(t, d, 'rectpuls')
plot(t, y, type = "l", xlab = "Time (s)", ylab = "Waveform",
     main = "Periodic rectangular pulse")

## assymetric sawtooth waveform
fs <- 1e3
t <- seq(0, 1, 1/fs)
d <- seq(0, 1, 1/3)
x <- tripuls(t, 0.2, -1)
y <- pulstran(t, d, x, fs)
plot(t, y, type = "l", xlab = "Time (s)", ylab = "Waveform",
     main = "Asymmetric sawtooth waveform")

## Periodic Gaussian waveform
fs <- 1e7
tc <- 0.00025
t <- seq(-tc, tc, 1/fs)
x <- gauspuls(t, 10e3, 0.5)
plot(t, x, type="l", xlab = "Time (s)", ylab = "Waveform",
     main = "Gaussian pulse")
ts <- seq(0, 0.025, 1/50e3)
d <- cbind(seq(0, 0.025, 1/1e3), sin(2 * pi * 0.1 * (0:25)))
y <- pulstran(ts, d, x, fs)
plot(ts, y, type = "l", xlab = "Time (s)", ylab = "Waveform",
     main = "Gaussian pulse train")

# Custom pulse trains
fnx <- function(x, fn) sin(2 * pi * fn * x) * exp(-fn * abs(x))
ffs <- 1000
tp <- seq(0, 1, 1/ffs)
pp <- fnx(tp, 30)
plot(tp, pp, type = "l",xlab = 'Time (s)', ylab = 'Waveform',
     main = "Custom pulse")
fs <- 2e3
t <- seq(0, 1.2, 1/fs)
d <- seq(0, 1, 1/3)
dd <- cbind(d, 4^-d)
z <- pulstran(t, dd, pp, ffs)
plot(t, z, type = "l", xlab = "Time (s)", ylab = "Waveform",
     main = "Custom pulse train")

## Generate the pulse train again, but now use the generating
## function as an input argument. Include the frequency and damping
## parameter in the function call. In this case, pulstran generates
## the pulse so that it is centered about zero.
y <- pulstran(t, dd, 'fnx', fn = 30)
plot(t, y, type = "l", xlab = "Time (s)", ylab = "Waveform",
     main = "Custom pulse train")

## Change Interpolation Method with Custom Pulse
## Generate a custom exponentially decaying sawtooth waveform of
## requency 0.25 Hz. The generating function has a second input argument
## that specifies a single value for the sawtooth frequency and the damping
## factor. Display a generated pulse, sampled at 0.1 kHz for 1 second, with
## a frequency and damping value equal to 50.

fnx <- function(x, fn) sawtooth(2 * pi * fn * 0.25 * x) * exp(-2 * fn * x^2)
fs <- 100
t <- seq(0, 1, 1/fs)
pp <- fnx(t, 50)
plot(t, pp, type = "l", xlab = "Time (s)", ylab = "Waveform")

## Use the pulstran function to generate a train of custom pulses.
## The train is sampled at 0.1 kHz for 125 seconds. The pulses occur
## every 25 seconds and have exponentially decreasing amplitudes. Specify
## the generated pulse as a prototype. Generate three pulse trains using the
## default linear interpolation method, nearest neighbor interpolation
## and piecewise cubic interpolation. Compare the pulse trains on a
##  single plot.
d <- cbind(seq(0, 125, 25), exp(-0.015 * seq(0, 125, 25)))
ffs <- 100
tp <- seq(0, 125, 1/ffs)

r <- pulstran(tp, d, pp)
y <- pulstran(tp, d, pp, method = 'nearest')
q <- pulstran(tp, d, pp, method = 'spline')
plot(tp, r, type = "l", xlab = "Time (s)", ylab = "Waveform")
lines(tp, y, col=2)
lines(tp, q, col=3)
legend ("bottomright", lty=1,
        legend=c("linear", "nearest neighbor", "spline"),
        col=1:3)

# }