Utility Functions — kScript

Utility functions provide statistical calculations, data manipulation, cross detection, support/resistance helpers, and data validation. They are building blocks for custom indicators and mathematical operations on time series data.

Category	Description
Statistical Functions	Calculate standard deviation, highest/lowest values, and sums over specified periods.
Cross Detection	Detect when time series cross above, below, or in either direction to generate trading signals.
Support/Resistance Levels	Identify key price levels using functions that track highs/lows over a lookback period.
Type Checking	Validate data integrity with NaN and numeric checks before performing calculations.

Function	Description
`lowest`	Find lowest value over specified period
`highest`	Find highest value over specified period
`sum`	Calculate sum of values over specified period
`stddev`	Calculate standard deviation of values
`donchian`	Donchian Channel midpoint calculation
`crossover`	Detect when series A crosses above series B
`crossunder`	Detect when series A crosses below series B
`cross`	Detect when series A crosses series B in either direction
`isnan`	Check if a value is NaN (Not a Number)
`isnum`	Check if a value is a valid finite number

lowest - find lowest value over specified period

lowest(source: TimeSeries, period?: number = 12, priceIndex?: number = 3): number

Parameter	Type	Description
`source`	TimeSeries	Source data series
`period`	number	Number of periods to look back (default: `12`)
`priceIndex`	number	Index of price data (default: `3` for low)

Returns: number (lowest value in the specified period).

var low20 = lowest(source=trade, period=20); // 20-period low

highest - find highest value over specified period

highest(source: TimeSeries, period?: number = 12, priceIndex?: number = 2): number

Parameter	Type	Description
`source`	TimeSeries	Source data series
`period`	number	Number of periods to look back (default: `12`)
`priceIndex`	number	Index of price data (default: `2` for high)

Returns: number (highest value in the specified period).

var high20 = highest(source=trade, period=20); // 20-period high

sum - calculate sum of values over specified period

sum(source: TimeSeries, period?: number = 12, priceIndex?: number = 1): number

Parameter	Type	Description
`source`	TimeSeries	Source data series
`period`	number	Number of periods to sum (default: `12`)
`priceIndex`	number	Index of price data (default: `1`)

Returns: number (sum of values in the specified period).

var volumeSum = sum(source=trade, period=10); // 10-period volume sum

stddev - calculate standard deviation of values

stddev(source: TimeSeries, period?: number = 12, priceIndex?: number = 1): number

Parameter	Type	Description
`source`	TimeSeries	Source data series
`period`	number	Number of periods for calculation (default: `12`)
`priceIndex`	number	Index of price data (default: `1`)

Returns: number (standard deviation value).

var volatility = stddev(source=trade, period=20); // 20-period volatility

donchian - Donchian Channel midpoint calculation

donchian(source: TimeSeries, period?: number = 12): number

Parameter	Type	Description
`source`	TimeSeries	Source data series
`period`	number	Number of periods (default: `12`)

Returns: number (Donchian Channel midpoint value).

var donchianMid = donchian(source=trade, period=20);

crossover - detect when series A crosses above series B

crossover(seriesA: TimeSeries, seriesB: TimeSeries): boolean

Parameter	Type	Description
`seriesA`	TimeSeries	First series, such as a fast moving average
`seriesB`	TimeSeries	Second series, such as a slow moving average

Returns: boolean (true if A crosses above B at the current bar).

var cross = crossover(fastMA, slowMA);

crossunder - detect when series A crosses below series B

crossunder(seriesA: TimeSeries, seriesB: TimeSeries): boolean

Parameter	Type	Description
`seriesA`	TimeSeries	First series
`seriesB`	TimeSeries	Second series

Returns: boolean (true when A crosses below B).

var bearishCross = crossunder(fastMA, slowMA);

cross - detect when series A crosses series B in either direction

cross(seriesA: TimeSeries, seriesB: TimeSeries): boolean

Parameter	Type	Description
`seriesA`	TimeSeries	First series
`seriesB`	TimeSeries	Second series

Returns: boolean (true when any cross occurs).

var anyCross = cross(macdLine, signalLine);

isnan - check if a value is NaN (Not a Number)

isnan(value: any): boolean

Parameter	Type	Description
`value`	any	Value to check for NaN

Returns: boolean (true if value is NaN, false otherwise).

var invalid = isnan(result); // Check if calculation failed

isnum - check if a value is a valid finite number

isnum(value: any): boolean

Parameter	Type	Description
`value`	any	Value to check for numeric validity

Returns: boolean (true if value is a valid finite number, false otherwise).

var valid = isnum(price); // Validate price data

Best Practices

Lookback Periods

Choose lookback periods based on your timeframe. Shorter periods fit scalping and lower timeframes; longer periods fit swing trading and broader trend analysis.

Performance

Statistical functions can be computationally expensive. Cache results when calculating multiple statistics on the same data.

Cross Detection

Use crossover() for bullish signals, crossunder() for bearish signals, and cross() when you need any direction change. Always combine cross signals with trend confirmation.

Donchian Channels

Donchian channels work best in trending markets for breakout strategies. In ranging markets, use them as support/resistance levels instead of breakout signals.

False Signals

Cross functions can generate false signals in choppy markets. Add filters like volume confirmation or trend direction to improve signal quality.

Data Validation

Validate data with isnan() and isnum() before calculations. Invalid data can propagate through indicators and cause incorrect results.