openscript 0.4.0__py3-none-any.whl

openscript/library/colour.py

@@ -0,0 +1,202 @@
+"""Colour: the nineteen names, and the calls that compute one.
+
+**A colour's channels are whole numbers and its alpha is not**
+(`compiled-program.md` section 3.1). Red, green and blue are whole numbers from
+0 to 255 in every colour the machine holds, not only in a literal, because every
+call that computes one rounds the three channels before it returns, with the
+language's own rounding, halves away from zero (`stdlib.md` section 11.2). Alpha
+stays a binary64 number from 0 to 1 and becomes a byte only at the contract
+boundary, where the conversion is one way and is not a round trip.
+
+The two arrangements `stdlib.md` section 20.9 fixes are the whole of the
+arithmetic here, and both were chosen against a mathematically equal alternative
+that differs in the last bit, so both are written out rather than described:
+
+- ``mix`` interpolates as ``from + (to - from) * weight``, channel by channel and
+  the alpha included. It is not ``from * (1 - weight) + to * weight``.
+- ``fade`` sets the alpha to ``(100 - percent) / 100``, the subtraction before
+  the division. It is not ``1 - percent / 100``, which is a different number at
+  40 of the 101 whole percentages, and it sets the alpha rather than scaling the
+  one the colour already carried, which is what makes a nested fade the inner
+  call's fade (`stdlib.md` section 11.2).
+
+**The channel table is a copy of a fact this repository holds once.**
+`spec/colours.json` is the authority and part of the conformance suite;
+`stdlib.md` section 11.1 fixes the values there and gap 4 of section 20.11
+records that they are not written out in the specification prose. A package a
+host installs cannot read that file at run time, so the table is here, and
+``tests/test_colour.py`` holds it to the authority character for character rather
+than to the other engine's copy of it. Two copies that agree with each other and
+with nothing published are still a contract nobody can implement against.
+"""
+
+import math
+from typing import NamedTuple
+
+from .rounding import round_half_away
+from .values import ABSENT, Value, number
+
+
+class Colour(NamedTuple):
+    """Red, green and blue as whole numbers 0 to 255, alpha as 0 to 1."""
+
+    r: float
+    g: float
+    b: float
+    a: float
+
+
+_HEX_DIGITS = "0123456789abcdef"
+
+
+def hex_byte(channel: float) -> str:
+    """A whole number from 0 to 255 as two hex digits, from a table.
+
+    Not the decimal rule and no host conversion: each nibble indexes a string of
+    sixteen characters, so the spelling cannot pick up a locale, a sign or a
+    point on the way.
+    """
+    value = int(channel)
+    if value < 0:
+        value = 0
+    if value > 255:
+        value = 255
+    return _HEX_DIGITS[value >> 4] + _HEX_DIGITS[value & 15]
+
+
+def _channel(x: float) -> float:
+    """One computed channel: rounded to a whole number, then held in range.
+
+    The rounding is the requirement of section 11.2 and the clamp is the
+    backstop under a diagnostic: a channel argument outside 0 to 255 is refused
+    by the checker, because a colour computed from data and landing at 300 is a
+    bug in the computation rather than a value to fix silently. A value that
+    reached here anyway is held inside the range the value model promises, since
+    the alternative is a colour the machine says cannot exist.
+
+    **A channel with no finite value is 0, and no page says so.** It is reachable:
+    a blend at an enormous weight overflows the interpolation before the rounding
+    ever runs. Neither 11.2 nor 20.9 states an answer, and the first engine's is
+    0, so that is what is here, and the silence is recorded where an engine author
+    will meet it rather than left for two engines to differ over.
+    """
+    if not math.isfinite(x):
+        return 0.0
+    rounded = round_half_away(x)
+    if rounded < 0:
+        return 0.0
+    if rounded > 255:
+        return 255.0
+    return rounded
+
+
+def make(r: float, g: float, b: float, a: float) -> Colour:
+    """A colour with the value model's invariant already true of it."""
+    alpha = 0.0 if a < 0 else (1.0 if a > 1 else (0.0 if a == 0 else a))
+    return Colour(_channel(r), _channel(g), _channel(b), alpha)
+
+
+# The channel values of the named colours, which `spec/colours.json` is the
+# authority for. Each is at full opacity, as section 11.1 states.
+_CHANNELS: dict[str, tuple[int, int, int]] = {
+    "aqua": (0, 255, 255),
+    "black": (0, 0, 0),
+    "blue": (0, 0, 255),
+    "brown": (165, 42, 42),
+    "fuchsia": (255, 0, 255),
+    "gray": (128, 128, 128),
+    "green": (0, 128, 0),
+    "lime": (0, 255, 0),
+    "maroon": (128, 0, 0),
+    "navy": (0, 0, 128),
+    "olive": (128, 128, 0),
+    "orange": (255, 165, 0),
+    "pink": (255, 192, 203),
+    "purple": (128, 0, 128),
+    "red": (255, 0, 0),
+    "silver": (192, 192, 192),
+    "teal": (0, 128, 128),
+    "white": (255, 255, 255),
+    "yellow": (255, 255, 0),
+}
+
+# The nineteen names, for a test that has to compare two tables.
+NAMES: tuple[str, ...] = tuple(_CHANNELS)
+
+
+def named(name: str) -> Value:
+    """The colour one of the nineteen bare names holds, or absence."""
+    channels = _CHANNELS.get(name)
+    if channels is None:
+        return ABSENT
+    return make(float(channels[0]), float(channels[1]), float(channels[2]), 1.0)
+
+
+def _colour_of(value: Value) -> Colour | None:
+    return value if isinstance(value, Colour) else None
+
+
+def rgb(r: Value, g: Value, b: Value) -> Value:
+    """``rgb(r, g, b)``: channels 0 to 255, fully opaque."""
+    red = number(r)
+    green = number(g)
+    blue = number(b)
+    if red is None or green is None or blue is None:
+        return ABSENT
+    return make(red, green, blue, 1.0)
+
+
+def rgba(r: Value, g: Value, b: Value, a: Value) -> Value:
+    """``rgba(r, g, b, a)``: the same with alpha 0 to 1, where 1 is opaque."""
+    red = number(r)
+    green = number(g)
+    blue = number(b)
+    alpha = number(a)
+    if red is None or green is None or blue is None or alpha is None:
+        return ABSENT
+    return make(red, green, blue, alpha)
+
+
+def fade(base: Value, percent: Value) -> Value:
+    """``fade(color, percent)``: the same colour at ``percent`` transparency.
+
+    Transparency, not opacity, and a percentage: 100 is invisible. The two
+    conventions are opposites and a script that guesses wrong draws something
+    nobody can see, so the arithmetic is written out rather than left to be
+    inferred from the name. ``withAlpha`` is the call for the other convention.
+    """
+    colour = _colour_of(base)
+    amount = number(percent)
+    if colour is None or amount is None:
+        return ABSENT
+    return make(colour.r, colour.g, colour.b, (100 - amount) / 100)
+
+
+def mix(a: Value, b: Value, weight: Value) -> Value:
+    """``mix(a, b, weight)``: a blend, 0 giving the first and 1 the second."""
+    first = _colour_of(a)
+    second = _colour_of(b)
+    amount = number(weight)
+    if first is None or second is None or amount is None:
+        return ABSENT
+    return make(
+        first.r + (second.r - first.r) * amount,
+        first.g + (second.g - first.g) * amount,
+        first.b + (second.b - first.b) * amount,
+        first.a + (second.a - first.a) * amount,
+    )
+
+
+def alpha(base: Value) -> Value:
+    """``alpha(color)``: read a colour's alpha, 0 to 1."""
+    colour = _colour_of(base)
+    return ABSENT if colour is None else colour.a
+
+
+def with_alpha(base: Value, a: Value) -> Value:
+    """``withAlpha(color, a)``: the same colour at a stated alpha."""
+    colour = _colour_of(base)
+    amount = number(a)
+    if colour is None or amount is None:
+        return ABSENT
+    return make(colour.r, colour.g, colour.b, amount)

openscript/library/composites.py

@@ -0,0 +1,208 @@
+"""The means of `stdlib.md` section 20.3 that are built out of other means, and the fit.
+
+Four of these feed one average's output into another, absences and all, which is
+where their warmups come from: the outer average seeds on the first values the
+inner one produced, not on the first bars of the source. That composition is the
+whole reason `stdlib.md` section 1 states warmups in bars of the call's own
+source rather than in bars of the chart.
+
+The other two compute over the window directly: the Gaussian kernel, whose one
+dependence on the exponential puts it in gap 1 of section 20.11, and the least
+squares fit, whose constants are functions of the length alone.
+
+``named`` is here rather than beside the six means because it has to be able to
+select any of them, this file's included.
+"""
+
+import math
+
+from . import averages, elementary
+from .rounding import round_half_away
+from .series import Region, contributed, region, window
+from .values import ABSENT, Value, number, result, whole
+
+#: The six averages ``ma`` and the channel studies select by name, section 4.
+NAMED = ("sma", "ema", "wma", "rma", "hma", "vwma")
+
+
+def named(state: Region, ctx, value: Value, length: int | None, kind: Value) -> Value:
+    """``ma(src, len, type)``: exactly the named average's arithmetic.
+
+    Each type has a state region of its own, so a run that switched type mid
+    history starts the new average from its own seed rather than from what the
+    old one left behind. The volume weighted type reads the bar, which is why
+    this one takes the context that the five others have no use for.
+    """
+    if not isinstance(kind, str) or kind not in NAMED:
+        return ABSENT
+    held = region(state, kind)
+    if kind == "sma":
+        return averages.simple(held, value, length)
+    if kind == "ema":
+        return averages.exponential(held, value, length)
+    if kind == "wma":
+        return averages.linear(held, value, length)
+    if kind == "rma":
+        return averages.smoothed(held, value, length)
+    if kind == "hma":
+        return hull(held, value, length)
+    return averages.volume_weighted(held, value, ctx.bar("volume"), length)
+
+
+def half_length(length: int | None) -> int | None:
+    """``floor(len / 2)``, held at a minimum of 1: the inner length of ``hma``.
+
+    Section 4 fixes the outer length and says nothing about this one, so it is
+    gap 2 of section 20.11: an implementation choice recorded rather than a
+    reading of the page. Selecting the average by name reaches the gap as surely
+    as calling it.
+    """
+    if length is None:
+        return None
+    half = length // 2
+    return 1 if half < 1 else half
+
+
+def root_length(length: int | None) -> int | None:
+    """``round(sqrt(len))``, held at a minimum of 1: the outer length of ``hma``.
+
+    The rounding is section 8.1's, halves away from zero, and the square root is
+    the one call section 20.10 exempts from gap 1: IEEE-754 has it correctly
+    rounded, so it is bit identical on every conforming platform without a
+    portable implementation of its own.
+    """
+    if length is None:
+        return None
+    outer = whole(round_half_away(math.sqrt(float(length))))
+    return 1 if outer is None or outer < 1 else outer
+
+
+def hull(state: Region, value: Value, length: int | None) -> Value:
+    """``hma(src, len)``: three linearly weighted means, the raw one formed left to right.
+
+    The raw series is fed to the outer mean absences and all, so the outer mean
+    fills on the first ``outer`` values it produced, which is where the declared
+    warmup of ``len + round(sqrt(len)) - 2`` comes from.
+    """
+    fast = averages.linear(region(state, "half"), value, half_length(length))
+    slow = averages.linear(region(state, "full"), value, length)
+    raw = ABSENT
+    if isinstance(fast, float) and isinstance(slow, float):
+        raw = result(2 * fast - slow)
+    return averages.linear(region(state, "outer"), raw, root_length(length))
+
+
+def doubled(state: Region, value: Value, length: int | None) -> Value:
+    """``dema(src, len)``: ``2 * e1 - e2``, formed left to right."""
+    first, second, _third = _chain(state, value, length, 2)
+    if not isinstance(first, float) or not isinstance(second, float):
+        return ABSENT
+    return result(2 * first - second)
+
+
+def tripled(state: Region, value: Value, length: int | None) -> Value:
+    """``tema(src, len)``: three terms added left to right, not ``3 * (e1 - e2) + e3``."""
+    first, second, third = _chain(state, value, length, 3)
+    if not isinstance(first, float) or not isinstance(second, float):
+        return ABSENT
+    if not isinstance(third, float):
+        return ABSENT
+    return result(3 * first - 3 * second + third)
+
+
+def _chain(state: Region, value: Value, length: int | None, depth: int):
+    """The exponential means of a chain, each fed the previous one's output.
+
+    Absences and all: an average fed absence freezes rather than skipping, which
+    is what makes the third mean's warmup three times the length less three
+    rather than an accident of how much history happened to be present.
+    """
+    first = averages.exponential(region(state, "one"), value, length)
+    second = averages.exponential(region(state, "two"), first, length)
+    if depth < 3:
+        return first, second, ABSENT
+    third = averages.exponential(region(state, "three"), second, length)
+    return first, second, third
+
+
+def smoothed_three(state: Region, value: Value, length: int | None) -> Value:
+    """The third mean of the same chain, which is what ``trix`` takes the change of."""
+    _first, _second, third = _chain(state, value, length, 3)
+    return third
+
+
+def gaussian(
+    state: Region, value: Value, length: int | None, offset: Value, sigma: Value
+) -> Value:
+    """``alma(src, len, offset, sigma)``: the kernel built from the position, two passes.
+
+    Position 0 is the oldest bar of the window and both passes run over that
+    order. The denominator of the exponent is **one product, divided once**: the
+    chain of divisions in circulation differs on about one exponent in four.
+
+    **This is the one average whose value depends on ``exp``**, so it reaches gap
+    1 of section 20.11 and carries no cross-engine guarantee. The kernel depends
+    only on the position, so an engine may build it once per length, provided the
+    values it builds are the ones these lines produce.
+    """
+    values = contributed(state, "src", number(value), length)
+    held = window(values, length)
+    peak_at = number(offset)
+    width = number(sigma)
+    if held is None or length is None or peak_at is None or width is None:
+        return ABSENT
+    if width == 0:
+        return ABSENT
+    peak = peak_at * (length - 1)
+    spread = length / width
+    weights = []
+    norm = 0.0
+    for position in range(length):
+        gap = position - peak
+        weight = elementary.exp(-(gap * gap) / (2 * spread * spread))
+        if not isinstance(weight, float):
+            return ABSENT
+        weights.append(weight)
+        norm = norm + weight
+    running = 0.0
+    for position in range(length):
+        running = running + held[length - 1 - position] * weights[position]
+    if norm == 0:
+        return ABSENT
+    return result(running / norm)
+
+
+def fitted(state: Region, value: Value, length: int | None, offset: Value) -> Value:
+    """``linreg(src, len, offset)``: the least squares line, read ``offset`` bars back.
+
+    ``x`` runs 0 at the oldest bar of the window to ``len - 1`` at this one, and
+    the sums over ``x`` are constants of the length. **The sum of squares is one
+    product divided once**: splitting the 6 into the two factors it is made of
+    holds every intermediate below the whole product and parts company with this
+    at 3716 of the first hundred thousand lengths, the first at a length of 15.
+
+    The two accumulations each add their own terms oldest first and neither reads
+    the other, so whether an engine runs them in one pass or two is not fixed.
+    The result is absent where the divisor is zero, which is every window of
+    length 1: a line fitted to one point is not a fit.
+    """
+    values = contributed(state, "src", number(value), length)
+    held = window(values, length)
+    back = number(offset)
+    if held is None or length is None or back is None:
+        return ABSENT
+    span = float(length)
+    sum_x = ((span - 1) * span) / 2
+    sum_x_squared = ((span - 1) * span * (2 * span - 1)) / 6
+    divisor = span * sum_x_squared - sum_x * sum_x
+    if divisor == 0:
+        return ABSENT
+    sum_y = 0.0
+    sum_xy = 0.0
+    for position in range(length):
+        y = held[length - 1 - position]
+        sum_y = sum_y + y
+        sum_xy = sum_xy + y * float(position)
+    slope = (span * sum_xy - sum_x * sum_y) / divisor
+    intercept = (sum_y - slope * sum_x) / span
+    return result(intercept + slope * (span - 1 - back))

openscript/library/counting.py

@@ -0,0 +1,218 @@
+"""The totals, the ranks and the two pair statistics of `stdlib.md` section 20.8.
+
+Every window here is the fresh oldest first sum of section 20.2.1 or a scan over
+the same window, and the three that pass over an absent bar say so in their
+names, which is section 2.4's rule and the reason they are three functions rather
+than a flag on the others.
+
+**The two pair statistics are two passes and are population forms.** The means
+are finished before any deviation is taken. The single pass arrangement, summing
+squares and cross products and subtracting at the end, 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.
+"""
+
+from typing import Optional, Sequence
+
+from . import elementary
+from .series import Region, back, contributed, raw_window, running_total, total, window
+from .values import ABSENT, Value, floor_of, number, result
+
+
+def windowed_sum(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``sum(src, len)``: the window sum of 20.2.1."""
+    held = window(contributed(state, "src", number(value), length), length)
+    return ABSENT if held is None else result(total(held))
+
+
+def counted(state: Region, condition: Value, length: Optional[int]) -> Value:
+    """``count(cond, len)``: the same sum over a window of ones and zeros.
+
+    A count is an addition of whole numbers and is therefore exact, which is why
+    it can be the same sum rather than a scan of its own.
+
+    **An absent condition is a bar the condition did not hold**, and not a hole
+    that makes the count absent. The window still has to be full of bars, so the
+    warmup is the window's, but a bar nobody could evaluate is counted as false:
+    the reading is how many of the last ``len`` bars the condition held on, and
+    an unknown bar is not one of them.
+    """
+    term = 1.0 if condition is True else 0.0
+    held = window(contributed(state, "cond", term, length), length)
+    return ABSENT if held is None else result(total(held))
+
+
+def accumulated(state: Region, value: Value) -> Value:
+    """``cum(src)``: the running total from the first bar, on section 20.6's terms."""
+    return running_total(state, "run", number(value))
+
+
+def skipping_sum(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``sumSkip(src, len)``: the same oldest first sum with the absent bars passed over.
+
+    A window with nothing present in it is the empty accumulation: the sum is the
+    0 it started at and is reported as 0. The window still has to be full of
+    bars, which is why the warmup is the same as the window sum's.
+    """
+    held = raw_window(contributed(state, "src", number(value), length), length)
+    if held is None:
+        return ABSENT
+    return result(total(_present(held)))
+
+
+def skipping_mean(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``avgSkip(src, len)``: that sum over the number of bars that had a value.
+
+    Dividing by ``len`` would be a different quantity. A window with nothing
+    present in it has a divisor of zero and is absent, which is the one place
+    this and ``sumSkip`` part company.
+    """
+    held = raw_window(contributed(state, "src", number(value), length), length)
+    if held is None:
+        return ABSENT
+    present = _present(held)
+    if not present:
+        return ABSENT
+    return result(total(present) / len(present))
+
+
+def present_count(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``countPresent(src, len)``: how many bars of the window had a value."""
+    held = raw_window(contributed(state, "src", number(value), length), length)
+    return ABSENT if held is None else float(len(_present(held)))
+
+
+def ranked(state: Region, value: Value, length: Optional[int], percent: Value) -> Value:
+    """``percentile(src, len, p)``: linear interpolation between the two ranks either side.
+
+    The nearest rank method, which returns an actual member of the window, is the
+    other common choice and is not this one: an even length window is the mean of
+    its two middles rather than one of them chosen by a rule nobody remembers.
+    """
+    held = window(contributed(state, "src", number(value), length), length)
+    return _interpolated(held, length, number(percent))
+
+
+def middle(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``median(src, len)``: the same at ``p`` of 50 and nothing else."""
+    held = window(contributed(state, "src", number(value), length), length)
+    return _interpolated(held, length, 50.0)
+
+
+def rank_of(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``percentRank(src, len)``: this bar's value counted among the window.
+
+    The bar counts itself, so the reading runs from ``100 / len`` to 100 rather
+    than from 0.
+    """
+    held = window(contributed(state, "src", number(value), length), length)
+    if held is None or length is None:
+        return ABSENT
+    counted_below = 0
+    for other in held:
+        if other <= held[0]:
+            counted_below = counted_below + 1
+    return result((float(counted_below) * 100) / length)
+
+
+def covariance(
+    state: Region, first: Value, second: Value, length: Optional[int]
+) -> Value:
+    """``covariance(a, b, len)``: the population form, two passes over both windows."""
+    pair = _pair(state, first, second, length)
+    if pair is None or length is None:
+        return ABSENT
+    left, right = pair
+    cross, _squares_left, _squares_right = _deviations(left, right, length)
+    return result(cross / length)
+
+
+def correlation(
+    state: Region, first: Value, second: Value, length: Optional[int]
+) -> Value:
+    """``correlation(a, b, len)``: that covariance over a product of two square roots.
+
+    **It is not the square root of a product**: the two are mathematically equal,
+    differ in the last bit, and this is the one the page states.
+    """
+    pair = _pair(state, first, second, length)
+    if pair is None or length is None:
+        return ABSENT
+    left, right = pair
+    cross, squares_left, squares_right = _deviations(left, right, length)
+    spread_left = elementary.sqrt(squares_left / length)
+    spread_right = elementary.sqrt(squares_right / length)
+    if not isinstance(spread_left, float) or not isinstance(spread_right, float):
+        return ABSENT
+    divisor = spread_left * spread_right
+    if divisor == 0:
+        return ABSENT
+    return result((cross / length) / divisor)
+
+
+def _pair(state: Region, first: Value, second: Value, length: Optional[int]):
+    """Both windows, or absence where either is short or holed.
+
+    Both series are contributed on every bar whatever the other one did, because
+    a bar one of them was absent on is still a bar the pair covered.
+    """
+    left = window(contributed(state, "a", number(first), length), length)
+    right = window(contributed(state, "b", number(second), length), length)
+    if left is None or right is None:
+        return None
+    return left, right
+
+
+def _deviations(left: Sequence[float], right: Sequence[float], length: int):
+    """The three second pass accumulations, each oldest first over its own terms.
+
+    None of the three reads another, so neither the order they are written in nor
+    whether an engine runs them in one pass or in three is fixed: section 20.1's
+    fourth rule. What the two passes do fix is that both means are finished
+    before any deviation is taken.
+    """
+    mean_left = total(left) / length
+    mean_right = total(right) / length
+    cross = 0.0
+    squares_left = 0.0
+    squares_right = 0.0
+    for at in range(length - 1, -1, -1):
+        cross = cross + (left[at] - mean_left) * (right[at] - mean_right)
+        squares_left = squares_left + (left[at] - mean_left) * (left[at] - mean_left)
+        squares_right = squares_right + (right[at] - mean_right) * (right[at] - mean_right)
+    return cross, squares_left, squares_right
+
+
+def _present(held: Sequence[Value]) -> list:
+    """The values of a raw window that are there, newest first as they arrived."""
+    return [value for value in held if isinstance(value, float)]
+
+
+def _interpolated(
+    held: Optional[Sequence[float]], length: Optional[int], percent: Optional[float]
+) -> Value:
+    """The rank read off the sorted window, interpolated between the two either side."""
+    if held is None or length is None or percent is None:
+        return ABSENT
+    ascending = sorted(held)
+    rank = (percent / 100) * (length - 1)
+    below = floor_of(rank)
+    if below < 0 or below >= length:
+        return ABSENT
+    at = int(below)
+    if at >= length - 1:
+        return result(ascending[at])
+    return result(ascending[at] + (rank - below) * (ascending[at + 1] - ascending[at]))
+
+
+def history_at(state: Region, value: Value, offset: Optional[int]) -> Value:
+    """``history(src, n)``: ``src`` as it stood ``n`` bars ago, the explicit ``src[n]``.
+
+    One operation and no accumulation, section 20.10. It is here rather than
+    beside the bookkeeping because what it reads is the same buffer every window
+    in this file is read from.
+    """
+    keep = None if offset is None else offset + 1
+    return back(contributed(state, "src", value, keep), offset)