Sooth.Predictor (Sooth v0.2.1)
Provides the Predictor module for Sooth.
This is the main entry point for the Sooth library.
Summary
Functions
Return the number of times the context has been observed.
Return a stream that yields each observed event within the context together with its probability.
Find a context in the predictor.
Return a number indicating the frequency that the event has been observed within the given context.
Returns a new Sooth.Predictor.
Register an observation of the given event within the given context.
Return an event that may occur in the given context, based on the limit, which should be between 1 and #count. The event is selected by iterating through all observed events for the context, subtracting the observation count of each event from the limit until it is zero or less.
Return the number of different events that have been observed within the given context.
Return a number indicating the surprise received by the predictor when it observed the given event within the given context. Note that nil will be returned if the event has never been observed within the context.
Return a number indicating how uncertain the predictor is about which event is likely to be observed after the given context. Note that nil will be returned if the context has never been observed.
Types
@type t() :: %Sooth.Predictor{ contexts: Aja.Vector.t(Sooth.Context.t()), error_event: non_neg_integer() }
A Predictor of error_event/contexts
Functions
count(predictor, id)
@spec count(t(), non_neg_integer()) :: non_neg_integer()
Return the number of times the context has been observed.
Parameters
predictor
- The predictor that will count the context.id
- A number that provides a context for observations.
Examples
iex> predictor =
...> Sooth.Predictor.new(0)
...> |> Sooth.Predictor.observe(2, 3)
...> |> Sooth.Predictor.observe(2, 3)
...> |> Sooth.Predictor.observe(2, 2)
iex> Sooth.Predictor.count(predictor, 2)
3
iex> Sooth.Predictor.count(predictor, 3)
0
distribution(predictor, id)
@spec distribution(t(), non_neg_integer()) :: nil | [{non_neg_integer(), float()}]
Return a stream that yields each observed event within the context together with its probability.
Parameters
predictor
- The predictor that will calculate the distribution.id
- A number that provides a context for the distribution.
Examples
iex> predictor = Sooth.Predictor.new(0)
...> |> Sooth.Predictor.observe(0, 3)
...> |> Sooth.Predictor.observe(0, 2)
iex> Sooth.Predictor.distribution(predictor, 0)
[{2, 0.5}, {3, 0.5}]
iex> Sooth.Predictor.distribution(predictor, 1)
nil
find_context(predictor, id)
@spec find_context(t(), non_neg_integer()) :: {t(), Sooth.Context.t(), non_neg_integer()}
Find a context in the predictor.
This is an implementation detail and should not be used directly.
frequency(predictor, id, event)
@spec frequency(t(), non_neg_integer(), non_neg_integer()) :: float()
Return a number indicating the frequency that the event has been observed within the given context.
Parameters
predictor
- The predictor that will calculate the frequency.id
- A number that provides a context for the frequency.event
- A number representing the observed event.
Examples
iex> predictor = Sooth.Predictor.new(0)
...> |> Sooth.Predictor.observe(0, 3)
...> |> Sooth.Predictor.observe(0, 3)
...> |> Sooth.Predictor.observe(0, 4)
...> |> Sooth.Predictor.observe(0, 5)
...> |> Sooth.Predictor.observe(1, 2)
iex> Sooth.Predictor.frequency(predictor, 0, 3)
0.5
iex> Sooth.Predictor.frequency(predictor, 0, 4)
0.25
iex> Sooth.Predictor.frequency(predictor, 0, 5)
0.25
iex> Sooth.Predictor.frequency(predictor, 1, 2)
1.0
new(error_event)
@spec new(non_neg_integer()) :: t()
Returns a new Sooth.Predictor.
Parameters
error_event
- The event to be returned by #select when no observations have been made for the context.
Examples
iex> Sooth.Predictor.new(2)
%Sooth.Predictor{error_event: 2, contexts: vec([])}
observe(predictor, id, event)
@spec observe(t(), non_neg_integer(), non_neg_integer()) :: t()
Register an observation of the given event within the given context.
Parameters
predictor
- The predictor that will observe the event.id
- A number that provides a context for the event, allowing the predictor to maintain observation statistics for different contexts.event
- A number representing the observed event.
Options
:include_count
- If this option is given, the function will return the count of the context.:include_statistic
- If this option is given, the function will return the statistic of the event.
Examples
iex> predictor = Sooth.Predictor.new(0)
iex> {predictor, count} = Sooth.Predictor.observe(predictor, 0, 3, :include_count)
iex> predictor
%Sooth.Predictor{
error_event: 0,
contexts: vec([
%Sooth.Context{id: 0, count: 1, statistics: vec([%Sooth.Statistic{event: 3, count: 1}])}
])
}
iex> count
1
observe(predictor, id, event, atom)
@spec observe( t(), non_neg_integer(), non_neg_integer(), :include_count ) :: {t(), non_neg_integer()}
@spec observe( t(), non_neg_integer(), non_neg_integer(), :include_statistic ) :: {t(), Sooth.Statistic.t()}
select(predictor, id, limit)
@spec select(t(), non_neg_integer(), non_neg_integer()) :: non_neg_integer()
Return an event that may occur in the given context, based on the limit, which should be between 1 and #count. The event is selected by iterating through all observed events for the context, subtracting the observation count of each event from the limit until it is zero or less.
Returns:
An event that has been previously observed in the given context, or the error_event
if the count
of the context is zero, or if limit exceeds the count
of the context.
Parameters
predictor
- The predictor that will select the event.id
- A number that provides a context for observations.limit
- The total number of event observations to be analysed before returning a event.
Examples
iex> predictor = Sooth.Predictor.new(99)
...> |> Sooth.Predictor.observe(1, 4)
...> |> Sooth.Predictor.observe(1, 3)
...> |> Sooth.Predictor.observe(1, 4)
...> |> Sooth.Predictor.observe(1, 5)
iex> Sooth.Predictor.select(predictor, 1, 1)
3
iex> Sooth.Predictor.select(predictor, 1, 2)
4
iex> Sooth.Predictor.select(predictor, 1, 3)
4
iex> Sooth.Predictor.select(predictor, 1, 4)
5
iex> Sooth.Predictor.select(predictor, 0, 0)
99
iex> Sooth.Predictor.select(predictor, 1, 5)
99
size(predictor, id)
@spec size(t(), non_neg_integer()) :: non_neg_integer()
Return the number of different events that have been observed within the given context.
Parameters
predictor
- The predictor that will calculate the size.id
- A number that provides a context for observations.
Examples
iex> predictor = Sooth.Predictor.new(0)
...> |> Sooth.Predictor.observe(0, 3)
...> |> Sooth.Predictor.observe(0, 3)
...> |> Sooth.Predictor.observe(0, 3)
...> |> Sooth.Predictor.observe(0, 1)
iex> Sooth.Predictor.size(predictor, 0)
2
surprise(predictor, id, event)
Return a number indicating the surprise received by the predictor when it observed the given event within the given context. Note that nil will be returned if the event has never been observed within the context.
Returns:
The surprise, which is calculated to be the Shannon pointwise mutual information
of the event according to the distribution
over the context.
Parameters
predictor
- The predictor that will calculate the surprise.id
- A number that provides a context for observations.event
- A number representing the observed event.
Examples
iex> predictor = Sooth.Predictor.new(9)
...> |> Sooth.Predictor.observe(0, 3)
...> |> Sooth.Predictor.observe(0, 3)
...> |> Sooth.Predictor.observe(0, 5)
...> |> Sooth.Predictor.observe(1, 2)
...> |> Sooth.Predictor.observe(1, 3)
...> |> Sooth.Predictor.observe(1, 4)
iex> Sooth.Predictor.surprise(predictor, 0, 3)
0.5849625007211563
iex> Sooth.Predictor.surprise(predictor, 0, 4)
nil
iex> Sooth.Predictor.surprise(predictor, 1, 2)
1.5849625007211563
uncertainty(predictor, id)
Return a number indicating how uncertain the predictor is about which event is likely to be observed after the given context. Note that nil will be returned if the context has never been observed.
Returns:
The uncertainty, which is calculated to be the Shannon entropy of the distribution
over the context.
Parameters
predictor
- The predictor that will calculate the uncertainty.id
- A number that provides a context for observations.
Examples
iex> predictor = Sooth.Predictor.new(0)
...> |> Sooth.Predictor.observe(0, 3)
...> |> Sooth.Predictor.observe(0, 3)
...> |> Sooth.Predictor.observe(0, 4)
...> |> Sooth.Predictor.observe(0, 5)
...> |> Sooth.Predictor.observe(1, 2)
...> |> Sooth.Predictor.observe(1, 3)
...> |> Sooth.Predictor.observe(1, 4)
iex> Sooth.Predictor.uncertainty(predictor, 0)
1.5
iex> Sooth.Predictor.uncertainty(predictor, 1)
1.584962500721156
iex> Sooth.Predictor.uncertainty(predictor, 2)
nil