Macaw.Data.Reduce (macaw_data v0.16.0)
View SourceShape-preserving downsampling (spec/01 §2.4): the two reducers finishing uses to bring a delivery within a budget.
lttb/3, Largest-Triangle-Three-Buckets, keeps aboutnpoints chosen to keep a series' visual shape;m4/3keeps, per pixel column, the first, last, least and greatest points, which a line drawn that wide needs to draw the same pixels as all of them.
Both treat a datum whose x or y is not a number as a gap, kept in place, so a line
over the result still breaks where the input broke. Ported from visualize's
Visualize.Data.lttb/3 and m4/3.
Both answer {:ok, elements} or {:error, reason} (spec/00 §5): arithmetic past a
float's range is {:values, :overflow}, never ArithmeticError (macaw_data#192). Their
! twins answer the elements or raise Macaw.Data.Error.
Summary
Types
Why a reduction is refused (format_error/1).
Functions
A refusal's words.
Largest-Triangle-Three-Buckets: about n of the elements, chosen to keep the series'
visual shape (Steinarsson 2013).
As lttb/3, the elements alone, raising Macaw.Data.Error in format_error/1's words.
M4: per pixel column, the first, last, least-y and greatest-y elements — the
elements a line drawn width pixels wide needs to draw the same pixels as all of them
(Jugel et al. 2014).
As m4/3, the elements alone, raising Macaw.Data.Error in format_error/1's words.
Types
@type reason() :: {:data, :list | :pair} | {:n, term()} | {:width, term()} | {:accessor, term()} | {:values, :overflow}
Why a reduction is refused (format_error/1).
Functions
A refusal's words.
iex> Macaw.Data.Reduce.format_error({:n, 2})
"n is an integer of at least 3, not 2"
@spec lttb([any()], pos_integer(), (any() -> {term(), term()}) | nil) :: {:ok, [any()]} | {:error, reason()}
Largest-Triangle-Three-Buckets: about n of the elements, chosen to keep the series'
visual shape (Steinarsson 2013).
The accessor returns {x, y}; without one the elements are {x, y} tuples. A datum
whose x or y is not a number is a gap: the defined data are reduced run by run
between the gaps, and each run of gaps keeps its first element in place, so a line over
the result still breaks where the input broke. Input of n or fewer elements is
returned unchanged; without gaps the result is exactly n elements, the first and the
last among them. n must be at least 3.
A refusal is {:data, :list}, {:data, :pair}, {:n, n}, {:accessor, accessor} or
{:values, :overflow}: a bucket's sum, or a triangle over the extents, at half the
largest float or past it (spec/04 §4.4).
Examples
iex> Macaw.Data.Reduce.lttb([{0, 0}, {1, 1}, {2, 0}, {3, 5}, {4, 0}, {5, 1}, {6, 0}], 4)
{:ok, [{0, 0}, {2, 0}, {3, 5}, {6, 0}]}
iex> Macaw.Data.Reduce.lttb([{0, 0}, {1, 3}, {2, nil}, {3, 4}, {4, 1}], 9)
{:ok, [{0, 0}, {1, 3}, {2, nil}, {3, 4}, {4, 1}]}
iex> Macaw.Data.Reduce.lttb([{1.0e308, 1}, {-1.0e308, 2}, {1.0e308, 3}, {-1.0e308, 4}], 3)
{:error, {:values, :overflow}}
As lttb/3, the elements alone, raising Macaw.Data.Error in format_error/1's words.
@spec m4([any()], pos_integer(), (any() -> {term(), term()}) | nil) :: {:ok, [any()]} | {:error, reason()}
M4: per pixel column, the first, last, least-y and greatest-y elements — the
elements a line drawn width pixels wide needs to draw the same pixels as all of them
(Jugel et al. 2014).
The columns split the extent of the defined x readings evenly. The accessor, the gaps
and the runs are as lttb/3's: each run of gaps keeps its first element in place, and
each stretch of one run in one column keeps at most four elements, deduplicated and in
input order. width must be at least 1.
A refusal is {:data, :list}, {:data, :pair}, {:width, width},
{:accessor, accessor} or {:values, :overflow}: an x at half the largest float or
past it, as the m4 step's (spec/04 §4.5.1).
Examples
iex> Macaw.Data.Reduce.m4([{0, 1}, {1, 5}, {2, 0}, {3, 2}, {4, 3}, {5, 9}, {6, 4}, {7, 6}], 2)
{:ok, [{0, 1}, {1, 5}, {2, 0}, {3, 2}, {4, 3}, {5, 9}, {7, 6}]}
iex> Macaw.Data.Reduce.m4([{0, 1}, {1, 2}, {2, nil}, {3, nil}, {4, 3}], 1)
{:ok, [{0, 1}, {1, 2}, {2, nil}, {4, 3}]}
iex> Macaw.Data.Reduce.m4([{1.0e308, 1}, {-1.0e308, 2}], 2)
{:error, {:values, :overflow}}
As m4/3, the elements alone, raising Macaw.Data.Error in format_error/1's words.