Macaw.Data.Source.Signal (macaw_data v0.18.0)
View SourceA generated source (spec/01 §10.1): rows that are a pure function of the tick, so a design under construction moves and replays without a host supplying any data.
A signal is a kind (:sine, :square, :random or :discrete), its fields and a
wave's shape: window (rows in a tick's own window, 24), period (12), min and
max (0 and 100) and seed (0). The first field is the tick, every other a value
column following the kind's wave, each shifted from the last so no two columns are one
line. rows/2 is the window of rows ending at a tick, rows/3 the rows of a span of
ticks: the same tick always gives the same rows.
As a source it is pulled, never pushed. Its present tick is fixed (tick:, moved with
at/2) or read from the request's now, every: milliseconds a tick counted from
origin: (the Unix epoch by default), so one request with one now has one answer
(spec/01 §2.3). Its schema describes the tick as the :number window field, labeled
"Tick", and every other field :number, under whatever describe: adds field by
field. It honors :window: a window is ticks, served up to the present tick, at most
limit: rows (10_000) and capped beyond. Its rows are a chunked
Macaw.Data.Table of the signal's origin, a tick its resolution, so a tick's row sits in
the same chunk on every fetch.
Ported from visualize's Visualize.Signals and Visualize.Feed.Signals: the same rows
for the same tick.
Examples
iex> alias Macaw.Data.Source.Signal
iex> {:ok, sine} = Signal.new(:sine, [:t, :value], window: 3, period: 4)
iex> Signal.rows(sine, 2) |> Enum.map(&{&1.t, round(&1.value)})
[{0, 50}, {1, 100}, {2, 50}]
iex> Signal.rows(sine, 0) |> Enum.map(& &1.t)
[0]
iex> alias Macaw.Data.Source
iex> {:ok, signal} = Source.Signal.new(:discrete, [:t, :n], tick: 10, describe: %{n: %{label: "Count"}})
iex> {:ok, %{supports: [:window]} = description} = Source.describe(signal, nil)
iex> Macaw.Data.Schema.fetch(description.schema, :n, :label)
{:ok, "Count"}
iex> request = Source.Request.new!(window: [4, 99], now: ~U[2026-11-01 00:00:00Z])
iex> {:ok, delivery} = Source.fetch(signal, description, request)
iex> {Macaw.Data.Table.column(delivery.rows, "t"), delivery.served.window}
{[4, 5, 6, 7, 8, 9, 10], [4, 10]}
iex> Macaw.Data.Source.Signal.new(:saw, [:t], every: 0)
{:error, [{[:every], {:type, :pos_integer}}, {[:kind], {:enum, [:sine, :square, :random, :discrete]}}]}
Summary
Functions
A signal moved to a fixed tick.
A reason's words (spec/00 §5): this module's, else the library's.
The four kinds.
A signal of the kind over the fields, the first the tick and the rest values:
{:ok, signal}, or every fault at once by path (spec/00 §5). Options: the wave's
window:, period:, min:, max: and seed:, and the source's describe: (a map of
field descriptions merged over the defaults, field by field), tick: (the present
tick, 0), every: (milliseconds a tick, counted from origin: to the request's
now; nil for the fixed tick) and limit: (the most rows one fetch serves).
As new/3, the signal alone, raising Macaw.Data.Error naming the faults.
The window of rows ending at the tick: one row a tick from tick − window + 1 to
tick, none below zero, the tick field the tick and each value field its kind's value
there. Rows are maps keyed by the fields as given.
One row a tick from max(from, 0) to to, whatever the signal's window; none when
to is below that.
Types
@type kind() :: :sine | :square | :random | :discrete
@type t() :: %Macaw.Data.Source.Signal{ every: pos_integer() | nil, fields: [atom() | String.t(), ...], kind: kind(), limit: pos_integer(), max: number(), min: number(), origin: DateTime.t(), period: number(), schema: Macaw.Data.Schema.t(), seed: integer(), tick: non_neg_integer(), window: pos_integer() }
Functions
@spec at(t(), non_neg_integer()) :: t()
A signal moved to a fixed tick.
A reason's words (spec/00 §5): this module's, else the library's.
@spec kinds() :: [kind(), ...]
The four kinds.
A signal of the kind over the fields, the first the tick and the rest values:
{:ok, signal}, or every fault at once by path (spec/00 §5). Options: the wave's
window:, period:, min:, max: and seed:, and the source's describe: (a map of
field descriptions merged over the defaults, field by field), tick: (the present
tick, 0), every: (milliseconds a tick, counted from origin: to the request's
now; nil for the fixed tick) and limit: (the most rows one fetch serves).
The faults: {[:kind], {:enum, kinds}}; {[:fields], {:type, :fields}} for anything
but a list of distinct atom or string names, at least one; {[key], {:type, type}} for
an option of the wrong type (:pos_integer for window, every and limit,
:number for period (positive), min and max, :integer for seed,
:non_neg_integer for tick, :datetime for origin, :map for describe);
{[key], :unknown_key} for an option it does not take; and the schema's own faults
under [:describe] for descriptions it refuses.
As new/3, the signal alone, raising Macaw.Data.Error naming the faults.
@spec rows(t(), non_neg_integer()) :: [map()]
The window of rows ending at the tick: one row a tick from tick − window + 1 to
tick, none below zero, the tick field the tick and each value field its kind's value
there. Rows are maps keyed by the fields as given.
One row a tick from max(from, 0) to to, whatever the signal's window; none when
to is below that.
iex> {:ok, counter} = Macaw.Data.Source.Signal.new(:discrete, [:t, :n], window: 2)
iex> Macaw.Data.Source.Signal.rows(counter, -1, 2) |> Enum.map(& &1.t)
[0, 1, 2]