Syntax Supported by the IML Procedure and the iml Action

A plateau is a set of consecutive local maxima.

You can associate two bases with each peak: one to the left of the peak and one to the right. The first base is found by locating the smallest value between a peak and its two neighboring peaks. If the first base point is on the left side of the peak, the second base is the nearest local minimum on the right side of the peak. Conversely, if the first base point is on the right side of the peak, the second base is the nearest local minimum on the left side.

Figure 272 shows an example of a peak and its associated bases. In the figure, is the left-neighbor peak, is the right-neighbor peak, is the minimum point between the peak and its left-neighbor peak, and is the minimum point between the peak and its right-neighbor peak. The value of the series at is less than the value of the series at . Thus, for the peak p, is the first base, and is the second base.

The width of a peak is the distance, measured in points, from the right base to the left base of the peak.

Associated with each peak is an absolute height, which is the difference between the peak value and the value at the first base. In the PEAKLOC function, you can specify a fraction of height that is used to determine the width of the peak according to the following criteria:

Figure 273 shows the width (w_max) of peak p when the fraction is 1. In the figure, the absolute height of peak p is h, which is the difference between the peak value and the value of its first base. Figure 274 demonstrates the width of the peak when the fraction is 0.7 and 0.9. Note that the base points of the peak are adjusted according to the specified fraction of height and calculated using linear interpolation. In this figure, w_0.7 and w_0.9 are the width values when the specified fraction of height is 0.7 and 0.9, respectively. In this figure, and are the bases of peak p when the fraction of height is 1, and are the bases of peak p when the fraction of height is 0.9, and and are the bases of peak p when the fraction of height is 0.7.

Prominence is a quantitative measure of how much a peak stands out among a cluster group of peaks. Associated with each peak are a prominence height (usually called the prominence) and a prominence width. To define these values, first define the right horizontal crossing and the left horizontal crossing for each peak.

The horizontal crossings are the closest points to the left and to the right of the peaks that have greater values than the peak. If no greater values are present, the left horizontal crossing is the beginning of the series, and the right horizontal crossing is the end of the series. Next, the left minimum point is calculated as the point with the minimum value between the peak and the left horizontal crossing. Similarly, the right minimum point is calculated as the point with the minimum value between the peak and the right horizontal crossing. Between the left minimum point and the right minimum point, the point with a higher value would be the first prominence base of the peak. The second base prominence of a peak is the first point on the opposite side of the peak that has the same height as the first prominence base. The second prominence base is calculated using linear interpolation.

Figure 275 demonstrates the definition of the prominence base points. The prominence of a peak is the value of the peak minus the value of the first prominence base, as shown in Figure 275. The maximum prominence width of a peak is the distance, measured in points, from the right prominence base to the left prominence base of the peak. In this figure, is the left horizontal crossing point, is the right horizontal crossing point, is the point that has the minimum value between p and , and is the point that has the minimum value between p and . The value of the series at is greater than the value of the series at . As a result, is the first (in this case, right) prominence base, and is the second (in this case, left) prominence base. In this figure, W is the maximum width of the prominence, and L is the prominence of the peak p. Like the peak width, the prominence width is affected by the fraction of height parameter.

A prominence group is defined as a single peak or a group of peaks. Peak A is in the same prominence group as peak B if the points between the left and right prominence bases of A overlap the points between the left and right prominence bases of B. A peak cannot belong to more than one prominence group. Figure 276 demonstrates the prominence groups for a series.

Peak A is a parent of peak B if (1) A and B belong to the same prominence group, (2) A has higher prominence than B, and (3) points between the left and right prominence bases of A overlap the points between the left and right prominence bases of B. If there is more than one peak that has all three of these conditions, then A is the peak with the lowest prominence. Note that if there are no peaks with higher prominence within the prominence group of peak B, then B is its own parent peak.

Figure 276 shows a series that has four prominence groups. The value of peak is the same as the value of peak . In this series, is in the first prominence group; peaks , , and are in the second prominence group; peak is in the third prominence group; and peak is in the fourth prominence group. This figure also shows the prominence and width of each peak. In this figure, peaks , , , and are their own parents. Peak is the parent of peak , and peak is the parent of peak .

The required input arguments to the PEAKLOC function are as follows:

The PEAKLOC function also supports two optional vectors of parameters. The param1 argument is a two-element numerical vector. The meaning of each element follows:

The param2 argument is a two-element character vector. The case of the values (lowercase or uppercase) does not matter. The meaning of each element follows:

The following example creates a signal whose peaks are detected by using the PEAKLOC function. Figure 277 plots the series and overlays the peaks.

series = {3 4 6.5 7 6 5 4 5 6 7.5 8 7.5 6 5 4 3
          2 3 4 5 5 2 3.5 5.5 6 5.5 4 };
locs = peakloc(series);

You can plot the signal and the detected peaks as follows:

x = 1:ncol(series);
peaks = j(1, ncol(series), .);
peaks[locs] = series[locs];

title "Peakloc Example";
call series(x, series) grid={x y}
   scatterX=x scatterY=peaks
   scatterOption="markerattrs=(size=12)"
   scatterOnTop=0;

The following statements set the filter for the minimum height to the value 7. The PEAKLOC function returns only peaks that are at least 7 units in height. The series and the peaks are shown in Figure 278.

filteredPeaks = peakloc(series, {7});
filteredPeakVals = j(1, ncol(series), .);
filteredPeakVals[filteredPeaks] = series[filteredPeaks];

title "Filtered Peaks";
call series(x, series) grid={x y}
   scatterX=x scatterY=filteredPeakVals
   scatterOption="markerattrs=(size=12)"
   scatterOnTop=0;