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.address_set — Function.

addrs::AddressSet = address_set(choices::ChoiceMap)

Return an AddressSet containing the addresses of values in the given assignment.

source

Note that none of these methods mutate the assignment.

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

Dynamic Choice Map

One concrete assignment type is DynamicChoiceMap, which is mutable. Users construct DynamicChoiceMaps and populate them for use as observations or constraints, e.g.:

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

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

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

choicemap
set_value!
set_submap!