**commit** a64c23d44e41f344b2cd9dae96b5f057e7f70cc7
**parent** f3a20123ca4a37bd282fd16721e9148f53d171a3
**Author:** Jared Tobin <jared@jtobin.ca>
**Date:** Tue, 6 Oct 2015 21:28:30 +1300
Documentation updates.
**Diffstat:**

1 file changed, 34 insertions(+), 1 deletion(-)

**diff --git a/Data/Sampling/Types.hs b/Data/Sampling/Types.hs**
@@ -1,6 +1,34 @@
{-# OPTIONS_GHC -Wall #-}
{-# LANGUAGE RecordWildCards #-}
+-- |
+-- Module: Data.Sampling.Types
+-- Copyright: (c) 2015 Jared Tobin
+-- License: MIT
+--
+-- Maintainer: Jared Tobin <jared@jtobin.ca>
+-- Stability: unstable
+-- Portability: ghc
+--
+-- Common types for implementing Markov Chain Monte Carlo (MCMC) algorithms.
+--
+-- 'Target' is a product type intended to hold a log-target density function and
+-- potentially its gradient.
+--
+-- The 'Chain' type represents a kind of annotated parameter space.
+-- Technically all that's required here is the type of the parameter space
+-- itself (held here in 'chainPosition') but in practice some additional
+-- information is typically useful. Additionally there is 'chainScore' for
+-- holding the most recent score of the chain, as well as the target itself for
+-- implementing things like annealing. The `chainTunables` field can be used
+-- to hold arbitrary data.
+--
+-- One should avoid exploiting these features to do something nasty (like, say,
+-- invalidating the Markov property).
+--
+-- The 'Transition' type permits probabilistic transitions over some state
+-- space by way of the underlying 'Prob' monad.
+
module Data.Sampling.Types (
Transition
, Chain(..)
@@ -10,7 +38,9 @@ module Data.Sampling.Types (
import Control.Monad.Trans.State.Strict (StateT)
import System.Random.MWC.Probability (Prob)
--- | A transition operator.
+-- | A generic transition operator.
+--
+-- Has access to randomness via the underlying 'Prob' monad.
type Transition m a = StateT a (Prob m) ()
-- | The @Chain@ type specifies the state of a Markov chain at any given
@@ -27,6 +57,9 @@ instance Show a => Show (Chain a b) where
-- | A @Target@ consists of a function from parameter space to the reals, as
-- well as possibly a gradient.
+--
+-- Most implementations assume a /log/-target, so records are named
+-- accordingly.
data Target a = Target {
lTarget :: a -> Double
, glTarget :: Maybe (a -> a)