Detects pulses in a Wave using the method described in Dietrich et al (2004) doi:10.1016/j.patcog.2004.04.004.
Usage
pd_dietrich2004(
wave,
U = 120,
gamma = 0.05,
alpha = 1.4,
scaling = 32,
V = 480,
psi = 1,
dt = 1,
filter = TRUE,
delta = 500,
band = c(2000, 11000)
)Arguments
- wave
A Wave object
- U
Length in samples of the short window the pulse energy is computed over.
- gamma
Where
thetasits between the smallest and the largest pulse energy, between 0 and 1.- alpha
Multiplier giving the upper threshold
F_afrom the lower thresholdF_1. Values above one putF_aaboveF_1.- scaling
Divisor applied to the long window energy before it is added to
theta.- V
Length in samples of the long window the reference level is computed over. Expected to be longer than
U.- psi
Number of samples after the
F_1crossing within which the energy must also crossF_afor a pulse to be reported. The paper names this parameter but never gives it a value.- dt
The step the state machine takes through the wave, in samples. A boundary can only be reported on this grid. The paper names this parameter but never gives it a value either; see the details.
- filter
Whether to normalise and bandpass filter the wave first, which is the first step of the method.
FALSEcomputes the energy from the wave as supplied.- delta
Half the width of the passband, in Hz. The paper gives no value for this, only that the filter is a highly selective one.
- band
The frequency range the weighting
Wof equation 2 is defined over, as a pair in Hz, orNULLto search the whole spectrum for the loudest frequency. The default is the frequency range of cricket song, which section 1 of the paper gives as 2 to 11 kHz and which is what the paper's ownWis a density over. A wave of some other animal needs its range given here.
Details
The short term energy is computed over a window of U samples (equation 5 of
the paper) and over a longer window of V samples, which gives a local
reference level. Two thresholds are derived from the long window energy
(equation 7), F_1 = theta + e_v/scaling and
F_a = theta + alpha*e_v/scaling, where theta is the lower energy bound of
equation 8. As alpha is greater than one, F_a is the upper of the two.
Algorithm 1 of the paper then walks the wave a sample at a time. A candidate
pulse opens at the sample where the energy first rises above F_1, and is
confirmed only if the energy also rises above F_a within psi samples of
that crossing. The sample reported is the F_1 crossing that opened the
candidate, not the F_a crossing that confirmed it. Where F_a is not
reached in time the candidate is abandoned and the next sample above F_1
opens a new one, so a larger psi lets a slow attack be reported from
further back. Once a pulse has been reported, no further pulse is reported
until the energy falls below F_1 again.
The paper says only that a similar algorithm estimates the offsets. Here the
same scan is run over the wave in reverse, so an offset closes a run above
F_1 that F_a confirmed within psi samples of its end. Both boundaries
are therefore measured at F_1 and a pulse length is its width at F_1.
Section 2 is two steps, and the segmentation above is the second. The first,
done here unless filter is FALSE, divides the wave by its maximum norm
(equation 1), finds the frequency omega carrying the most energy, weighted
by a density W over the frequencies the sound can occupy (equation 2), and
removes everything further than delta from it (equations 3 and 4). This is
what frees the energy of the sounds of the environment before any of it is
thresholded. The energies and thresholds returned are then in the units of
the normalised signal rather than of the wave as supplied. Normalisation on
its own changes no boundary, as theta, F_1 and F_a are all linear in
the amplitude of the wave.
band is what keeps that first step useful, and it is worth setting for the
animal in hand. It gives the support of W, and so the range equation 2 is
allowed to choose from. Left to the whole spectrum, the loudest frequency of
a field recording is usually wind or handling noise well below the song, and
the filter then keeps that and discards the song: on a wave of 5 kHz pulses
over a 300 Hz drone, searching the whole spectrum reported 593 pulses, one
for each half cycle of the drone, where the cricket range reported the 5 that
are there.
Three of the method's parameters have no value anywhere in the paper, and
their defaults here are this package's rather than Dietrich's: psi, which
is named only in the prose and in Algorithm 1; delta, described only as
making a highly selective filter; and dt, the step of Algorithm 1. The one
candidate for dt is a row of Table 1 reading beta = U/4 among the
segmentation parameters, under a symbol Algorithm 1 does not use and which is
the sonogram overlap everywhere else in the paper, so U/4 is offered rather
than assumed and the default is one sample.
Onsets and offsets follow the convention described under pulseDetection(),
and the windowed energy displaces each boundary outward in the way described
under pd_simple(). The one point on which this function parts company with
that convention, and with pd_simple() and pd_threshold(), is a sample
whose energy is exactly equal to a threshold. The paper's comparisons are not
strict, so such a sample is part of a pulse, and a silent or constant
amplitude wave, whose every energy is exactly equal to both thresholds, is
reported as one pulse spanning the analysed range. The other two detectors
report no pulse in it.
