declarative

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

README.md (2626B)

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