math reference

Numeric functions and constants for arithmetic, rounding, random values, and finite-value checks.

math.abs

math.abs(value: number) -> same_numeric

Returns the absolute value of a number.

value keeps its type: an int returns an int and a float returns a float. Check for null or use ?? to supply a fallback before calling. Null float inputs produce null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let body = math.abs((chart.close ?? 0.0) - (chart.open ?? 0.0))
}

math.max

math.max(value: number, values: number...) -> same_numeric

Returns the largest of one or more numbers.

Pass the first number as value and any others as values. Mixing ints and floats gives a float result.

Check for null or use ?? to supply a fallback before calling. NaN inputs produce null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let bodyTop = math.max(chart.open ?? 0.0, chart.close ?? 0.0)
}

math.min

math.min(value: number, values: number...) -> same_numeric

Returns the smallest of one or more numbers.

Pass the first number as value and any others as values. Mixing ints and floats gives a float result.

Check for null or use ?? to supply a fallback before calling. NaN inputs produce null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let bodyBottom = math.min(chart.open ?? 0.0, chart.close ?? 0.0)
}

math.clamp

math.clamp(value: number, min: number, max: number) -> same_numeric

Keeps a number within a range.

Returns value when it is between min and max, including both ends. Below the range it returns min; above the range it returns max.

Mixing ints and floats gives a float result. min > max stops the script with an error. Check for null or use ?? to supply a fallback before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let pct = math.clamp(((chart.close ?? 0.0) - (chart.open ?? 0.0)) * 10.0, 0.0, 100.0)
}

math.round

math.round(value: number, decimals: int = 0) -> float

Rounds a number to a chosen number of decimal places.

value can be an int or float; the result is always a float. decimals defaults to 0, which rounds to a whole number. Negative decimals round to tens, hundreds, and so on.

Check for null or use ?? to supply a fallback before calling. NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let price = math.round(chart.close ?? 0.0, 2)
}

math.floor

math.floor(value: float) -> float

Rounds a number down to a whole number.

For example, 1.8 becomes 1.0 and -1.2 becomes -2.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let wholePrice = math.floor(chart.close ?? 0.0)
}

math.ceil

math.ceil(value: float) -> float

Rounds a number up to a whole number.

For example, 1.2 becomes 2.0 and -1.8 becomes -1.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let wholePrice = math.ceil(chart.close ?? 0.0)
}

math.trunc

math.trunc(value: float) -> float

Removes the fractional part of a number.

Rounds toward zero: 1.8 becomes 1.0 and -1.8 becomes -1.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let signedWhole = math.trunc((chart.close ?? 0.0) - (chart.open ?? 0.0))
}

math.sign

math.sign(value: float) -> float

Returns -1.0, 0.0, or 1.0 for a number's sign.

Returns -1.0 for negative values, 1.0 for positive values, and 0.0 for both 0.0 and -0.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let direction = math.sign((chart.close ?? 0.0) - (chart.open ?? 0.0))
}

math.pow

math.pow(base: float, exponent: float) -> float?

Raises a number to a power.

Returns base raised to exponent, as a float. Inputs with no real-number result, such as a negative base with a fractional exponent, return null.

Check for null or use ?? to supply a fallback before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let squared = math.pow((chart.close ?? 0.0) - (chart.open ?? 0.0), 2.0)
}

math.atan2

math.atan2(y: float, x: float) -> float

Returns the angle of a vector in radians.

y and x are the vector's coordinates. The result is from -math.pi to math.pi, inclusive.

Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let angle = math.atan2(
    (chart.close ?? 0.0) - (chart.open ?? 0.0),
    (chart.high ?? 0.0) - (chart.low ?? 0.0)
  )
}

math.log

math.log(value: float) -> float?

Returns the natural logarithm of a float.

value must be greater than 0.0 for a real result. Values at or below 0.0 return null. Check for null before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ret = math.log((chart.close ?? 1.0) / (chart.open ?? 1.0))
}

math.log2

math.log2(value: float) -> float?

Returns the base-2 logarithm of a float.

value must be greater than 0.0 for a real result. Values at or below 0.0 return null. Check for null before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let scale = math.log2(chart.volume ?? 0.0)
}

math.log10

math.log10(value: float) -> float?

Returns the base-10 logarithm of a float.

value must be greater than 0.0 for a real result. Values at or below 0.0 return null. Check for null before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let digits = math.log10(chart.volume ?? 0.0)
}

math.sqrt

math.sqrt(value: float) -> float?

Returns the square root of a float.

value must be non-negative for a real result. Negative values produce null. Check for null before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let range = math.sqrt((chart.high ?? 0.0) - (chart.low ?? 0.0))
}

math.cbrt

math.cbrt(value: float) -> float

Returns the cube root of a number.

value can be negative, zero, or positive.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let normalized = math.cbrt((chart.close ?? 0.0) - (chart.open ?? 0.0))
}

math.exp

math.exp(value: float) -> float

Returns e raised to a power.

value is the exponent. A result too large for a float may be infinite.

Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let growth = math.exp((chart.close ?? 0.0) - (chart.open ?? 0.0))
}

math.sin

math.sin(value: float) -> float

Returns the sine of an angle in radians.

value is the angle in radians.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let wave = math.sin(chart.index * 0.1)
}

math.cos

math.cos(value: float) -> float

Returns the cosine of an angle in radians.

value is the angle in radians.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let wave = math.cos(chart.index * 0.1)
}

math.tan

math.tan(value: float) -> float

Returns the tangent of an angle in radians.

value is the angle in radians. Near odd multiples of math.pi / 2.0, the result may be very large or infinite.

Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let slope = math.tan(chart.index * 0.01)
}

math.asin

math.asin(value: float) -> float?

Returns the arcsine of a float in radians.

value must be in [-1.0, 1.0] for a real result. Values outside that range return null. Check for null before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let angle = math.asin(math.clamp((chart.close ?? 0.0) - (chart.open ?? 0.0), -1.0, 1.0))
}

math.acos

math.acos(value: float) -> float?

Returns the arccosine of a float in radians.

value must be in [-1.0, 1.0] for a real result. Values outside that range return null. Check for null before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let angle = math.acos(math.clamp((chart.close ?? 0.0) - (chart.open ?? 0.0), -1.0, 1.0))
}

math.atan

math.atan(value: float) -> float

Returns the arctangent of a number in radians.

The result is between -math.pi / 2.0 and math.pi / 2.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let angle = math.atan((chart.close ?? 0.0) - (chart.open ?? 0.0))
}

math.sinh

math.sinh(value: float) -> float

Returns the hyperbolic sine of a number.

value is the number to calculate from.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let value = math.sinh((chart.close ?? 0.0) - (chart.open ?? 0.0))
}

math.cosh

math.cosh(value: float) -> float

Returns the hyperbolic cosine of a number.

value is the number to calculate from.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let value = math.cosh((chart.close ?? 0.0) - (chart.open ?? 0.0))
}

math.tanh

math.tanh(value: float) -> float

Returns the hyperbolic tangent of a number.

Returns a value from -1.0 to 1.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let bounded = math.tanh((chart.close ?? 0.0) - (chart.open ?? 0.0))
}

math.roundTo

math.roundTo(value: float, step: float) -> float?

Rounds a float to the nearest multiple of step.

value is divided by step, rounded to the nearest integer value, and multiplied by step. A zero, null, or NaN step returns null instead of stopping the script with an error. Check for null before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let price = math.roundTo(chart.close ?? 0.0, 0.25)
}

math.floorTo

math.floorTo(value: float, step: float) -> float?

Rounds a float down to a multiple of step.

value is divided by step, rounded down, and multiplied by step. A zero, null, or NaN step returns null instead of stopping the script with an error. Check for null before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let bid = math.floorTo(chart.close ?? 0.0, 0.25)
}

math.ceilTo

math.ceilTo(value: float, step: float) -> float?

Rounds a float up to a multiple of step.

value is divided by step, rounded up, and multiplied by step. A zero, null, or NaN step returns null instead of stopping the script with an error. Check for null before calling.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ask = math.ceilTo(chart.close ?? 0.0, 0.25)
}

math.safeDiv

math.safeDiv(num: float?, den: float?, fallback: float = 0) -> float?

Returns a division result with a fallback for zero or missing denominators.

num is the numerator. den is the denominator; zero or null den returns fallback. Null num returns null because the numerator is missing. Otherwise the result is num / den.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let moveRatio = math.safeDiv(chart.close - chart.open, chart.open, 0.0) ?? 0.0
}

math.randomFloat

math.randomFloat(min: float, max: float) -> float

Returns a random float from min up to, but not including, max.

Both bounds are required. Every equal-sized part of the range is equally likely. min >= max stops the script with an error.

Call this inside a handler. Replaying the same script uses the same sequence of random values.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let jitter = math.randomFloat(-0.5, 0.5)
}

math.randomInt

math.randomInt(min: int, max: int) -> int

Returns a random whole number between min and max, including both.

Both bounds are required. Every integer in the range is equally likely. min > max stops the script with an error. Bounds must be within math.minInt (-9223372036854775807) and math.maxInt (9223372036854775807).

Replaying the same script uses the same sequence of random values.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let pick = math.randomInt(0, 9)
}

math.isFinite

math.isFinite(value: float?) -> bool

Reports whether a number is finite and non-null.

Returns false for null, NaN, and positive or negative infinity; otherwise true.

This check does not change a nullable value's type. Use x != null when you need to use x as a non-null value.

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let usable = math.isFinite(chart.close)
}

math.isEven

math.isEven(value: int) -> bool

Tests whether an integer is even.

Returns true when value % 2 == 0. Check for null before using a nullable int. Supported integers range from math.minInt (-9223372036854775807) to math.maxInt (9223372036854775807).

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let evenBar = math.isEven(chart.index)
}

math.isOdd

math.isOdd(value: int) -> bool

Tests whether an integer is odd.

Returns true when value % 2 != 0. Check for null before using a nullable int. Supported integers range from math.minInt (-9223372036854775807) to math.maxInt (9223372036854775807).

Example

script "Math Example"
data chart = subscribe(data.ohlcv)

on chart.update {
  let oddBar = math.isOdd(chart.index)
}

math.pi

math.pi: float = 3.141592653589793

Pi, the ratio of a circle's circumference to its diameter.

math.e

math.e: float = 2.718281828459045

Euler's number, the base of natural logarithms.

math.tau

math.tau: float = 6.283185307179586

Tau, equal to 2.0 * math.pi.

math.epsilon

math.epsilon: float = 0.0000000000000002220446049250313

The gap between 1.0 and the next larger float.

math.maxInt

math.maxInt: int = 9223372036854775807

The largest supported integer.

math.minInt

math.minInt: int = -9223372036854775807

Lowest supported integer value (-9223372036854775807).

math.maxFloat

math.maxFloat: float = 179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

The largest finite float.

math.minFloat

math.minFloat: float = -179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

The most negative finite float.