15.5.228 find_max

find_max(data [, diagonal=diagonal, /degree, /subgrid])

By default, seeks local maxima in data and returns their values. data must be numerical and may have multiple dimensions.

If diagonal is specified, then it must be an array with one element per dimension of data. The elements that are equal to 0 indicate which dimensions are not checked for a local maximum. The elements that are equal to 1 and 2 (after conversion to type long) indicate in which dimensions checking is performed. The elements that are equal to 2 indicate in which dimensions checked directions may be diagonal. Elements equal to 1 indicate that no diagonals are allowed in those dimensions. All such directions either have non-zero coordinate offsets only in those dimensions, or have only a single non-zero coordinate offset (i.e., a non-diagnonal or orthogonal direction). Only approved directions are checked. If diagonal contains n1 ones and n2 twos, then the number of directions per data element that will be considered is equal to m = 2^n2 - 1 + n1.

For example, regard a two-dimensional array. We’ll call the first dimension the east-west direction and the second one the north-south dimension. Then, if diagonal = [1,0], values are returned for all points that are local maxima in the east-west direction without regards to any other direction. If diagonal = [1,1], then all points are approved that are local maxima in the east-west direction and also in the north-south direction, without regards to the other (northeast-southwest, southeast-northwest) directions. If diagonal = [2,2], then all directions are checked.

For a three-dimensional array, if diagonal = [2,2,1], then the only checked directions that have a non-zero third coordinate offset are those that are along the 3rd axis. If diagonal = [1,1,0], then only directions along (and not between) the first two axes are checked.

If /degree is specified, then the number of directions per data element where the data shows a local maximum is returned instead. This number always lies between 0 and the total number m of directions given above. find_max(data, /degree) eq m returns an array with 1s at all positions returned by find_max(data), but the latter form is considerably faster because for each element it stops checking as soon as a direction without a local maximum is found. For noise data in arbitrary numbers of dimensions, on average at most 2 local maximum determinations per data element are performed if /degree is not specified, compared to m, which is grows exponentially with the number of dimensions in the worst case, if /degree is specified.

If /subgrid is specified, then the value of the local maximum is taken from a quadratic hypersurface fitted to the local neighborhood of the local maximum.

The used algorithm decides whether a particular data point is a local maximum by looking at its nearest neighbors only. This means that it cannot decide if a region in which all adjacent data values are equal constitutes a local maximum. Such regions are ignored.

See also: local_max, find_maxloc, find_min