Macaw.Data.Aggregate behaviour (macaw_data v0.18.0)
View SourceThe aggregate behavior (spec/04 §1.2): a statistic, one column's readings reduced to one value (visualize#909).
reduce/2 is given the readings with every nil dropped, since a gap is absence, never
zero (spec/01 §1.1). An aggregate may also give the streaming form, init/1, step/3
and finish/2 together, over the same readings in the same order:
finish(Enum.reduce(values, init(options), &step(&2, &1, options)), options)
== reduce(values, options)An aggregate with the streaming form may also give the combining form, merge/3: the
state of two runs of readings from each run's state, associative, so a table's chunks
are reduced one by one and their states merged (spec/04 §1.4).
Its options are checked as a transform's are (Macaw.Data.Operations.Option), and may
not be a key of a step that names it (Macaw.Data.Operations.step_keys/0): the registry
refuses one that is.
Summary
Callbacks
The streaming form's value of its state, or {:error, reason} as reduce/2's.
The streaming form's first state.
Whether the input's unit and quantity carry to the output.
The combining form (spec/04 §1.2): the state of two runs of readings, the first
before the second, from each run's state. Associative, so a step's per-chunk partials
merge under any grouping: merge(state(a), state(b)) == state(a ++ b) by value.
The name a node's fn or a stored function names, unique in a registry.
The keys the aggregate reads.
The output's table type for an input column of type.
What every reading is read as (spec/04 §3.1, §5), checked over the readings before any
is reduced, so reduce/2 and step/3 never meet another: :number, :comparable
(numbers, or times of any kinds, not both), :point (a number or a point [x, y]), or :any,
the default when an aggregate does not say.
The value of the readings, nils already dropped; or {:error, reason} where no value
of the output's type holds it (sum and mean beyond a float's range: :overflow),
which the caller answers as a fault (spec/04 §3.1, §5).
The inverse of the combining form, where it is exact (spec/04 §1.2, §1.5): the state of
a run of readings with some of them removed, from the run's state and the removed
readings' state, {:ok, state}; :inexact where the subtraction could differ from
the state of the remaining readings, as a floating-point sum's would.
The streaming form's state after one more reading.
Functions
What aggregate's readings are read as: its reads/0, :any when it has none.
Types
Callbacks
The streaming form's value of its state, or {:error, reason} as reduce/2's.
The streaming form's first state.
@callback keeps_unit?() :: boolean()
Whether the input's unit and quantity carry to the output.
The combining form (spec/04 §1.2): the state of two runs of readings, the first
before the second, from each run's state. Associative, so a step's per-chunk partials
merge under any grouping: merge(state(a), state(b)) == state(a ++ b) by value.
@callback name() :: String.t()
The name a node's fn or a stored function names, unique in a registry.
@callback options() :: [{String.t(), Macaw.Data.Operations.Option.t()}]
The keys the aggregate reads.
@callback output(Macaw.Data.Table.type(), options()) :: Macaw.Data.Table.type()
The output's table type for an input column of type.
@callback reads() :: :number | :comparable | :point | :any
What every reading is read as (spec/04 §3.1, §5), checked over the readings before any
is reduced, so reduce/2 and step/3 never meet another: :number, :comparable
(numbers, or times of any kinds, not both), :point (a number or a point [x, y]), or :any,
the default when an aggregate does not say.
The value of the readings, nils already dropped; or {:error, reason} where no value
of the output's type holds it (sum and mean beyond a float's range: :overflow),
which the caller answers as a fault (spec/04 §3.1, §5).
The inverse of the combining form, where it is exact (spec/04 §1.2, §1.5): the state of
a run of readings with some of them removed, from the run's state and the removed
readings' state, {:ok, state}; :inexact where the subtraction could differ from
the state of the remaining readings, as a floating-point sum's would.
The streaming form's state after one more reading.
Functions
@spec reads(module()) :: :number | :comparable | :point | :any
What aggregate's readings are read as: its reads/0, :any when it has none.