Macaw.Data.Stack (macaw_data v0.16.0)

View Source

d3-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

point()

@type point() :: %{
  key: any(),
  index: non_neg_integer(),
  data: any(),
  value: number(),
  y0: number(),
  y1: number()
}

series()

@type series() :: %{key: any(), index: non_neg_integer(), points: [point()]}

t()

@type t() :: %Macaw.Data.Stack{
  keys: [any()],
  offset: :none | :expand | :diverging | :silhouette | :wiggle,
  order:
    :none | :ascending | :descending | :reverse | :insideout | {:keys, [any()]},
  value: (map(), any() -> number()) | nil
}

Functions

generate(stack, data)

@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}]}

generate!(stack, data)

@spec generate!(t(), Macaw.Data.Table.source()) :: [series()]

As generate/2, the series alone, raising Macaw.Data.Error with its faults.

keys(stack, keys)

@spec keys(t(), [any()]) :: t()

Sets the keys to stack.

Keys determine the layers in the stack, typically field names.

new()

@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.

offset(stack, offset)

@spec offset(t(), atom()) :: t()

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)

order(stack, order)

@spec order(t(), atom() | {:keys, [any()]}) :: t()

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's stackOrderInsideOut: 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]

series(stack, data)

@spec series(t(), [term()]) :: [series()]

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.

stacked(stack, data)

@spec stacked(t(), [term()]) :: {:ok, [series()]} | {:error, [{list(), term()}, ...]}

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}}]}

stacked!(stack, data)

@spec stacked!(t(), [term()]) :: [series()]

As stacked/2, the series alone, raising Macaw.Data.Error with its faults.

value(stack, func)

@spec value(t(), (map(), any() -> number())) :: t()

Sets the value accessor function.

The function receives (datum, key) and returns a number.