openscript 0.4.0__py3-none-any.whl

openscript/library/deviation.py

@@ -0,0 +1,155 @@
+"""The spread readings of `stdlib.md` section 20.5 and the bands built on them.
+
+**The variance is two passes and the one pass arrangement is not permitted.**
+Subtracting the square of the mean from the mean of the squares is mathematically
+equal, loses most of its significant digits on a price series where the values
+are large and their spread is small, and can return a negative variance that then
+has to be floored at zero. An implementation that needs a floor to stay real is
+computing a different quantity, and the floor is how it hides.
+
+**The two readings taken from the bands are computed from the bands as
+reported.** A study that plots all three lines and a study that plots one reading
+then agree to the last bit, which they would not if the reading were rebuilt from
+the basis and the width.
+"""
+
+from typing import Optional
+
+from . import averages, composites, elementary, ranges
+from .series import Region, contributed, mean, region, window
+from .values import ABSENT, Value, number, result
+
+
+def variance(
+    state: Region, value: Value, length: Optional[int], sample: Value
+) -> Value:
+    """``variance(src, len, sample)``: the mean first, the deviations from it second.
+
+    Each deviation is squared as a product of the deviation with itself. The
+    divisor is ``len`` for the population form and ``len - 1`` for the sample
+    form, which is what the argument names rather than a correction a script has
+    to write by hand.
+    """
+    held = window(contributed(state, "src", number(value), length), length)
+    if held is None or length is None:
+        return ABSENT
+    squares = spread_of(held, length)
+    divisor = (length - 1) if sample is True else length
+    if divisor == 0:
+        return ABSENT
+    return result(squares / divisor)
+
+
+def spread_of(held, length: int) -> float:
+    """The second pass: the squared deviations from the finished mean, oldest first."""
+    middle = mean(held, length)
+    squares = 0.0
+    for at in range(length - 1, -1, -1):
+        squares = squares + (held[at] - middle) * (held[at] - middle)
+    return squares
+
+
+def deviation(
+    state: Region, value: Value, length: Optional[int], sample: Value
+) -> Value:
+    """``stdev(src, len, sample)``: the square root of that variance, taken once."""
+    return elementary.sqrt(variance(state, value, length, sample))
+
+
+def bands(state: Region, value: Value, length: Optional[int], multiplier: Value) -> list:
+    """``bollinger(src, len, mult)``: a mean with deviation bands, formed as written.
+
+    The multiplier is applied to the width and the product added to the basis,
+    which is one rounding of the product and one of the sum.
+    """
+    basis = averages.simple(region(state, "basis"), value, length)
+    width = deviation(region(state, "width"), value, length, False)
+    return _banded(basis, width, number(multiplier))
+
+
+def band_width(
+    state: Region, value: Value, length: Optional[int], multiplier: Value
+) -> Value:
+    """``bbWidth(src, len, mult)``: the band width over the basis, a squeeze reads low."""
+    basis, upper, lower = bands(state, value, length, multiplier)
+    if not isinstance(upper, float) or not isinstance(lower, float):
+        return ABSENT
+    if not isinstance(basis, float) or basis == 0:
+        return ABSENT
+    return result((upper - lower) / basis)
+
+
+def band_position(
+    state: Region, value: Value, length: Optional[int], multiplier: Value
+) -> Value:
+    """``bbPercent(src, len, mult)``: where the source sits between the two bands."""
+    _basis, upper, lower = bands(state, value, length, multiplier)
+    price = number(value)
+    if not isinstance(upper, float) or not isinstance(lower, float) or price is None:
+        return ABSENT
+    span = upper - lower
+    if span == 0:
+        return ABSENT
+    return result((price - lower) / span)
+
+
+def range_bands(
+    state: Region,
+    ctx,
+    length: Optional[int],
+    multiplier: Value,
+    width_length: Optional[int],
+    kind: Value,
+) -> list:
+    """``keltner(len, mult, atrLen, maType)``: the same picture built from the range.
+
+    **The basis is the close**, averaged at ``len`` by the type the argument
+    names, and not the typical price. Section 6 writes the call without a source
+    argument and the close is the source it means: the two agree only on a bar
+    whose close is its own typical price, so this decides which function the call
+    is rather than the order its arithmetic runs in.
+
+    The width is the average true range exactly as section 20.5 defines it, the
+    oldest bar's exception included, and not the gap aware form the directional
+    index takes.
+    """
+    basis = composites.named(region(state, "basis"), ctx, ctx.bar("close"), length, kind)
+    width = ranges.average_range(region(state, "width"), ctx, width_length)
+    return _banded(basis, width, number(multiplier))
+
+
+def historical(
+    state: Region, value: Value, length: Optional[int], periods: Value
+) -> Value:
+    """``hv(src, len, periodsPerYear)``: the spread of the log return, annualised once.
+
+    The ratio is formed before the logarithm is taken. The result is a proportion
+    and is not scaled by a hundred: section 6 says annualised standard deviation
+    of log returns and says nothing about a percentage, so a study that wants a
+    percentage axis multiplies at the plot, where a reader can see it happen.
+
+    **This reading depends on ``log``**, so it reaches gap 1 of section 20.11 and
+    carries no cross-engine guarantee.
+    """
+    values = contributed(state, "src", number(value), 2)
+    now = values[len(values) - 1]
+    before = values[len(values) - 2] if len(values) > 1 else ABSENT
+    ratio = ABSENT
+    if isinstance(now, float) and isinstance(before, float) and before != 0:
+        ratio = now / before
+    step = elementary.log(ratio)
+    spread = deviation(region(state, "spread"), step, length, False)
+    count = number(periods)
+    scale = elementary.sqrt(count)
+    if not isinstance(spread, float) or not isinstance(scale, float):
+        return ABSENT
+    return result(spread * scale)
+
+
+def _banded(basis: Value, width: Value, multiplier: Optional[float]) -> list:
+    """The three lines of a band study: the basis, and the width either side of it."""
+    if not isinstance(basis, float) or not isinstance(width, float):
+        return [basis if isinstance(basis, float) else ABSENT, ABSENT, ABSENT]
+    if multiplier is None:
+        return [basis, ABSENT, ABSENT]
+    return [basis, result(basis + multiplier * width), result(basis - multiplier * width)]

openscript/library/elementary.py

@@ -0,0 +1,206 @@
+"""Square root, the logarithms, the powers and the trigonometry.
+
+**Everything here except ``sqrt`` reaches gap 1 of `stdlib.md` section 20.11,
+and is not held to the vectors.** That section states the gap and
+`compiled-program.md` section 8.3 states the requirement it cannot meet: a
+transcendental function is to be computed by a portable reference algorithm
+rather than by the platform's own maths library, because a platform's is correct
+to within about an ulp and differs between platforms in the last bit. **No such
+algorithm is written down anywhere**, so there is nothing to implement against,
+and inventing one here would be a third answer rather than a second engine.
+
+So these call the host's maths module and say so. `conformance.md` section 8
+scopes the difference out: no case may assert a value that reaches this row, not
+even with a tolerance, because an engine that is correct can fail such a case and
+the release gate would then stop a release over a hole in the specification. The
+calls still work and still compute what they always did; what they do not carry
+is a cross-engine guarantee.
+
+Measured against `spec/vectors/library/`, which is the first engine's arithmetic,
+this file's answers differ on a minority of cells and never by more than one ulp.
+``exp``, ``log``, ``log10``, ``pow``, ``sin``, ``cos``, ``tan``, ``hypot`` and
+``atan2`` each have some; ``log2``, ``asin``, ``acos`` and ``atan`` had none on
+the interpreter this was written under, which is a fact about two maths libraries
+on one machine and not a guarantee about a third.
+
+**``sqrt`` is the exception and is held to the vectors.** IEEE-754 requires it to
+be correctly rounded, so every conforming platform returns the same bits, and
+section 20.10 says so rather than leaving it to be assumed.
+
+The domain rules are `stdlib.md` section 8.1's, and are checked before the call
+rather than read off the answer: the host raises where this language is absent,
+and an engine that let the raise out would turn "no finite real value" into a
+stopped run.
+"""
+
+import math
+
+from .values import ABSENT, Value, number, result
+
+# The circle constant and the base of the natural logarithm, as `stdlib.md`
+# section 8.2 names them. Both are the nearest binary64 to the constant and are
+# the same bits on every platform, so neither reaches the gap above.
+PI: float = math.pi
+E: float = math.e
+
+
+def _guarded(x: float, of) -> Value:
+    """A host maths call whose refusals become absence.
+
+    The host raises where the argument is outside the function's domain and
+    where the answer overflows. `stdlib.md` section 2.4 makes both of those
+    absence: a function whose result has no finite real value returns ``none``
+    rather than raising, and it is a function whose *arguments* are wrong that
+    raises, which is a diagnostic the checker or the interpreter produces long
+    before the call gets here.
+    """
+    try:
+        return result(of(x))
+    except (ValueError, OverflowError, ZeroDivisionError):
+        return ABSENT
+
+
+def sqrt(x: Value) -> Value:
+    """``sqrt(x)``: square root, absent below zero."""
+    value = number(x)
+    if value is None or value < 0:
+        return ABSENT
+    return result(math.sqrt(value))
+
+
+def exp(x: Value) -> Value:
+    """``exp(x)``: e to the power x. Reaches gap 1."""
+    value = number(x)
+    return ABSENT if value is None else _guarded(value, math.exp)
+
+
+def log(x: Value) -> Value:
+    """``log(x)``: natural logarithm, absent at or below zero. Reaches gap 1."""
+    value = number(x)
+    if value is None or value <= 0:
+        return ABSENT
+    return _guarded(value, math.log)
+
+
+def log10(x: Value) -> Value:
+    """``log10(x)``: base ten logarithm, same absence rule. Reaches gap 1."""
+    value = number(x)
+    if value is None or value <= 0:
+        return ABSENT
+    return _guarded(value, math.log10)
+
+
+def log2(x: Value) -> Value:
+    """``math.log2(x)``: base two logarithm, same absence rule. Reaches gap 1."""
+    value = number(x)
+    if value is None or value <= 0:
+        return ABSENT
+    return _guarded(value, math.log2)
+
+
+def power(x: Value, y: Value) -> Value:
+    """``pow(x, y)``: absent where the result is not a finite real.
+
+    Reaches gap 1. A negative base raised to a fractional exponent has no real
+    answer and a zero base raised to a negative one has no finite answer, and
+    both are absence here rather than the refusal the host makes of them.
+    """
+    base = number(x)
+    exponent = number(y)
+    if base is None or exponent is None:
+        return ABSENT
+    try:
+        return result(math.pow(base, exponent))
+    except (ValueError, OverflowError, ZeroDivisionError):
+        return ABSENT
+
+
+def hypot(x: Value, y: Value) -> Value:
+    """``math.hypot(x, y)``: the diagonal without intermediate overflow.
+
+    Reaches gap 1, and it is the reading of this file most likely to differ:
+    avoiding the overflow is what makes it more than a square root of a sum of
+    squares, and no two libraries scale the same way.
+    """
+    left = number(x)
+    right = number(y)
+    if left is None or right is None:
+        return ABSENT
+    try:
+        return result(math.hypot(left, right))
+    except (ValueError, OverflowError):
+        return ABSENT
+
+
+def to_degrees(x: Value) -> Value:
+    """``math.toDegrees(x)``: ``(x * 180) / pi``, multiply first.
+
+    Not a gap: it is two operations over binary64 and `stdlib.md` section 20.7
+    fixes their order. Folding the constant into one factor is a different number
+    at about a quarter of the arguments, so the association is written out rather
+    than handed to a conversion the host provides.
+    """
+    value = number(x)
+    return ABSENT if value is None else result((value * 180) / math.pi)
+
+
+def to_radians(x: Value) -> Value:
+    """``math.toRadians(x)``: ``(x * pi) / 180``, multiply first. Not a gap."""
+    value = number(x)
+    return ABSENT if value is None else result((value * math.pi) / 180)
+
+
+def sin(x: Value) -> Value:
+    """``math.sin(x)``: sine of an angle in radians. Reaches gap 1."""
+    value = number(x)
+    return ABSENT if value is None else _guarded(value, math.sin)
+
+
+def cos(x: Value) -> Value:
+    """``math.cos(x)``: cosine. Reaches gap 1."""
+    value = number(x)
+    return ABSENT if value is None else _guarded(value, math.cos)
+
+
+def tan(x: Value) -> Value:
+    """``math.tan(x)``: tangent. Reaches gap 1."""
+    value = number(x)
+    return ABSENT if value is None else _guarded(value, math.tan)
+
+
+def asin(x: Value) -> Value:
+    """``math.asin(x)``: inverse sine, absent outside -1 to 1. Reaches gap 1."""
+    value = number(x)
+    if value is None or value < -1 or value > 1:
+        return ABSENT
+    return _guarded(value, math.asin)
+
+
+def acos(x: Value) -> Value:
+    """``math.acos(x)``: inverse cosine, same range rule. Reaches gap 1."""
+    value = number(x)
+    if value is None or value < -1 or value > 1:
+        return ABSENT
+    return _guarded(value, math.acos)
+
+
+def atan(x: Value) -> Value:
+    """``math.atan(x)``: inverse tangent. Reaches gap 1."""
+    value = number(x)
+    return ABSENT if value is None else _guarded(value, math.atan)
+
+
+def atan2(y: Value, x: Value) -> Value:
+    """``math.atan2(y, x)``: angle of a vector, in all four quadrants.
+
+    Reaches gap 1. The argument order is the page's, which is the one every
+    library states: the vertical component first.
+    """
+    vertical = number(y)
+    horizontal = number(x)
+    if vertical is None or horizontal is None:
+        return ABSENT
+    try:
+        return result(math.atan2(vertical, horizontal))
+    except (ValueError, OverflowError):
+        return ABSENT

openscript/library/extremes.py

@@ -0,0 +1,122 @@
+"""The window scans of `stdlib.md` sections 9 and 20.10, and the pivots.
+
+Section 20.10 names these as the functions with no accumulation order to fix:
+they select a value and compute nothing, so an implementer can write the scan the
+obvious way and be bit identical. **The one thing a scan can differ on is a
+tie**, and the tie rules are section 9's, so they are what this file is careful
+about.
+
+- An extreme goes to **the most recent bar that set it**, so an equal value later
+  in the window replaces the earlier one. That only shows in the two calls that
+  report an age, and it shows there on every flat stretch of a series.
+- A pivot is **strict on both sides**, so a run of equal values holds no pivot at
+  all. A test written with "at or above" would report a pivot at each end of a
+  flat top, which is two pivots where the chart shows none.
+
+A window arrives newest first, so an index into it is an age in bars and
+``held[0]`` is what this bar contributed.
+"""
+
+from typing import Optional, Sequence
+
+from .series import Region, contributed, window
+from .values import ABSENT, Value, number, result
+
+
+def high_at(held: Sequence[float]) -> int:
+    """The age in bars of the window's high, the most recent bar that set it.
+
+    The scan runs oldest first and replaces on an equal value, which is how the
+    tie reaches the newest of the bars that hold it rather than the oldest.
+    """
+    at = len(held) - 1
+    for age in range(len(held) - 2, -1, -1):
+        if held[age] >= held[at]:
+            at = age
+    return at
+
+
+def low_at(held: Sequence[float]) -> int:
+    """The age in bars of the window's low, on the same terms."""
+    at = len(held) - 1
+    for age in range(len(held) - 2, -1, -1):
+        if held[age] <= held[at]:
+            at = age
+    return at
+
+
+def window_high(values: Sequence[Value], length: Optional[int]) -> Value:
+    """The outright high of the last ``length`` contributions, or absence."""
+    held = window(values, length)
+    return ABSENT if held is None else result(held[high_at(held)])
+
+
+def window_low(values: Sequence[Value], length: Optional[int]) -> Value:
+    """The outright low of the last ``length`` contributions, or absence."""
+    held = window(values, length)
+    return ABSENT if held is None else result(held[low_at(held)])
+
+
+def highest(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``highest(src, len)``: the largest value in the last ``len`` bars."""
+    return window_high(contributed(state, "src", number(value), length), length)
+
+
+def lowest(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``lowest(src, len)``: the smallest."""
+    return window_low(contributed(state, "src", number(value), length), length)
+
+
+def highest_bars(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``highestBars(src, len)``: how many bars back the window's high was set."""
+    held = window(contributed(state, "src", number(value), length), length)
+    return ABSENT if held is None else float(high_at(held))
+
+
+def lowest_bars(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``lowestBars(src, len)``: how many bars back the window's low was set."""
+    held = window(contributed(state, "src", number(value), length), length)
+    return ABSENT if held is None else float(low_at(held))
+
+
+def pivot_high(state: Region, value: Value, left: Optional[int], right: Optional[int]) -> Value:
+    """``pivotHigh(src, left, right)``: a local high, reported ``right`` bars after it.
+
+    Reporting it at the pivot bar would be a lookahead: the value would appear on
+    history at a bar where no script could have had it. So the window is
+    ``left + right + 1`` wide, the candidate sits ``right`` bars back inside it,
+    and the answer is absent on every bar that is not one.
+    """
+    values = contributed(state, "src", number(value), _span(left, right))
+    return _pivot(values, left, right, True)
+
+
+def pivot_low(state: Region, value: Value, left: Optional[int], right: Optional[int]) -> Value:
+    """``pivotLow(src, left, right)``: a local low, on the same terms."""
+    values = contributed(state, "src", number(value), _span(left, right))
+    return _pivot(values, left, right, False)
+
+
+def _span(left: Optional[int], right: Optional[int]) -> Optional[int]:
+    """The window a pivot test needs: the bars either side and the candidate."""
+    if left is None or right is None:
+        return None
+    return left + right + 1
+
+
+def _pivot(
+    values: Sequence[Value], left: Optional[int], right: Optional[int], above: bool
+) -> Value:
+    """The candidate's value where it beats both sides strictly, absence otherwise."""
+    held = window(values, _span(left, right))
+    if held is None or right is None:
+        return ABSENT
+    candidate = held[right]
+    for age in range(len(held)):
+        if age == right:
+            continue
+        if above and held[age] >= candidate:
+            return ABSENT
+        if not above and held[age] <= candidate:
+            return ABSENT
+    return result(candidate)