Sooth.Predictor (Sooth v0.2.1)

Provides the Predictor module for Sooth.

This is the main entry point for the Sooth library.

Summary

Types

t()

A Predictor of error_event/contexts

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

Link to this function

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
Link to this function

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
Link to this function

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.

Link to this function

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
Link to this function

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([])}
Link to this function

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
Link to this function

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()}
Link to this function

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
Link to this function

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
Link to this function

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
Link to this function

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