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