0
# Local Extrema Analysis
1
2
Functions for finding local minima and maxima in numeric data sequences, useful for signal processing and data analysis.
3
4
## Capabilities
5
6
### Local Extrema Detection
7
8
Test if a value is a local minimum or maximum among three consecutive values.
9
10
```typescript { .api }
11
/**
12
* Returns true if b is a local minima (a > b && b < c)
13
* Tests if the middle value is smaller than both neighbors
14
* @param a - Left neighbor value
15
* @param b - Center value to test
16
* @param c - Right neighbor value
17
* @returns True if b is a local minimum
18
*/
19
function isMinima(a: number, b: number, c: number): boolean;
20
21
/**
22
* Returns true if b is a local maxima (a < b && b > c)
23
* Tests if the middle value is larger than both neighbors
24
* @param a - Left neighbor value
25
* @param b - Center value to test
26
* @param c - Right neighbor value
27
* @returns True if b is a local maximum
28
*/
29
function isMaxima(a: number, b: number, c: number): boolean;
30
```
31
32
### Single Extrema Finding
33
34
Find the index of the first local minimum or maximum in an array.
35
36
```typescript { .api }
37
/**
38
* Returns index of the first local & internal minima in values array
39
* Searches in semi-open interval [from, to)
40
* @param values - Array of numeric values to search
41
* @param from - Start index (default: 0)
42
* @param to - End index exclusive (default: values.length)
43
* @returns Index of first minima, or -1 if none found
44
*/
45
function minimaIndex(values: number[], from?: number, to?: number): number;
46
47
/**
48
* Returns index of the first local & internal maxima in values array
49
* Searches in semi-open interval [from, to)
50
* @param values - Array of numeric values to search
51
* @param from - Start index (default: 0)
52
* @param to - End index exclusive (default: values.length)
53
* @returns Index of first maxima, or -1 if none found
54
*/
55
function maximaIndex(values: number[], from?: number, to?: number): number;
56
```
57
58
### Multiple Extrema Finding
59
60
Find all local minima and maxima indices in an array using generators.
61
62
```typescript { .api }
63
/**
64
* Returns generator yielding all minima indices in values array
65
* Searches in semi-open interval [from, to)
66
* @param values - Array of numeric values to search
67
* @param from - Start index (default: 0)
68
* @param to - End index exclusive (default: values.length)
69
* @returns Generator yielding indices of all minima
70
*/
71
function minimaIndices(values: number[], from?: number, to?: number): Generator<number>;
72
73
/**
74
* Returns generator yielding all maxima indices in values array
75
* Searches in semi-open interval [from, to)
76
* @param values - Array of numeric values to search
77
* @param from - Start index (default: 0)
78
* @param to - End index exclusive (default: values.length)
79
* @returns Generator yielding indices of all maxima
80
*/
81
function maximaIndices(values: number[], from?: number, to?: number): Generator<number>;
82
```
83
84
## Usage Examples
85
86
```typescript
87
import {
88
isMinima, isMaxima,
89
minimaIndex, maximaIndex,
90
minimaIndices, maximaIndices
91
} from "@thi.ng/math/extrema";
92
93
// Local extrema detection
94
isMinima(5, 2, 7); // true (2 < 5 and 2 < 7)
95
isMinima(2, 5, 7); // false (5 > 2, not a minimum)
96
isMaxima(2, 8, 3); // true (8 > 2 and 8 > 3)
97
98
// Sample data with peaks and valleys
99
const signal = [1, 3, 2, 6, 4, 8, 5, 7, 1];
100
101
// Find first extrema
102
minimaIndex(signal); // 2 (value 2 at index 2)
103
maximaIndex(signal); // 3 (value 6 at index 3)
104
105
// Find extrema in specific range
106
minimaIndex(signal, 3, 8); // 4 (value 4 at index 4)
107
maximaIndex(signal, 4, 8); // 5 (value 8 at index 5)
108
109
// Find all extrema
110
const allMinima = [...minimaIndices(signal)]; // [2, 4, 8]
111
const allMaxima = [...maximaIndices(signal)]; // [1, 3, 5, 7]
112
113
// Get actual extrema values
114
const minimaValues = allMinima.map(i => signal[i]); // [2, 4, 1]
115
const maximaValues = allMaxima.map(i => signal[i]); // [3, 6, 8, 7]
116
117
// Practical applications
118
// Find peaks in audio signal
119
const findAudioPeaks = (samples: number[], threshold = 0.5) => {
120
return [...maximaIndices(samples)].filter(i => samples[i] > threshold);
121
};
122
123
// Find valleys in time series data
124
const findDataValleys = (timeSeries: number[]) => {
125
return [...minimaIndices(timeSeries)].map(i => ({
126
index: i,
127
value: timeSeries[i],
128
timestamp: i // or actual timestamp
129
}));
130
};
131
132
// Analyze signal characteristics
133
const analyzeSignal = (data: number[]) => {
134
const peaks = [...maximaIndices(data)];
135
const valleys = [...minimaIndices(data)];
136
137
return {
138
peakCount: peaks.length,
139
valleyCount: valleys.length,
140
avgPeakValue: peaks.reduce((sum, i) => sum + data[i], 0) / peaks.length,
141
avgValleyValue: valleys.reduce((sum, i) => sum + data[i], 0) / valleys.length
142
};
143
};
144
```