Macaw.Data.Stack (macaw_data v0.13.0)
View Sourced3-shape's stack (spec/04 §4.8): a baseline for each datum, so layers of data stack on
one another. The engine of the stack transform, ported from visualize's
Visualize.Shape.Stack.
Examples
data = [
%{month: "Jan", apples: 10, oranges: 20, bananas: 15},
%{month: "Feb", apples: 15, oranges: 25, bananas: 10},
%{month: "Mar", apples: 20, oranges: 15, bananas: 25}
]
stack = Macaw.Data.Stack.new()
|> Macaw.Data.Stack.keys([:apples, :oranges, :bananas])
{:ok, series} = Macaw.Data.Stack.generate(stack, data)
# One series per key, in key order, each with :key, :index (its position
# in the stacking order) and :points. Points have :data, :y0 (baseline), :y1 (top).
Summary
Functions
Generates the stacked series data.
As generate/2, the series alone, raising Macaw.Data.Error with its faults.
Sets the keys to stack.
Creates a new stack generator. Its value function reads a datum's key by name
(Macaw.Data.Table.get/2), nil read as 0, so it reads rows that have names.
Sets the stack offset.
Sets the stack order.
stacked!/2: the series as a bare list, raising Macaw.Data.Error on a value that is no
number or a sum past a float's range. stacked/2 answers those as values.
As generate/2, over a list of data each given to the value function as it is: no
source read as rows, so no source's fault. {:ok, series}, or the faults of a value that
is no number and of a sum past a float's range. The stack step stacks row places so
(spec/04 §4.8).
As stacked/2, the series alone, raising Macaw.Data.Error with its faults.
Sets the value accessor function.
Types
Functions
@spec generate(t(), Macaw.Data.Table.source()) :: {:ok, [series()]} | {:error, [{list(), term()}, ...]}
Generates the stacked series data.
{:ok, series}: one series per key, in key order, each a map with:
:key- The series key:index- The series' position in the stacking order (0 is the bottom):points- One point per datum with:data,:value,:y0,:y1,:index
The data is any source, read by Macaw.Data.Table.rows/1; a source of no shape it
reads is Macaw.Data.Table.source/1's {:error, faults} (macaw_data#161). Rows with
no names, a tensor's or tuple rows, are {:error, [{[:names], :required}]} under the
default value function, which reads by name: Macaw.Data.Table.named/2 names them, or
value/2 reads them another way.
A value that is no number is {[key, j], {:reads, :number}}, row j under key, every
one at once, whichever function read it. The default function reads nil as 0; a
caller's answering nil answers no number (macawdata#178). A stack of one key under
the :none offset and an order that reads no value (:none, :reverse, `{:keys, }`)
does no arithmetic, so it reads nothing as a number and answers each value as it is.
A sum past a float's range is :overflow: {[key, j], :overflow} for a point, or
{[:order], :overflow} for a series' sum an order reads. What a float holds answers as
the BEAM's arithmetic does; integers alone never overflow.
iex> alias Macaw.Data.Stack
iex> Stack.new() |> Stack.keys([:a]) |> Stack.generate([%{a: 1}, 2])
{:error, [{[], {:type, :rows}}]}
iex> Stack.new() |> Stack.keys([:a]) |> Stack.generate([{1, 2}])
{:error, [{[:names], :required}]}
iex> Stack.new() |> Stack.keys([:a, :b]) |> Stack.generate([%{a: 1, b: "x"}])
{:error, [{[:b, 0], {:reads, :number}}]}
iex> Stack.new() |> Stack.keys([:a, :b]) |> Stack.generate([%{a: 1.0e308, b: 1.0e308}])
{:error, [{[:b, 0], :overflow}]}
@spec generate!(t(), Macaw.Data.Table.source()) :: [series()]
As generate/2, the series alone, raising Macaw.Data.Error with its faults.
Sets the keys to stack.
Keys determine the layers in the stack, typically field names.
@spec new() :: t()
Creates a new stack generator. Its value function reads a datum's key by name
(Macaw.Data.Table.get/2), nil read as 0, so it reads rows that have names.
Sets the stack offset.
:none- Zero baseline (default):expand- Normalize to 0-1 (100% stacked):diverging- Positive values stack up from zero, negative values stack down from zero:silhouette- Center the stack around zero:wiggle- Minimize weighted wiggle (for streamgraphs)
Sets the stack order.
:none- Use key order (default):ascending- Smallest series on bottom:descending- Largest series on bottom:reverse- Reverse key order:insideout- d3'sstackOrderInsideOut: the earliest-peaking series in the middle, later ones outward on whichever side has the smaller sum (good for streamgraphs){:keys, list}- The listed keys bottom first, then the unlisted keys in key order; a listed key the stack does not have is ignored (spec/04 §4.8)
Every order but {:keys, list} is computed from the data generate/2 is given, so over
a stream of data it can change between frames; {:keys, list} is fixed.
iex> alias Macaw.Data.Stack
iex> Stack.new()
...> |> Stack.keys([:a, :b, :c])
...> |> Stack.order({:keys, [:c, :x, :a]})
...> |> Stack.generate!([%{a: 1, b: 2, c: 3}])
...> |> Enum.map(&{&1.key, &1.index})
[a: 1, b: 2, c: 0]
stacked!/2: the series as a bare list, raising Macaw.Data.Error on a value that is no
number or a sum past a float's range. stacked/2 answers those as values.
As generate/2, over a list of data each given to the value function as it is: no
source read as rows, so no source's fault. {:ok, series}, or the faults of a value that
is no number and of a sum past a float's range. The stack step stacks row places so
(spec/04 §4.8).
iex> alias Macaw.Data.Stack
iex> stack = Stack.new() |> Stack.keys([:a, :b]) |> Stack.value(fn d, _key -> d end)
iex> Stack.stacked(stack, [:no_number])
{:error, [{[:a, 0], {:reads, :number}}, {[:b, 0], {:reads, :number}}]}
As stacked/2, the series alone, raising Macaw.Data.Error with its faults.
Sets the value accessor function.
The function receives (datum, key) and returns a number.