A module containing the central type of the library, `EventM`

, and various
related helper functions.

- data EventM a
- makeEvent :: [a] -> EventM a
- makeEventProb :: (Ord a, Real prob) => [(a, prob)] -> EventM a
- outcomes :: Ord a => EventM a -> [(a, Rational)]
- enact :: EventM a -> IO a
- coinToss :: EventM Bool
- subst :: Eq a => a -> a -> EventM a -> EventM a
- compareEvent :: Ord a => EventM a -> EventM a -> Map Ordering Rational

# Documentation

A probabilistic event with an outcome of type `a`

. See the `enact`

function
to actually run the event and randomly pick an outcome.

For an explanation of the `Num`

instance, see the DieRoll type in the Numeric.Probability.Game.Dice
module.

The `Eq`

instance compares the two distributions to see if they are equal.
This looks at all the outcomes and sees if their probabilities are equal on
the left-hand side and the right-hand side. For example,
`coinToss == fmap (>= 4) d6`

, but `d12 /= d6 + d6`

.

The `Show`

instance will display a horizontal bar-chart of relative outcome
probability. Note: this really is a relative probability -- common factors
are cancelled, and is not a count of the different outcomes. If you wish to
show the raw numbers, use `show . outcomes`

instead.

The `Functor`

instance allows you to modify the outcome values without changing
their associated probabilities. For example, `fmap show d6`

changes the outcomes
into their String representations.

The `Applicative`

instance allows you to join together the results of two events
in a predetermined manner. For example, `makeEvent [id, (* 2)] <*> d6`

allows
you to roll a d6 that has a 50% chance of being doubled. Note that ```
pure
6
```

is an event that is certain to produce the outcome 6.

The `Monad`

instance allows you to base the choice of the next event on the
result of the previous event. For example, ```
coinToss >>= x -> if x then d6
else d4
```

will roll a d4 50% of the time and a d6 the other 50%. Note that ```
return
6
```

is an event that is certain to produce the outcome 6.

makeEvent :: [a] -> EventM aSource

Makes an event that has an equal chance of taking on the value of each
entry in the list. Note that duplicates in the list are permitted and do
have an effect: `makeEvent [True, False]`

has a 50% chance of giving a True
result, but `makeEvent [True, True, False, False, False]`

only has a 40%
chance of giving a True result. If you do not want this behaviour, use
`makeEvent . nub`

to remove duplicates.

The result of passing the empty list is undefined.

makeEventProb :: (Ord a, Real prob) => [(a, prob)] -> EventM aSource

Given a list of events and their associated probabilities, forms a corresponding event. The probabilities must be non-negative. If the probabilities do not sum to one, they are all scaled linearly so that their sum is one. Duplicate items will have their probabilities added.

The result of passing the empty list, a list containing negative probabilities, or a list where all the probabilities are zero is undefined.

outcomes :: Ord a => EventM a -> [(a, Rational)]Source

Gets a list of all the outcomes of the event and their associated probability. You can be sure that the probabilities will all sum to 1, and that there will only be one item in the list per outcome. It is possible that some of the outcomes in the list will have zero probability.

enact :: EventM a -> IO aSource

Actually enacts the event and produces a single result according to the probabilities
in the `EventM a`

parameter.

An event with a 50% chance of giving True, and a 50% chance of giving False.

subst :: Eq a => a -> a -> EventM a -> EventM aSource

If the `EventM a`

parameter returns a result equal to the first parameter,
it is changed to be the second parameter; otherwise it is left untouched. For
example `replace 4 8 d4`

has an equal chance of producing the outcomes 1, 2,
3 and 8, `replace 10 0 d10 == z10`

, and `replace 10 20 d6 == d6`

.

compareEvent :: Ord a => EventM a -> EventM a -> Map Ordering RationalSource

Compares the outcomes of the two events, and works out the probability associated with the first outcome being greater than, equal to or less than the second outcome. The probabilites for each are returned in an associative map.

Added in version 1.1.