Choice Maps

Maps from the addresses of random choices to their values are stored in associative tree-structured data structures that have the following abstract type:

Gen.ChoiceMap — Type.

abstract type ChoiceMap end

Abstract type for maps from hierarchical addresses to values.

source

Choice maps are constructed by users to express observations and/or constraints on the traces of generative functions. Choice maps are also returned by certain Gen inference methods, and are used internally by various Gen inference methods.

Choice maps provide the following methods:

Gen.has_value — Function.

has_value(choices::ChoiceMap, addr)

Return true if there is a value at the given address.

source

Gen.get_value — Function.

value = get_value(choices::ChoiceMap, addr)

Return the value at the given address in the assignment, or throw a KeyError if no value exists. A syntactic sugar is Base.getindex:

value = choices[addr]

source

Gen.get_submap — Function.

submap = get_submap(choices::ChoiceMap, addr)

Return the sub-assignment containing all choices whose address is prefixed by addr.

It is an error if the assignment contains a value at the given address. If there are no choices whose address is prefixed by addr then return an EmptyChoiceMap.

source

Gen.get_values_shallow — Function.

key_submap_iterable = get_values_shallow(choices::ChoiceMap)

Return an iterable collection of tuples (key, value) for each top-level key associated with a value.

source

Gen.get_submaps_shallow — Function.

key_submap_iterable = get_submaps_shallow(choices::ChoiceMap)

Return an iterable collection of tuples (key, submap::ChoiceMap) for each top-level key that has a non-empty sub-assignment.

source

Gen.to_array — Function.

arr::Vector{T} = to_array(choices::ChoiceMap, ::Type{T}) where {T}

Populate an array with values of choices in the given assignment.

It is an error if each of the values cannot be coerced into a value of the given type.

Implementation

To support to_array, a concrete subtype T <: ChoiceMap should implement the following method:

n::Int = _fill_array!(choices::T, arr::Vector{V}, start_idx::Int) where {V}

Populate arr with values from the given assignment, starting at start_idx, and return the number of elements in arr that were populated.

source

Gen.from_array — Function.

choices::ChoiceMap = from_array(proto_choices::ChoiceMap, arr::Vector)

Return an assignment with the same address structure as a prototype assignment, but with values read off from the given array.

The order in which addresses are populated is determined by the prototype assignment. It is an error if the number of choices in the prototype assignment is not equal to the length the array.

Implementation

To support from_array, a concrete subtype T <: ChoiceMap should implement the following method:

(n::Int, choices::T) = _from_array(proto_choices::T, arr::Vector{V}, start_idx::Int) where {V}

Return an assignment with the same address structure as a prototype assignment, but with values read off from arr, starting at position start_idx, and the number of elements read from arr.

source

Gen.get_selected — Function.

selected_choices = get_selected(choices::ChoiceMap, selection::Selection)

Filter the choice map to include only choices in the given selection.

Returns a new choice map.

source

Note that none of these methods mutate the choice map.

Choice maps also implement:

Base.isempty, which tests of there are no random choices in the choice map
Base.merge, which takes two choice maps, and returns a new choice map containing all random choices in either choice map. It is an error if the choice maps both have values at the same address, or if one choice map has a value at an address that is the prefix of the address of a value in the other choice map.
==, which tests if two choice maps have the same addresses and values at those addresses.

Mutable Choice Maps

A mutable choice map can be constructed with choicemap, and then populated:

choices = choicemap()
choices[:x] = true
choices["foo"] = 1.25
choices[:y => 1 => :z] = -6.3

There is also a constructor that takes initial (address, value) pairs:

choices = choicemap((:x, true), ("foo", 1.25), (:y => 1 => :z, -6.3))

Gen.choicemap — Function.

choices = choicemap()

Construct an empty mutable choice map.

source

choices = choicemap(tuples...)

Construct a mutable choice map initialized with given address, value tuples.

source

Gen.set_value! — Function.

set_value!(choices::DynamicChoiceMap, addr, value)

Set the given value for the given address.

Will cause any previous value or sub-assignment at this address to be deleted. It is an error if there is already a value present at some prefix of the given address.

The following syntactic sugar is provided:

choices[addr] = value

source

Gen.set_submap! — Function.

set_submap!(choices::DynamicChoiceMap, addr, submap::ChoiceMap)

Replace the sub-assignment rooted at the given address with the given sub-assignment. Set the given value for the given address.

Will cause any previous value or sub-assignment at the given address to be deleted. It is an error if there is already a value present at some prefix of address.

source