RandomChoiceLink
The RandomChoiceLink is a type of FunctionLink that, when executed, returns one of its members, using a uniform distribution. For example,
(cog-execute! (RandomChoice (Concept "A") (Concept "B")))
will return A half the time, and B half the time. Selection weights can be specified in one of two different formats; one of the two formats is particularly convenient for use with the GetLink; the other is a more traditional transpose of the first. Most convenient for the GetLink is a SetLink of weight-atom pairs:
RandomChoice SetLink List <number> <atom> ... List <number> <atom>
where <number> evaluates to a NumberNode, specifying a weight for making that selection, and <atom> is the atom to be selected. The alternate format is a transpose of the above:
RandomChoice List <number> ... <number> List <atom> ... <atom>
The above form requires that the two lists be exactly the same length. The probability of selecting an item is in proportion to the weights; that is, the probability is equal to the weight divided by the sum of the weights. For example:
(cog-execute!
(RandomChoice
(List (Number 1) (Number 3))
(List (Concept "A") (Concept "B"))))
will pick A one out of four times, and B three out of four times (where four = 1+3). Another example:
(DefineLink (DefinedSchema "pairs")
(RandomChoice
(SetLink
(ListLink (Number 1) (Concept "AAA"))
(ListLink (Number 1) (Concept "BBB"))
(ListLink (Number 0.1) (Concept "CCC")) )))
(cog-execute! (DefinedSchema "pairs"))
will pick AAA and BBB 1/2.1=0.4762... of the time and will pick CCC 0.1/2.1=0.0476... of the time.
