declarative

DIY Markov Chains
git clone git://git.jtobin.io/declarative.git
Log | Files | Refs | README | LICENSE

README.md (2986B)

      1 # declarative
      2 
      3 [![Build Status](https://secure.travis-ci.org/jtobin/declarative.png)](http://travis-ci.org/jtobin/declarative)
      4 [![Hackage Version](https://img.shields.io/hackage/v/declarative.svg)](http://hackage.haskell.org/package/declarative)
      5 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jtobin/declarative/blob/master/LICENSE)
      6 
      7 
      8 DIY Markov Chains.
      9 
     10 ## What is this
     11 
     12 This package presents a simple combinator language for Markov transition
     13 operators that are useful in MCMC.
     14 
     15 Any transition operators sharing the same stationary distribution and obeying
     16 the Markov and reversibility properties can be combined in a couple of ways,
     17 such that the resulting operator preserves the stationary distribution and
     18 desirable properties amenable for MCMC.
     19 
     20 We can deterministically concatenate operators end-to-end, or sample from
     21 a collection of them according to some probability distribution.  See
     22 [Geyer, 2005](http://www.stat.umn.edu/geyer/f05/8931/n1998.pdf) for details.
     23 
     24 The result is a simple grammar for building composite, property-preserving
     25 transition operators from existing ones:
     26 
     27     transition ::= primitive <transition>
     28                  | concatT transition transition
     29                  | sampleT transition transition
     30 
     31 This library also re-exports a number of production-quality transition
     32 operators from the
     33 [mighty-metropolis](https://hackage.haskell.org/package/mighty-metropolis),
     34 [speedy-slice](https://hackage.haskell.org/package/speedy-slice), and
     35 [hasty-hamiltonian](https://hackage.haskell.org/package/hasty-hamiltonian) libraries.
     36 
     37 Markov chains can then be run over arbitrary `Target`s using whatever
     38 transition operator is desired.
     39 
     40     import Numeric.MCMC
     41     import Data.Sampling.Types
     42 
     43     target :: [Double] -> Double
     44     target [x0, x1] = negate (5  *(x1 - x0 ^ 2) ^ 2 + 0.05 * (1 - x0) ^ 2)
     45 
     46     rosenbrock :: Target [Double]
     47     rosenbrock = Target target Nothing
     48 
     49     transition :: Transition IO (Chain [Double] b)
     50     transition =
     51       concatT
     52         (sampleT (metropolis 0.5) (metropolis 1.0))
     53         (sampleT (slice 2.0) (slice 3.0))
     54 
     55     main :: IO ()
     56     main = withSystemRandom . asGenIO $ mcmc 10000 [0, 0] transition rosenbrock
     57 
     58 ![trace](https://dl.dropboxusercontent.com/spa/u0s6617yxinm2ca/b2w56upc.png)
     59 
     60 ## Installation
     61 
     62 Installing is best done via [stack](http://haskellstack.org), which will pull
     63 down everything you might need (including GHC).
     64 
     65 ```
     66 $ stack install declarative
     67 ```
     68 
     69 If you want to grab the test suite/examples, grab the repo and build via
     70 
     71 ```
     72 git clone git@github.com:jtobin/declarative.git
     73 cd declarative
     74 stack build
     75 ```
     76 
     77 You can then run the test suite via `stack test`.
     78 
     79 ## Documentation & Examples
     80 
     81 Check out the haddock-generated docs on
     82 [Hackage](https://hackage.haskell.org/package/declarative).
     83 
     84 You can also peruse the introductory [announce
     85 post](https://medium.com/@jaredtobin/a-framework-for-markov-chain-monte-carlo-3fc40df45592).
     86 
     87 ## Etc.
     88 
     89 PRs and issues welcome.
     90