Local Extrema Analysis

/**
 * Returns true if b is a local minima (a > b && b < c)
 * Tests if the middle value is smaller than both neighbors
 * @param a - Left neighbor value
 * @param b - Center value to test
 * @param c - Right neighbor value  
 * @returns True if b is a local minimum
 */
function isMinima(a: number, b: number, c: number): boolean;

/**
 * Returns true if b is a local maxima (a < b && b > c) 
 * Tests if the middle value is larger than both neighbors
 * @param a - Left neighbor value
 * @param b - Center value to test
 * @param c - Right neighbor value
 * @returns True if b is a local maximum
 */
function isMaxima(a: number, b: number, c: number): boolean;

/**
 * Returns index of the first local & internal minima in values array
 * Searches in semi-open interval [from, to)
 * @param values - Array of numeric values to search
 * @param from - Start index (default: 0)
 * @param to - End index exclusive (default: values.length)  
 * @returns Index of first minima, or -1 if none found
 */
function minimaIndex(values: number[], from?: number, to?: number): number;

/**
 * Returns index of the first local & internal maxima in values array
 * Searches in semi-open interval [from, to)
 * @param values - Array of numeric values to search
 * @param from - Start index (default: 0)  
 * @param to - End index exclusive (default: values.length)
 * @returns Index of first maxima, or -1 if none found
 */
function maximaIndex(values: number[], from?: number, to?: number): number;

/**
 * Returns generator yielding all minima indices in values array
 * Searches in semi-open interval [from, to)
 * @param values - Array of numeric values to search  
 * @param from - Start index (default: 0)
 * @param to - End index exclusive (default: values.length)
 * @returns Generator yielding indices of all minima
 */
function minimaIndices(values: number[], from?: number, to?: number): Generator<number>;

/**
 * Returns generator yielding all maxima indices in values array  
 * Searches in semi-open interval [from, to)
 * @param values - Array of numeric values to search
 * @param from - Start index (default: 0)
 * @param to - End index exclusive (default: values.length) 
 * @returns Generator yielding indices of all maxima
 */
function maximaIndices(values: number[], from?: number, to?: number): Generator<number>;

import { 
  isMinima, isMaxima, 
  minimaIndex, maximaIndex,
  minimaIndices, maximaIndices 
} from "@thi.ng/math/extrema";

// Local extrema detection
isMinima(5, 2, 7); // true (2 < 5 and 2 < 7)
isMinima(2, 5, 7); // false (5 > 2, not a minimum)
isMaxima(2, 8, 3); // true (8 > 2 and 8 > 3)

// Sample data with peaks and valleys
const signal = [1, 3, 2, 6, 4, 8, 5, 7, 1];

// Find first extrema  
minimaIndex(signal); // 2 (value 2 at index 2)
maximaIndex(signal); // 3 (value 6 at index 3)

// Find extrema in specific range
minimaIndex(signal, 3, 8); // 4 (value 4 at index 4)
maximaIndex(signal, 4, 8); // 5 (value 8 at index 5)

// Find all extrema
const allMinima = [...minimaIndices(signal)]; // [2, 4, 8]
const allMaxima = [...maximaIndices(signal)]; // [1, 3, 5, 7]

// Get actual extrema values
const minimaValues = allMinima.map(i => signal[i]); // [2, 4, 1]
const maximaValues = allMaxima.map(i => signal[i]); // [3, 6, 8, 7]

// Practical applications
// Find peaks in audio signal
const findAudioPeaks = (samples: number[], threshold = 0.5) => {
  return [...maximaIndices(samples)].filter(i => samples[i] > threshold);
};

// Find valleys in time series data
const findDataValleys = (timeSeries: number[]) => {
  return [...minimaIndices(timeSeries)].map(i => ({
    index: i,
    value: timeSeries[i],
    timestamp: i // or actual timestamp
  }));
};

// Analyze signal characteristics
const analyzeSignal = (data: number[]) => {
  const peaks = [...maximaIndices(data)];
  const valleys = [...minimaIndices(data)];
  
  return {
    peakCount: peaks.length,
    valleyCount: valleys.length,
    avgPeakValue: peaks.reduce((sum, i) => sum + data[i], 0) / peaks.length,
    avgValleyValue: valleys.reduce((sum, i) => sum + data[i], 0) / valleys.length
  };
};